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