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