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