ps: Update man page for adding comm as an alias for ucomm.
[dragonfly.git] / bin / ps / ps.1
CommitLineData
984263bc
MD
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.\" $FreeBSD: src/bin/ps/ps.1,v 1.24.2.7 2002/06/20 22:43:33 charnier Exp $
8e1c6f81 34.\" $DragonFly: src/bin/ps/ps.1,v 1.20 2008/09/02 11:50:45 matthias Exp $
984263bc 35.\"
8e1c6f81 36.Dd September 2, 2008
984263bc
MD
37.Dt PS 1
38.Os
39.Sh NAME
40.Nm ps
41.Nd process status
42.Sh SYNOPSIS
43.Nm
ee5f7d37 44.Op Fl aCcefHhjlmrRSTuvwx
984263bc
MD
45.Op Fl M Ar core
46.Op Fl N Ar system
47.Op Fl O Ar fmt
48.Op Fl o Ar fmt
49.Op Fl p Ar pid
50.Op Fl t Ar tty
51.Op Fl U Ar username
52.Nm
53.Op Fl L
54.Sh DESCRIPTION
55The
56.Nm
57utility
58displays a header line followed by lines containing information about your
59processes that have controlling terminals.
ab7ed900 60This information is sorted by controlling terminal, then by process ID.
984263bc
MD
61.Pp
62The information displayed is selected based on a set of keywords (see the
63.Fl L
64.Fl O
65and
66.Fl o
67options).
ab7ed900
SW
68The default output format includes, for each process, the process' ID,
69controlling terminal, CPU time (including both user and system time),
984263bc
MD
70state, and associated command.
71.Pp
72The process file system (see
73.Xr procfs 5 )
74should 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.
82This can be disabled by setting the
c49ea21f 83.Va security.ps_showallprocs
984263bc
MD
84sysctl to zero.
85.It Fl c
86Change the ``command'' column output to just contain the executable name,
87rather than the full command line.
88.It Fl C
ab7ed900
SW
89Change the way the CPU percentage is calculated by using a ``raw''
90CPU calculation that ignores ``resident'' time (this normally has
984263bc
MD
91no effect).
92.It Fl e
93Display the environment as well.
94.It Fl f
95Show commandline and environment information about swapped out processes.
96This option is honored only if the uid of the user is 0.
2b0645c3
MD
97.It Fl H
98Print one line per lightweight process (LWP) instead of one line per process.
99When this option is set and the
100.Fl o
101option is not set, the
102.Cm tid
103column is inserted in the output format after the
104.Cm pid
105one.
984263bc
MD
106.It Fl h
107Repeat the information header as often as necessary to guarantee one
108header per page of information.
109.It Fl j
110Print information associated with the following keywords:
c39f3bbe
SW
111.Cm user , pid , ppid , pgid , sess , jobc , state , tt , time ,
112and
113.Cm command .
984263bc
MD
114.It Fl L
115List the set of available keywords.
116.It Fl l
117Display information associated with the following keywords:
c39f3bbe
SW
118.Cm uid , pid , ppid , cpu , pri , nice , vsz , rss , wchan , state ,
119.Cm tt , time ,
120and
121.Cm command .
984263bc
MD
122.It Fl M
123Extract values associated with the name list from the specified core
124instead of the default
125.Pa /dev/kmem .
126.It Fl m
ab7ed900 127Sort by memory usage, instead of by process ID.
984263bc
MD
128.It Fl N
129Extract the name list from the specified system instead of the default
8e1c6f81 130.Pa /boot/kernel .
984263bc
MD
131.It Fl O
132Add the information associated with the space or comma separated list
ab7ed900 133of keywords specified, after the process ID,
984263bc
MD
134in the default information
135display.
136Keywords may be appended with an equals (``='') sign and a string.
137This causes the printed header to use the specified string instead of
138the standard header.
139.It Fl o
140Display information associated with the space or comma separated list
141of keywords specified.
142Keywords may be appended with an equals (``='') sign and a string.
143This causes the printed header to use the specified string instead of
144the standard header.
145.It Fl p
ab7ed900 146Display information associated with the specified process ID.
984263bc 147.It Fl r
ab7ed900 148Sort by current CPU usage, instead of by process ID.
ee5f7d37
MD
149.It Fl R
150Subsort by parent/child chain. This very useful option makes
151the parent/child associations clear and understandable.
984263bc
MD
152.It Fl S
153Change the way the process time is calculated by summing all exited
154children to their parent process.
155.It Fl T
156Display information about processes attached to the device associated
157with the standard input.
158.It Fl t
159Display information about processes attached to the specified terminal
160device.
161.It Fl U
162Display the processes belonging to the specified
163.Ar username .
164.It Fl u
165Display information associated with the following keywords:
c39f3bbe
SW
166.Cm user , pid, %cpu , %mem , vsz , rss , tt , state , start , time ,
167and
168.Cm command .
984263bc
MD
169The
170.Fl u
171option implies the
172.Fl r
173option.
174.It Fl v
175Display information associated with the following keywords:
c39f3bbe
SW
176.Cm pid , state , time , sl , re , pagein , vsz , rss , lim , tsiz ,
177.Cm %cpu , %mem
178and
179.Cm command .
984263bc
MD
180The
181.Fl v
182option implies the
183.Fl m
184option.
185.It Fl w
186Use 132 columns to display information, instead of the default which
187is your window size.
188If the
189.Fl w
190option is specified more than once,
191.Nm
192will use as many columns as necessary without regard for your window size.
193.It Fl x
194Display information about processes without controlling terminals.
195.El
196.Pp
197A complete list of the available keywords are listed below.
198Some of these keywords are further specified as follows:
c39f3bbe
SW
199.Bl -tag -width ".Cm lstart"
200.It Cm %cpu
ab7ed900 201The CPU utilization of the process; this is a decaying average over up to
984263bc
MD
202a minute of previous (real) time.
203Since the time base over which this is computed varies (since processes may
204be very young) it is possible for the sum of all
c39f3bbe 205.Cm %cpu
984263bc 206fields to exceed 100%.
c39f3bbe 207.It Cm %mem
984263bc 208The percentage of real memory used by this process.
c39f3bbe 209.It Cm flags
984263bc
MD
210The flags associated with the process as in
211the include file
9a379a4a 212.In sys/proc.h .
c39f3bbe 213.It Cm lim
984263bc
MD
214The soft limit on memory used, specified via a call to
215.Xr setrlimit 2 .
c39f3bbe 216.It Cm lstart
984263bc
MD
217The exact time the command started, using the ``%c'' format described in
218.Xr strftime 3 .
c39f3bbe 219.It Cm nice
984263bc
MD
220The process scheduling increment (see
221.Xr setpriority 2 ) .
c39f3bbe 222.It Cm rss
984263bc 223the real memory (resident set) size of the process (in 1024 byte units).
c39f3bbe 224.It Cm start
984263bc
MD
225The time the command started.
226If the command started less than 24 hours ago, the start time is
227displayed using the ``%l:ps.1p'' format described in
228.Xr strftime 3 .
229If the command started less than 7 days ago, the start time is
230displayed using the ``%a6.15p'' format.
231Otherwise, the start time is displayed using the ``%e%b%y'' format.
c39f3bbe 232.It Cm state
984263bc 233The state is given by a sequence of letters, for example,
c39f3bbe 234.Dq Li RWNA .
984263bc
MD
235The first letter indicates the run state of the process:
236.Pp
237.Bl -tag -width indent -compact
fac25122
MD
238.It Li B
239Marks a blocked kernel thread.
c39f3bbe 240.It Li D
984263bc 241Marks a process in disk (or other short term, uninterruptible) wait.
c39f3bbe 242.It Li I
984263bc 243Marks a process that is idle (sleeping for longer than about 20 seconds).
c39f3bbe 244.It Li J
984263bc
MD
245Marks a process which is in
246.Xr jail 2 .
247The hostname of the prison can be found in
c39f3bbe
SW
248.Pa /proc/ Ns Ao Ar pid Ac Ns Pa /status .
249.It Li R
92a93b69 250Marks a runnable process and is followed by the CPU number.
c39f3bbe 251.It Li S
984263bc 252Marks a process that is sleeping for less than about 20 seconds.
c39f3bbe 253.It Li T
984263bc 254Marks a stopped process.
c39f3bbe
SW
255.It Li Z
256Marks a dead process (a
257.Dq zombie ) .
984263bc
MD
258.El
259.Pp
260Additional characters after these, if any, indicate additional state
261information:
262.Pp
263.Bl -tag -width indent -compact
c39f3bbe 264.It Li +
984263bc 265The process is in the foreground process group of its control terminal.
c39f3bbe 266.It Li <
ab7ed900 267The process has raised CPU scheduling priority.
c39f3bbe 268.It Li >
984263bc
MD
269The process has specified a soft limit on memory requirements and is
270currently exceeding that limit; such a process is (necessarily) not
271swapped.
c39f3bbe 272.It Li A
984263bc
MD
273the process has asked for random page replacement
274.Pf ( Dv MADV_RANDOM ,
275from
276.Xr madvise 2 ,
277for example,
278.Xr lisp 1
279in a garbage collect).
c39f3bbe 280.It Li E
984263bc 281The process is trying to exit.
c39f3bbe 282.It Li L
984263bc
MD
283The process has pages locked in core (for example, for raw
284.Tn I/O ) .
c39f3bbe 285.It Li M
18988e7a
MD
286On SMP systems indicates a process or thread which is
287.Em not
288holding the MP lock (the Big Giant Lock).
c39f3bbe 289.It Li N
ab7ed900 290The process has reduced CPU scheduling priority (see
984263bc 291.Xr setpriority 2 ) .
c39f3bbe 292.It Li S
ab7ed900 293The process has asked for FIFO page replacement
984263bc
MD
294.Pf ( Dv MADV_SEQUENTIAL ,
295from
296.Xr madvise 2 ,
297for example, a large image processing program using virtual memory to
298sequentially address voluminous data).
c39f3bbe 299.It Li s
984263bc 300The process is a session leader.
c39f3bbe 301.It Li V
984263bc 302The process is suspended during a
3867d280 303.Xr vfork 2 .
c39f3bbe 304.It Li W
984263bc 305The process is swapped out.
c39f3bbe 306.It Li X
984263bc
MD
307The process is being traced or debugged.
308.El
c39f3bbe 309.It Cm tt
984263bc
MD
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).
c39f3bbe 316.It Cm wchan
984263bc
MD
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
fac25122 320as 324000. Note that blocked threads often only have ascii wchan's.
984263bc
MD
321.El
322.Pp
c39f3bbe
SW
323When printing using the
324.Cm command
325keyword, a process that has exited and
984263bc
MD
326has a parent that has not yet waited for the process (in other words, a zombie)
327is listed as ``<defunct>'', and a process which is blocked while trying
328to exit is listed as ``<exiting>''.
329The
330.Nm
331utility
332makes an educated guess as to the file name and arguments given when the
333process was created by examining memory or the swap area.
334The method is inherently somewhat unreliable and in any event a process
335is entitled to destroy this information, so the names cannot be depended
336on too much.
c39f3bbe
SW
337The
338.Cm ucomm
339(accounting) keyword can, however, be depended on.
984263bc
MD
340.Sh KEYWORDS
341The following is a complete list of the available keywords and their
342meanings.
343Several of them have aliases (keywords which are synonyms).
344.Pp
ab7ed900
SW
345.Bl -tag -width ".Cm sigignore" -compact
346.It Cm %cpu
347percentage CPU usage (alias
348.Cm pcpu )
349.It Cm %mem
350percentage memory usage (alias
351.Cm pmem )
352.It Cm acflag
353accounting flag (alias
354.Cm acflg )
355.It Cm batch
356batchness of the process (higher numbers mean less interactivity)
357.It Cm command
984263bc 358command and arguments
ab7ed900
SW
359.It Cm cpu
360short-term CPU usage factor (for scheduling)
361.It Cm f
362the process flags, in hexadecimal (alias
363.Cm flags )
364.It Cm inblk
365total blocks read (alias
366.Cm inblock )
367.It Cm jail
368jail ID
369.It Cm jobc
984263bc 370job control count
ab7ed900 371.It Cm ktrace
984263bc 372tracing flags
0e1ac0a4
SW
373.\" .It Cm ktracep
374.\" tracing vnode
ab7ed900
SW
375.It Cm lastcpu
376CPU ID the process was last scheduled on
377.It Cm lim
984263bc 378memoryuse limit
ab7ed900
SW
379.It Cm login
380login name of user who started the process (alias
381.Cm logname )
382.It Cm lstart
984263bc 383time started
ab7ed900 384.It Cm majflt
984263bc 385total page faults
ab7ed900 386.It Cm minflt
984263bc 387total page reclaims
ab7ed900 388.It Cm msgrcv
984263bc 389total messages received (reads from pipes/sockets)
ab7ed900 390.It Cm msgsnd
984263bc 391total messages sent (writes on pipes/sockets)
ab7ed900
SW
392.It Cm nice
393nice value (alias
394.Cm ni )
395.It Cm nivcsw
984263bc 396total involuntary context switches
2b0645c3
MD
397.It Cm nlwp
398number of lightweight processes
ab7ed900
SW
399.It Cm nsigs
400total signals taken (alias
401.Cm nsignals )
402.It Cm nswap
984263bc 403total swaps in/out
ab7ed900 404.It Cm nvcsw
984263bc 405total voluntary context switches
ab7ed900 406.It Cm nwchan
984263bc 407wait channel (as an address)
ab7ed900
SW
408.It Cm oublk
409total blocks written (alias
410.Cm oublock )
411.It Cm p_ru
984263bc 412resource usage (valid only for zombie)
ab7ed900 413.It Cm paddr
984263bc 414swap address
ab7ed900
SW
415.It Cm pagein
416pageins (same as
417.Cm majflt )
418.It Cm pgid
984263bc 419process group number
ab7ed900
SW
420.It Cm pid
421process ID
422.It Cm ppid
423parent process ID
424.It Cm pri
cb56579b 425scheduling priority (lower == better)
ab7ed900 426.It Cm re
984263bc 427core residency time (in seconds; 127 = infinity)
ab7ed900
SW
428.It Cm rgid
429real group ID
0e1ac0a4
SW
430.\" .It Cm rlink
431.\" reverse link on run queue, or 0
ab7ed900 432.It Cm rss
984263bc 433resident set size
ab7ed900
SW
434.It Cm rsz
435resident set size + (text size / text use count) (alias
436.Cm rssize )
437.It Cm rtprio
984263bc 438realtime priority (101 = not a realtime process)
ab7ed900
SW
439.It Cm ruid
440real user ID
441.It Cm ruser
984263bc 442user name (from ruid)
ab7ed900 443.It Cm sess
984263bc 444session pointer
ab7ed900
SW
445.It Cm sig
446pending signals (alias
447.Cm pending )
448.It Cm sigcatch
449caught signals (alias
450.Cm caught )
451.It Cm sigignore
452ignored signals (alias
453.Cm ignored )
454.It Cm sigmask
455blocked signals (alias
456.Cm blocked )
457.It Cm sl
984263bc 458sleep time (in seconds; 127 = infinity)
ab7ed900 459.It Cm start
984263bc 460time started
ab7ed900
SW
461.It Cm state
462symbolic process state (alias
463.Cm stat )
464.It Cm svgid
984263bc 465saved gid from a setgid executable
ab7ed900 466.It Cm svuid
984263bc 467saved uid from a setuid executable
ab7ed900 468.It Cm tdev
984263bc 469control terminal device number
ab7ed900 470.It Cm tdpri
cb56579b 471LWKT thread priority (0-31, 31 highest), and critical section count
2b0645c3
MD
472.It Cm tid
473thread ID (aka lightweight process ID)
ab7ed900
SW
474.It Cm time
475accumulated CPU time, user + system (alias
476.Cm cputime )
477.It Cm tpgid
478control terminal process group ID
479.\".It Cm trss
984263bc 480.\"text resident set size (in Kbytes)
ab7ed900 481.It Cm tsess
984263bc 482control terminal session pointer
e690c43b
SS
483.It Cm tsig
484pending thread signals
ab7ed900 485.It Cm tsiz
984263bc 486text size (in Kbytes)
ab7ed900 487.It Cm tt
984263bc 488control terminal name (two letter abbreviation)
ab7ed900 489.It Cm tty
984263bc 490full name of control terminal
ab7ed900 491.It Cm ucomm
e81509a4
PA
492name to be used for accounting (alias
493.Cm comm )
ab7ed900
SW
494.It Cm uid
495effective user ID
496.It Cm user
984263bc 497user name (from uid)
ab7ed900
SW
498.It Cm vsz
499virtual size in Kbytes (alias
500.Cm vsize )
501.It Cm wchan
984263bc 502wait channel (as a symbolic name)
ab7ed900 503.It Cm xstat
984263bc
MD
504exit or stop status (valid only for stopped or zombie process)
505.El
506.Sh FILES
507.Bl -tag -width /var/db/kvm_kernel.db -compact
508.It Pa /dev/kmem
509default kernel memory
510.It Pa /var/run/dev.db
511/dev name database
512.It Pa /var/db/kvm_kernel.db
513system namelist database
8e1c6f81 514.It Pa /boot/kernel
984263bc
MD
515default system namelist
516.It Pa /proc
517the mount point of
518.Xr procfs 5
519.El
520.Sh SEE ALSO
521.Xr kill 1 ,
522.Xr w 1 ,
523.Xr kvm 3 ,
524.Xr strftime 3 ,
525.Xr procfs 5 ,
526.Xr pstat 8 ,
527.Xr sysctl 8
ab7ed900
SW
528.Sh HISTORY
529The
530.Nm
531command appeared in
532.At v4 .
984263bc
MD
533.Sh BUGS
534Since
535.Nm
536cannot run faster than the system and is run as any other scheduled
537process, the information it displays can never be exact.