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 55The 56.Nm 57utility 58displays a header line followed by lines containing information about your 59processes that have controlling terminals. 60This information is sorted by controlling terminal, then by process ID. 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). 68The default output format includes, for each process, the process' ID, 69controlling terminal, CPU time (including both user and system time), 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 security.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 89Change the way the CPU percentage is calculated by using a ``raw'' 90CPU calculation that ignores ``resident'' time (this normally has 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 98Print one line per lightweight process (LWP) instead of one line per process. 99When this option is set and the 100.Fl o 101option is not set, the 102.Cm tid 103column is inserted in the output format after the 104.Cm pid 105one. 106.It Fl h 107Repeat the information header as often as necessary to guarantee one 108header per page of information. 109.It Fl j 110Print information associated with the following keywords: 111.Cm user , pid , ppid , pgid , sess , jobc , state , tt , time , 112and 113.Cm command . 114.It Fl L 115List the set of available keywords. 116.It Fl l 117Display information associated with the following keywords: 118.Cm uid , pid , ppid , cpu , pri , nice , vsz , rss , wchan , state , 119.Cm tt , time , 120and 121.Cm command . 122.It Fl M 123Extract values associated with the name list from the specified core 124instead of the default 125.Pa /dev/kmem . 126.It Fl m 127Sort by memory usage, instead of by process ID. 128.It Fl N 129Extract the name list from the specified system instead of the default 130.Pa /boot/kernel . 131.It Fl O 132Add the information associated with the space or comma separated list 133of keywords specified, after the process ID, 134in the default information 135display. 136Keywords may be appended with an equals (``='') sign and a string. 137This causes the printed header to use the specified string instead of 138the standard header. 139.It Fl o 140Display information associated with the space or comma separated list 141of keywords specified. 142Keywords may be appended with an equals (``='') sign and a string. 143This causes the printed header to use the specified string instead of 144the standard header. 145.It Fl p 146Display information associated with the specified process ID. 147.It Fl r 148Sort by current CPU usage, instead of by process ID. 149.It Fl R 150Subsort by parent/child chain. This very useful option makes 151the parent/child associations clear and understandable. 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 286On SMP systems indicates a process or thread which is 287.Em not 288holding the MP lock (the Big Giant Lock). 289.It Li N 290The process has reduced CPU scheduling priority (see 291.Xr setpriority 2 ) . 292.It Li S 293The process has asked for FIFO page replacement 294.Pf ( Dv MADV_SEQUENTIAL , 295from 296.Xr madvise 2 , 297for example, a large image processing program using virtual memory to 298sequentially address voluminous data). 299.It Li s 300The process is a session leader. 301.It Li V 302The process is suspended during a 303.Xr vfork 2 . 304.It Li W 305The process is swapped out. 306.It Li X 307The process is being traced or debugged. 308.El 309.It Cm tt 310An abbreviation for the pathname of the controlling terminal, if any. 311The abbreviation consists of the three letters following 312.Pa /dev/tty , 313or, for the console, ``con''. 314This is followed by a ``-'' if the process can no longer reach that 315controlling terminal (i.e., it has been revoked). 316.It Cm wchan 317The event (an address in the system) on which a process waits. 318When printed numerically, the initial part of the address is 319trimmed off and the result is printed in hex, for example, 0x80324000 prints 320as 324000. Note that blocked threads often only have ascii wchan's. 321.El 322.Pp 323When printing using the 324.Cm command 325keyword, a process that has exited and 326has a parent that has not yet waited for the process (in other words, a zombie) 327is listed as ``<defunct>'', and a process which is blocked while trying 328to exit is listed as ``<exiting>''. 329The 330.Nm 331utility 332makes an educated guess as to the file name and arguments given when the 333process was created by examining memory or the swap area. 334The method is inherently somewhat unreliable and in any event a process 335is entitled to destroy this information, so the names cannot be depended 336on too much. 337The 338.Cm ucomm 339(accounting) keyword can, however, be depended on. 340.Sh KEYWORDS 341The following is a complete list of the available keywords and their 342meanings. 343Several of them have aliases (keywords which are synonyms). 344.Pp 345.Bl -tag -width ".Cm sigignore" -compact 346.It Cm %cpu 347percentage CPU usage (alias 348.Cm pcpu ) 349.It Cm %mem 350percentage memory usage (alias 351.Cm pmem ) 352.It Cm acflag 353accounting flag (alias 354.Cm acflg ) 355.It Cm batch 356batchness of the process (higher numbers mean less interactivity) 357.It Cm command 358command and arguments 359.It Cm cpu 360short-term CPU usage factor (for scheduling) 361.It Cm f 362the process flags, in hexadecimal (alias 363.Cm flags ) 364.It Cm inblk 365total blocks read (alias 366.Cm inblock ) 367.It Cm jail 368jail ID 369.It Cm jobc 370job control count 371.It Cm ktrace 372tracing flags 373.\" .It Cm ktracep 374.\" tracing vnode 375.It Cm lastcpu 376CPU ID the process was last scheduled on 377.It Cm lim 378memoryuse limit 379.It Cm login 380login name of user who started the process (alias 381.Cm logname ) 382.It Cm lstart 383time started 384.It Cm majflt 385total page faults 386.It Cm minflt 387total page reclaims 388.It Cm msgrcv 389total messages received (reads from pipes/sockets) 390.It Cm msgsnd 391total messages sent (writes on pipes/sockets) 392.It Cm nice 393nice value (alias 394.Cm ni ) 395.It Cm nivcsw 396total involuntary context switches 397.It Cm nlwp 398number of lightweight processes 399.It Cm nsigs 400total signals taken (alias 401.Cm nsignals ) 402.It Cm nswap 403total swaps in/out 404.It Cm nvcsw 405total voluntary context switches 406.It Cm nwchan 407wait channel (as an address) 408.It Cm oublk 409total blocks written (alias 410.Cm oublock ) 411.It Cm p_ru 412resource usage (valid only for zombie) 413.It Cm paddr 414swap address 415.It Cm pagein 416pageins (same as 417.Cm majflt ) 418.It Cm pgid 419process group number 420.It Cm pid 421process ID 422.It Cm ppid 423parent process ID 424.It Cm pri 425scheduling priority (lower == better) 426.It Cm re 427core residency time (in seconds; 127 = infinity) 428.It Cm rgid 429real group ID 430.\" .It Cm rlink 431.\" reverse link on run queue, or 0 432.It Cm rss 433resident set size 434.It Cm rsz 435resident set size + (text size / text use count) (alias 436.Cm rssize ) 437.It Cm rtprio 438realtime priority (101 = not a realtime process) 439.It Cm ruid 440real user ID 441.It Cm ruser 442user name (from ruid) 443.It Cm sess 444session pointer 445.It Cm sig 446pending signals (alias 447.Cm pending ) 448.It Cm sigcatch 449caught signals (alias 450.Cm caught ) 451.It Cm sigignore 452ignored signals (alias 453.Cm ignored ) 454.It Cm sigmask 455blocked signals (alias 456.Cm blocked ) 457.It Cm sl 458sleep time (in seconds; 127 = infinity) 459.It Cm start 460time started 461.It Cm state 462symbolic process state (alias 463.Cm stat ) 464.It Cm svgid 465saved gid from a setgid executable 466.It Cm svuid 467saved uid from a setuid executable 468.It Cm tdev 469control terminal device number 470.It Cm tdpri 471LWKT thread priority (0-31, 31 highest), and critical section count 472.It Cm tid 473thread ID (aka lightweight process ID) 474.It Cm time 475accumulated CPU time, user + system (alias 476.Cm cputime ) 477.It Cm tpgid 478control terminal process group ID 479.\".It Cm trss 480.\"text resident set size (in Kbytes) 481.It Cm tsess 482control terminal session pointer 483.It Cm tsig 484pending thread signals 485.It Cm tsiz 486text size (in Kbytes) 487.It Cm tt 488control terminal name (two letter abbreviation) 489.It Cm tty 490full name of control terminal 491.It Cm ucomm 492name to be used for accounting (alias 493.Cm comm ) 494.It Cm uid 495effective user ID 496.It Cm user 497user name (from uid) 498.It Cm vsz 499virtual size in Kbytes (alias 500.Cm vsize ) 501.It Cm wchan 502wait channel (as a symbolic name) 503.It Cm xstat 504exit 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 509default kernel memory 510.It Pa /var/run/dev.db 511/dev name database 512.It Pa /var/db/kvm_kernel.db 513system namelist database 514.It Pa /boot/kernel 515default system namelist 516.It Pa /proc 517the 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 529The 530.Nm 531command appeared in 532.At v4 . 533.Sh BUGS 534Since 535.Nm 536cannot run faster than the system and is run as any other scheduled 537process, the information it displays can never be exact. 538