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