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