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