xref: /freebsd/bin/ps/ps.1 (revision 380a989b3223d455375b4fae70fd0b9bdd43bafb)
1.\" Copyright (c) 1980, 1990, 1991, 1993, 1994
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\"    must display the following acknowledgement:
14.\"	This product includes software developed by the University of
15.\"	California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     @(#)ps.1	8.3 (Berkeley) 4/18/94
33.\"	$Id: ps.1,v 1.18 1998/06/04 06:46:13 jkoshy Exp $
34.\"
35.Dd April 18, 1994
36.Dt PS 1
37.Os BSD 4
38.Sh NAME
39.Nm ps
40.Nd process status
41.Sh SYNOPSIS
42.Nm ps
43.Op Fl aCcefhjlmrSTuvwx
44.Op Fl M Ar core
45.Op Fl N Ar system
46.Op Fl O Ar fmt
47.Op Fl o Ar fmt
48.Op Fl p Ar pid
49.Op Fl t Ar tty
50.Op Fl U Ar username
51.Op Fl W Ar swap
52.Nm ps
53.Op Fl L
54.Sh DESCRIPTION
55.Nm Ps
56displays a header line followed by lines containing information about your
57processes that have controlling terminals.
58This information is sorted by controlling terminal, then by process
59.Tn ID .
60.Pp
61The information displayed is selected based on a set of keywords (see the
62.Fl L
63.Fl O
64and
65.Fl o
66options).
67The default output format includes, for each process, the process'
68.Tn ID ,
69controlling terminal, cpu time (including both user and system time),
70state, and associated command.
71.Pp
72The process file system (see
73.Xr procfs 5
74\&) should be mounted when
75.Nm
76is executed, otherwise not all information will be available.
77.Pp
78The options are as follows:
79.Bl -tag -width indent
80.It Fl a
81Display information about other users' processes as well as your own.
82.It Fl c
83Change the ``command'' column output to just contain the executable name,
84rather than the full command line.
85.It Fl C
86Change the way the cpu percentage is calculated by using a ``raw''
87cpu calculation that ignores ``resident'' time (this normally has
88no effect).
89.It Fl e
90Display the environment as well.
91.It Fl f
92Show commandline and environment information about swapped out processes.
93This option is honored only if the uid of the user is 0.
94.It Fl h
95Repeat the information header as often as necessary to guarantee one
96header per page of information.
97.It Fl j
98Print information associated with the following keywords:
99user, pid, ppid, pgid, sess, jobc, state, tt, time and command.
100.It Fl L
101List the set of available keywords.
102.It Fl l
103Display information associated with the following keywords:
104uid, pid, ppid, cpu, pri, nice, vsz, rss, wchan, state, tt, time
105and command.
106.It Fl M
107Extract values associated with the name list from the specified core
108instead of the default
109.Pa /dev/kmem .
110.It Fl m
111Sort by memory usage, instead of by process
112.Tn ID .
113.It Fl N
114Extract the name list from the specified system instead of the default
115.Pa /kernel .
116.It Fl O
117Add the information associated with the space or comma separated list
118of keywords specified, after the process
119.Tn ID ,
120in the default information
121display.
122Keywords may be appended with an equals (``='') sign and a string.
123This causes the printed header to use the specified string instead of
124the standard header.
125.It Fl o
126Display information associated with the space or comma separated list
127of keywords specified.
128Keywords may be appended with an equals (``='') sign and a string.
129This causes the printed header to use the specified string instead of
130the standard header.
131.It Fl p
132Display information associated with the specified process
133.Tn ID .
134.It Fl r
135Sort by current cpu usage, instead of by process
136.Tn ID .
137.It Fl S
138Change the way the process time is calculated by summing all exited
139children to their parent process.
140.It Fl T
141Display information about processes attached to the device associated
142with the standard input.
143.It Fl t
144Display information about processes attached to the specified terminal
145device.
146.It Fl U
147Display the processes belonging to the specified
148.Tn username .
149.It Fl u
150Display information associated with the following keywords:
151user, pid, %cpu, %mem, vsz, rss, tt, state, start, time and command.
152The
153.Fl u
154option implies the
155.Fl r
156option.
157.It Fl v
158Display information associated with the following keywords:
159pid, state, time, sl, re, pagein, vsz, rss, lim, tsiz,
160%cpu, %mem and command.
161The
162.Fl v
163option implies the
164.Fl m
165option.
166.It Fl W
167Extract swap information from the specified file instead of the
168default
169.Pa /dev/drum .
170.It Fl w
171Use 132 columns to display information, instead of the default which
172is your window size.
173If the
174.Fl w
175option is specified more than once,
176.Nm
177will use as many columns as necessary without regard for your window size.
178.It Fl x
179Display information about processes without controlling terminals.
180.El
181.Pp
182A complete list of the available keywords are listed below.
183Some of these keywords are further specified as follows:
184.Bl -tag -width indent
185.It %cpu
186The cpu utilization of the process; this is a decaying average over up to
187a minute of previous (real) time.
188Since the time base over which this is computed varies (since processes may
189be very young) it is possible for the sum of all
190.Tn \&%CPU
191fields to exceed 100%.
192.It %mem
193The percentage of real memory used by this process.
194.It flags
195The flags associated with the process as in
196the include file
197.Aq Pa sys/proc.h :
198.Bl -column P_NOCLDSTOP P_NOCLDSTOP
199.It Dv "P_ADVLOCK" Ta No "0x00001	Process may hold a POSIX advisory lock"
200.It Dv "P_CONTROLT" Ta No "0x00002	Has a controlling terminal"
201.It Dv "P_INMEM" Ta No "0x00004		Loaded into memory"
202.It Dv "P_NOCLDSTOP" Ta No "0x00008	No SIGCHLD when children stop"
203.It Dv "P_PPWAIT" Ta No "0x00010	Parent is waiting for child to exec/exit"
204.It Dv "P_PROFIL" Ta No "0x00020	Has started profiling"
205.It Dv "P_SELECT" Ta No "0x00040	Selecting; wakeup/waiting danger"
206.It Dv "P_SINTR" Ta No "0x00080		Sleep is interruptible"
207.It Dv "P_SUGID" Ta No "0x00100		Had set id privileges since last exec"
208.It Dv "P_SYSTEM" Ta No "0x00200	System proc: no sigs, stats or swapping"
209.It Dv "P_TIMEOUT" Ta No "0x00400	Timing out during sleep"
210.It Dv "P_TRACED" Ta No "0x00800	Debugged process being traced"
211.It Dv "P_WAITED" Ta No "0x01000	Debugging process has waited for child"
212.It Dv "P_WEXIT" Ta No "0x02000		Working on exiting"
213.It Dv "P_EXEC" Ta No "0x04000		Process called exec"
214.It Dv "P_NOSWAP" Ta No "0x08000	Another flag to prevent swap out"
215.It Dv "P_PHYSIO" Ta No "0x10000	Doing physical I/O"
216.It Dv "P_OWEUPC" Ta No "0x20000	Owe process an addupc() call at next ast"
217.It Dv "P_SWAPPING" Ta No "0x40000	Process is being swapped"
218.El
219.It lim
220The soft limit on memory used, specified via a call to
221.Xr setrlimit 2 .
222.It lstart
223The exact time the command started, using the ``%c'' format described in
224.Xr strftime 3 .
225.It nice
226The process scheduling increment (see
227.Xr setpriority 2 ) .
228.It rss
229the real memory (resident set) size of the process (in 1024 byte units).
230.It start
231The time the command started.
232If the command started less than 24 hours ago, the start time is
233displayed using the ``%l:ps.1p'' format described in
234.Xr strftime 3 .
235If the command started less than 7 days ago, the start time is
236displayed using the ``%a6.15p'' format.
237Otherwise, the start time is displayed using the ``%e%b%y'' format.
238.It state
239The state is given by a sequence of letters, for example,
240.Dq Tn RWNA .
241The first letter indicates the run state of the process:
242.Pp
243.Bl -tag -width indent -compact
244.It D
245Marks a process in disk (or other short term, uninterruptible) wait.
246.It I
247Marks a process that is idle (sleeping for longer than about 20 seconds).
248.It R
249Marks a runnable process.
250.It S
251Marks a process that is sleeping for less than about 20 seconds.
252.It T
253Marks a stopped process.
254.It Z
255Marks a dead process (a ``zombie'').
256.El
257.Pp
258Additional characters after these, if any, indicate additional state
259information:
260.Pp
261.Bl -tag -width indent -compact
262.It +
263The process is in the foreground process group of its control terminal.
264.It <
265The process has raised
266.Tn CPU
267scheduling priority.
268.It >
269The process has specified a soft limit on memory requirements and is
270currently exceeding that limit; such a process is (necessarily) not
271swapped.
272.It A
273the process has asked for random page replacement
274.Pf ( Dv VA_ANOM ,
275from
276.Xr vadvise 2 ,
277for example,
278.Xr lisp 1
279in a garbage collect).
280.It E
281The process is trying to exit.
282.It L
283The process has pages locked in core (for example, for raw
284.Tn I/O ) .
285.It N
286The process has reduced
287.Tn CPU
288scheduling priority (see
289.Xr setpriority 2 ) .
290.It S
291The process has asked for
292.Tn FIFO
293page replacement
294.Pf ( Dv VA_SEQL ,
295from
296.Xr vadvise 2 ,
297for example, a large image processing program using virtual memory to
298sequentially address voluminous data).
299.It s
300The process is a session leader.
301.It V
302The process is suspended during a
303.Xr vfork .
304.It W
305The process is swapped out.
306.It X
307The process is being traced or debugged.
308.El
309.It tt
310An abbreviation for the pathname of the controlling terminal, if any.
311The abbreviation consists of the three letters following
312.Pa /dev/tty ,
313or, for the console, ``con''.
314This is followed by a ``-'' if the process can no longer reach that
315controlling terminal (i.e., it has been revoked).
316.It wchan
317The event (an address in the system) on which a process waits.
318When printed numerically, the initial part of the address is
319trimmed off and the result is printed in hex, for example, 0x80324000 prints
320as 324000.
321.El
322.Pp
323When printing using the command keyword, a process that has exited and
324has a parent that has not yet waited for the process (in other words, a zombie)
325is listed as ``<defunct>'', and a process which is blocked while trying
326to exit is listed as ``<exiting>''.
327.Nm Ps
328makes an educated guess as to the file name and arguments given when the
329process was created by examining memory or the swap area.
330The method is inherently somewhat unreliable and in any event a process
331is entitled to destroy this information, so the names cannot be depended
332on too much.
333The ucomm (accounting) keyword can, however, be depended on.
334.Sh KEYWORDS
335The following is a complete list of the available keywords and their
336meanings.
337Several of them have aliases (keywords which are synonyms).
338.Pp
339.Bl -tag -width sigignore -compact
340.It %cpu
341percentage cpu usage (alias pcpu)
342.It %mem
343percentage memory usage (alias pmem)
344.It acflag
345accounting flag (alias acflg)
346.It command
347command and arguments
348.It cpu
349short-term cpu usage factor (for scheduling)
350.It flags
351the process flags, in hexadecimal (alias f)
352.It inblk
353total blocks read (alias inblock)
354.It jobc
355job control count
356.It ktrace
357tracing flags
358.It ktracep
359tracing vnode
360.It lim
361memoryuse limit
362.It logname
363login name of user who started the process
364.It lstart
365time started
366.It majflt
367total page faults
368.It minflt
369total page reclaims
370.It msgrcv
371total messages received (reads from pipes/sockets)
372.It msgsnd
373total messages sent (writes on pipes/sockets)
374.It nice
375nice value (alias ni)
376.It nivcsw
377total involuntary context switches
378.It nsigs
379total signals taken (alias nsignals)
380.It nswap
381total swaps in/out
382.It nvcsw
383total voluntary context switches
384.It nwchan
385wait channel (as an address)
386.It oublk
387total blocks written (alias oublock)
388.It p_ru
389resource usage (valid only for zombie)
390.It paddr
391swap address
392.It pagein
393pageins (same as majflt)
394.It pgid
395process group number
396.It pid
397process
398.Tn ID
399.It poip
400pageouts in progress
401.It ppid
402parent process
403.Tn ID
404.It pri
405scheduling priority
406.It re
407core residency time (in seconds; 127 = infinity)
408.It rgid
409real group
410.Tn ID
411.It rlink
412reverse link on run queue, or 0
413.It rss
414resident set size
415.It rsz
416resident set size + (text size / text use count) (alias rssize)
417.It rtprio
418realtime priority (101 = not a realtime process)
419.It ruid
420real user
421.Tn ID
422.It ruser
423user name (from ruid)
424.It sess
425session pointer
426.It sig
427pending signals (alias pending)
428.It sigcatch
429caught signals (alias caught)
430.It sigignore
431ignored signals (alias ignored)
432.It sigmask
433blocked signals (alias blocked)
434.It sl
435sleep time (in seconds; 127 = infinity)
436.It start
437time started
438.It state
439symbolic process state (alias stat)
440.It svgid
441saved gid from a setgid executable
442.It svuid
443saved uid from a setuid executable
444.It tdev
445control terminal device number
446.It time
447accumulated cpu time, user + system (alias cputime)
448.It tpgid
449control terminal process group
450.Tn ID
451.\".It trss
452.\"text resident set size (in Kbytes)
453.It tsess
454control terminal session pointer
455.It tsiz
456text size (in Kbytes)
457.It tt
458control terminal name (two letter abbreviation)
459.It tty
460full name of control terminal
461.It uprocp
462process pointer
463.It ucomm
464name to be used for accounting
465.It uid
466effective user
467.Tn ID
468.It upr
469scheduling priority on return from system call (alias usrpri)
470.It user
471user name (from uid)
472.It vsz
473virtual size in Kbytes (alias vsize)
474.It wchan
475wait channel (as a symbolic name)
476.It xstat
477exit or stop status (valid only for stopped or zombie process)
478.El
479.Sh FILES
480.Bl -tag -width /var/db/kvm_kernel.db -compact
481.It Pa /dev
482special files and device names
483.It Pa /dev/drum
484default swap device
485.It Pa /dev/kmem
486default kernel memory
487.It Pa /var/run/dev.db
488/dev name database
489.It Pa /var/db/kvm_kernel.db
490system namelist database
491.It Pa /kernel
492default system namelist
493.It Pa /proc
494the mount point of
495.Xr procfs 5
496.El
497.Sh SEE ALSO
498.Xr kill 1 ,
499.Xr w 1 ,
500.Xr kvm 3 ,
501.Xr strftime 3 ,
502.Xr procfs 5 ,
503.Xr pstat 8
504.Sh BUGS
505Since
506.Nm
507cannot run faster than the system and is run as any other scheduled
508process, the information it displays can never be exact.
509