1.\"- 2.\" Copyright (c) 1980, 1990, 1991, 1993, 1994 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 4. Neither the name of the University nor the names of its contributors 14.\" may be used to endorse or promote products derived from this software 15.\" without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" @(#)ps.1 8.3 (Berkeley) 4/18/94 30.\" $FreeBSD$ 31.\" 32.Dd October 30, 2011 33.Dt PS 1 34.Os 35.Sh NAME 36.Nm ps 37.Nd process status 38.Sh SYNOPSIS 39.Nm 40.Op Fl aCcdefHhjlmrSTuvwXxZ 41.Op Fl O Ar fmt | Fl o Ar fmt 42.Op Fl G Ar gid Ns Op , Ns Ar gid Ns Ar ... 43.Op Fl M Ar core 44.Op Fl N Ar system 45.Op Fl p Ar pid Ns Op , Ns Ar pid Ns Ar ... 46.Op Fl t Ar tty Ns Op , Ns Ar tty Ns Ar ... 47.Op Fl U Ar user Ns Op , Ns Ar user Ns Ar ... 48.Nm 49.Op Fl L 50.Sh DESCRIPTION 51The 52.Nm 53utility 54displays a header line, followed by lines containing information about 55all of your 56processes that have controlling terminals. 57If the 58.Fl x 59options is specified, 60.Nm 61will also display processes that do not have controlling terminals. 62.Pp 63A different set of processes can be selected for display by using any 64combination of the 65.Fl a , G , p , T , t , 66and 67.Fl U 68options. 69If more than one of these options are given, then 70.Nm 71will select all processes which are matched by at least one of the 72given options. 73.Pp 74For the processes which have been selected for display, 75.Nm 76will usually display one line per process. 77The 78.Fl H 79option may result in multiple output lines (one line per thread) for 80some processes. 81By default all of these output lines are sorted first by controlling 82terminal, then by process ID. 83The 84.Fl m , r , u , 85and 86.Fl v 87options will change the sort order. 88If more than one sorting option was given, then the selected processes 89will be sorted by the last sorting option which was specified. 90.Pp 91For the processes which have been selected for display, the information 92to display is selected based on a set of keywords (see the 93.Fl L , O , 94and 95.Fl o 96options). 97The default output format includes, for each process, the process' ID, 98controlling terminal, state, CPU time (including both user and system time) 99and associated command. 100.Pp 101The process file system (see 102.Xr procfs 5 ) 103should be mounted when 104.Nm 105is executed, otherwise not all information will be available. 106.Pp 107The options are as follows: 108.Bl -tag -width indent 109.It Fl a 110Display information about other users' processes as well as your own. 111If the 112.Va security.bsd.see_other_uids 113sysctl is set to zero, this option is honored only if the UID of the user is 0. 114.It Fl c 115Change the 116.Dq command 117column output to just contain the executable name, 118rather than the full command line. 119.It Fl C 120Change the way the CPU percentage is calculated by using a 121.Dq raw 122CPU calculation that ignores 123.Dq resident 124time (this normally has 125no effect). 126.It Fl d 127Arrange processes into descendancy order and prefix each command with 128indentation text showing sibling and parent/child relationships. 129If either of the 130.Fl m 131and 132.Fl r 133options are also used, they control how sibling processes are sorted 134relative to each other. 135Note that this option has no effect if the 136.Dq command 137column is not the last column displayed. 138.It Fl e 139Display the environment as well. 140.It Fl f 141Show commandline and environment information about swapped out processes. 142This option is honored only if the UID of the user is 0. 143.It Fl G 144Display information about processes which are running with the specified 145real group IDs. 146.It Fl H 147Show all of the 148.Em kernel visible 149threads associated with each process. 150Depending on the threading package that 151is in use, this may show only the process, only the kernel scheduled entities, 152or all of the process threads. 153.It Fl h 154Repeat the information header as often as necessary to guarantee one 155header per page of information. 156.It Fl j 157Print information associated with the following keywords: 158.Cm user , pid , ppid , pgid , sid , jobc , state , tt , time , 159and 160.Cm command . 161.It Fl L 162List the set of keywords available for the 163.Fl O 164and 165.Fl o 166options. 167.It Fl l 168Display information associated with the following keywords: 169.Cm uid , pid , ppid , cpu , pri , nice , vsz , rss , mwchan , state , 170.Cm tt , time , 171and 172.Cm command . 173.It Fl M 174Extract values associated with the name list from the specified core 175instead of the currently running system. 176.It Fl m 177Sort by memory usage, instead of the combination of controlling 178terminal and process ID. 179.It Fl N 180Extract the name list from the specified system instead of the default, 181which is the kernel image the system has booted from. 182.It Fl O 183Add the information associated with the space or comma separated list 184of keywords specified, after the process ID, 185in the default information 186display. 187Keywords may be appended with an equals 188.Pq Ql = 189sign and a string. 190This causes the printed header to use the specified string instead of 191the standard header. 192.It Fl o 193Display information associated with the space or comma separated 194list of keywords specified. 195The last keyword in the list may be appended with an equals 196.Pq Ql = 197sign and a string that spans the rest of the argument, and can contain 198space and comma characters. 199This causes the printed header to use the specified string instead of 200the standard header. 201Multiple keywords may also be given in the form of more than one 202.Fl o 203option. 204So the header texts for multiple keywords can be changed. 205If all keywords have empty header texts, no header line is written. 206.It Fl p 207Display information about processes which match the specified process IDs. 208.It Fl r 209Sort by current CPU usage, instead of the combination of controlling 210terminal and process ID. 211.It Fl S 212Change the way the process times, namely cputime, systime, and usertime, 213are calculated by summing all exited children to their parent process. 214.It Fl T 215Display information about processes attached to the device associated 216with the standard input. 217.It Fl t 218Display information about processes attached to the specified terminal 219devices. 220Full pathnames, as well as abbreviations (see explanation of the 221.Cm tt 222keyword) can be specified. 223.It Fl U 224Display the processes belonging to the specified usernames. 225.It Fl u 226Display information associated with the following keywords: 227.Cm user , pid , %cpu , %mem , vsz , rss , tt , state , start , time , 228and 229.Cm command . 230The 231.Fl u 232option implies the 233.Fl r 234option. 235.It Fl v 236Display information associated with the following keywords: 237.Cm pid , state , time , sl , re , pagein , vsz , rss , lim , tsiz , 238.Cm %cpu , %mem , 239and 240.Cm command . 241The 242.Fl v 243option implies the 244.Fl m 245option. 246.It Fl w 247Use 132 columns to display information, instead of the default which 248is your window size. 249If the 250.Fl w 251option is specified more than once, 252.Nm 253will use as many columns as necessary without regard for your window size. 254Note that this option has no effect if the 255.Dq command 256column is not the last column displayed. 257.It Fl X 258When displaying processes matched by other options, skip any processes 259which do not have a controlling terminal. 260This is the default behaviour. 261.It Fl x 262When displaying processes matched by other options, include processes 263which do not have a controlling terminal. 264This is the opposite of the 265.Fl X 266option. 267If both 268.Fl X 269and 270.Fl x 271are specified in the same command, then 272.Nm 273will use the one which was specified last. 274.It Fl Z 275Add 276.Xr mac 4 277label to the list of keywords for which 278.Nm 279will display information. 280.El 281.Pp 282A complete list of the available keywords are listed below. 283Some of these keywords are further specified as follows: 284.Bl -tag -width lockname 285.It Cm %cpu 286The CPU utilization of the process; this is a decaying average over up to 287a minute of previous (real) time. 288Since the time base over which this is computed varies (since processes may 289be very young) it is possible for the sum of all 290.Cm %cpu 291fields to exceed 100%. 292.It Cm %mem 293The percentage of real memory used by this process. 294.It Cm class 295Login class associated with the process. 296.It Cm flags 297The flags associated with the process as in 298the include file 299.In sys/proc.h : 300.Bl -column P_SINGLE_BOUNDARY 0x40000000 301.It Dv "P_ADVLOCK" Ta No "0x00001 Process may hold a POSIX advisory lock" 302.It Dv "P_CONTROLT" Ta No "0x00002 Has a controlling terminal" 303.It Dv "P_KTHREAD" Ta No "0x00004 Kernel thread" 304.It Dv "P_FOLLOWFORK" Ta No "0x00008 Attach debugger to new children" 305.It Dv "P_PPWAIT" Ta No "0x00010 Parent is waiting for child to exec/exit" 306.It Dv "P_PROFIL" Ta No "0x00020 Has started profiling" 307.It Dv "P_STOPPROF" Ta No "0x00040 Has thread in requesting to stop prof" 308.It Dv "P_HADTHREADS" Ta No "0x00080 Has had threads (no cleanup shortcuts)" 309.It Dv "P_SUGID" Ta No "0x00100 Had set id privileges since last exec" 310.It Dv "P_SYSTEM" Ta No "0x00200 System proc: no sigs, stats or swapping" 311.It Dv "P_SINGLE_EXIT" Ta No "0x00400 Threads suspending should exit, not wait" 312.It Dv "P_TRACED" Ta No "0x00800 Debugged process being traced" 313.It Dv "P_WAITED" Ta No "0x01000 Someone is waiting for us" 314.It Dv "P_WEXIT" Ta No "0x02000 Working on exiting" 315.It Dv "P_EXEC" Ta No "0x04000 Process called exec" 316.It Dv "P_WKILLED" Ta No "0x08000 Killed, shall go to kernel/user boundary ASAP" 317.It Dv "P_CONTINUED" Ta No "0x10000 Proc has continued from a stopped state" 318.It Dv "P_STOPPED_SIG" Ta No "0x20000 Stopped due to SIGSTOP/SIGTSTP" 319.It Dv "P_STOPPED_TRACE" Ta No "0x40000 Stopped because of tracing" 320.It Dv "P_STOPPED_SINGLE" Ta No "0x80000 Only one thread can continue" 321.It Dv "P_PROTECTED" Ta No "0x100000 Do not kill on memory overcommit" 322.It Dv "P_SIGEVENT" Ta No "0x200000 Process pending signals changed" 323.It Dv "P_SINGLE_BOUNDARY" Ta No "0x400000 Threads should suspend at user boundary" 324.It Dv "P_HWPMC" Ta No "0x800000 Process is using HWPMCs" 325.It Dv "P_JAILED" Ta No "0x1000000 Process is in jail" 326.It Dv "P_INEXEC" Ta No "0x4000000 Process is in execve()" 327.It Dv "P_STATCHILD" Ta No "0x8000000 Child process stopped or exited" 328.It Dv "P_INMEM" Ta No "0x10000000 Loaded into memory" 329.It Dv "P_SWAPPINGOUT" Ta No "0x20000000 Process is being swapped out" 330.It Dv "P_SWAPPINGIN" Ta No "0x40000000 Process is being swapped in" 331.El 332.It Cm label 333The MAC label of the process. 334.It Cm lim 335The soft limit on memory used, specified via a call to 336.Xr setrlimit 2 . 337.It Cm lstart 338The exact time the command started, using the 339.Ql %c 340format described in 341.Xr strftime 3 . 342.It Cm lockname 343The name of the lock that the process is currently blocked on. 344If the name is invalid or unknown, then 345.Dq ???\& 346is displayed. 347.It Cm logname 348The login name associated with the session the process is in (see 349.Xr getlogin 2 ) . 350.It Cm mwchan 351The event name if the process is blocked normally, or the lock name if 352the process is blocked on a lock. 353See the wchan and lockname keywords 354for details. 355.It Cm nice 356The process scheduling increment (see 357.Xr setpriority 2 ) . 358.It Cm rss 359the real memory (resident set) size of the process (in 1024 byte units). 360.It Cm start 361The time the command started. 362If the command started less than 24 hours ago, the start time is 363displayed using the 364.Dq Li %l:ps.1p 365format described in 366.Xr strftime 3 . 367If the command started less than 7 days ago, the start time is 368displayed using the 369.Dq Li %a6.15p 370format. 371Otherwise, the start time is displayed using the 372.Dq Li %e%b%y 373format. 374.It Cm state 375The state is given by a sequence of characters, for example, 376.Dq Li RWNA . 377The first character indicates the run state of the process: 378.Pp 379.Bl -tag -width indent -compact 380.It Li D 381Marks a process in disk (or other short term, uninterruptible) wait. 382.It Li I 383Marks a process that is idle (sleeping for longer than about 20 seconds). 384.It Li L 385Marks a process that is waiting to acquire a lock. 386.It Li R 387Marks a runnable process. 388.It Li S 389Marks a process that is sleeping for less than about 20 seconds. 390.It Li T 391Marks a stopped process. 392.It Li W 393Marks an idle interrupt thread. 394.It Li Z 395Marks a dead process (a 396.Dq zombie ) . 397.El 398.Pp 399Additional characters after these, if any, indicate additional state 400information: 401.Pp 402.Bl -tag -width indent -compact 403.It Li + 404The process is in the foreground process group of its control terminal. 405.It Li < 406The process has raised CPU scheduling priority. 407.It Li E 408The process is trying to exit. 409.It Li J 410Marks a process which is in 411.Xr jail 2 . 412The hostname of the prison can be found in 413.Pa /proc/ Ns Ao Ar pid Ac Ns Pa /status . 414.It Li L 415The process has pages locked in core (for example, for raw 416.Tn I/O ) . 417.It Li N 418The process has reduced CPU scheduling priority (see 419.Xr setpriority 2 ) . 420.It Li s 421The process is a session leader. 422.It Li V 423The process is suspended during a 424.Xr vfork 2 . 425.It Li W 426The process is swapped out. 427.It Li X 428The process is being traced or debugged. 429.El 430.It Cm tt 431An abbreviation for the pathname of the controlling terminal, if any. 432The abbreviation consists of the three letters following 433.Pa /dev/tty , 434or, for pseudo-terminals, the corresponding entry in 435.Pa /dev/pts . 436This is followed by a 437.Ql - 438if the process can no longer reach that 439controlling terminal (i.e., it has been revoked). 440A 441.Ql - 442without a preceding two letter abbreviation or pseudo-terminal device number 443indicates a process which never had a controlling terminal. 444The full pathname of the controlling terminal is available via the 445.Cm tty 446keyword. 447.It Cm wchan 448The event (an address in the system) on which a process waits. 449When printed numerically, the initial part of the address is 450trimmed off and the result is printed in hex, for example, 0x80324000 prints 451as 324000. 452.El 453.Pp 454When printing using the command keyword, a process that has exited and 455has a parent that has not yet waited for the process (in other words, a zombie) 456is listed as 457.Dq Li <defunct> , 458and a process which is blocked while trying 459to exit is listed as 460.Dq Li <exiting> . 461If the arguments cannot be located (usually because it has not been set, as is 462the case of system processes and/or kernel threads) the command name is printed 463within square brackets. 464The 465.Nm 466utility first tries to obtain the arguments cached by the kernel (if they were 467shorter than the value of the 468.Va kern.ps_arg_cache_limit 469sysctl). 470The process can change the arguments shown with 471.Xr setproctitle 3 . 472Otherwise, 473.Nm 474makes an educated guess as to the file name and arguments given when the 475process was created by examining memory or the swap area. 476The method is inherently somewhat unreliable and in any event a process 477is entitled to destroy this information. 478The ucomm (accounting) keyword can, however, be depended on. 479If the arguments are unavailable or do not agree with the ucomm keyword, 480the value for the ucomm keyword is appended to the arguments in parentheses. 481.Sh KEYWORDS 482The following is a complete list of the available keywords and their 483meanings. 484Several of them have aliases (keywords which are synonyms). 485.Pp 486.Bl -tag -width ".Cm sigignore" -compact 487.It Cm %cpu 488percentage CPU usage (alias 489.Cm pcpu ) 490.It Cm %mem 491percentage memory usage (alias 492.Cm pmem ) 493.It Cm acflag 494accounting flag (alias 495.Cm acflg ) 496.It Cm args 497command and arguments 498.It Cm class 499login class 500.It Cm comm 501command 502.It Cm command 503command and arguments 504.It Cm cpu 505short-term CPU usage factor (for scheduling) 506.It Cm emul 507system-call emulation environment 508.It Cm etime 509elapsed running time, format 510.Op days- Ns 511.Op hours: Ns 512minutes:seconds. 513.It Cm etimes 514elapsed running time, in decimal integer seconds 515.It Cm flags 516the process flags, in hexadecimal (alias 517.Cm f ) 518.It Cm gid 519effective group ID (alias 520.Cm egid ) 521.It Cm group 522group name (from egid) (alias 523.Cm egroup ) 524.It Cm inblk 525total blocks read (alias 526.Cm inblock ) 527.It Cm jid 528jail ID 529.It Cm jobc 530job control count 531.It Cm ktrace 532tracing flags 533.It Cm label 534MAC label 535.It Cm lim 536memoryuse limit 537.It Cm lockname 538lock currently blocked on (as a symbolic name) 539.It Cm logname 540login name of user who started the session 541.It Cm lstart 542time started 543.It Cm lwp 544process thread-id 545.It Cm majflt 546total page faults 547.It Cm minflt 548total page reclaims 549.It Cm msgrcv 550total messages received (reads from pipes/sockets) 551.It Cm msgsnd 552total messages sent (writes on pipes/sockets) 553.It Cm mwchan 554wait channel or lock currently blocked on 555.It Cm nice 556nice value (alias 557.Cm ni ) 558.It Cm nivcsw 559total involuntary context switches 560.It Cm nlwp 561number of threads tied to a process 562.It Cm nsigs 563total signals taken (alias 564.Cm nsignals ) 565.It Cm nswap 566total swaps in/out 567.It Cm nvcsw 568total voluntary context switches 569.It Cm nwchan 570wait channel (as an address) 571.It Cm oublk 572total blocks written (alias 573.Cm oublock ) 574.It Cm paddr 575process pointer 576.It Cm pagein 577pageins (same as majflt) 578.It Cm pgid 579process group number 580.It Cm pid 581process ID 582.It Cm ppid 583parent process ID 584.It Cm pri 585scheduling priority 586.It Cm re 587core residency time (in seconds; 127 = infinity) 588.It Cm rgid 589real group ID 590.It Cm rgroup 591group name (from rgid) 592.It Cm rss 593resident set size 594.It Cm rtprio 595realtime priority (101 = not a realtime process) 596.It Cm ruid 597real user ID 598.It Cm ruser 599user name (from ruid) 600.It Cm sid 601session ID 602.It Cm sig 603pending signals (alias 604.Cm pending ) 605.It Cm sigcatch 606caught signals (alias 607.Cm caught ) 608.It Cm sigignore 609ignored signals (alias 610.Cm ignored ) 611.It Cm sigmask 612blocked signals (alias 613.Cm blocked ) 614.It Cm sl 615sleep time (in seconds; 127 = infinity) 616.It Cm start 617time started 618.It Cm state 619symbolic process state (alias 620.Cm stat ) 621.It Cm svgid 622saved gid from a setgid executable 623.It Cm svuid 624saved UID from a setuid executable 625.It Cm systime 626accumulated system CPU time 627.It Cm tdaddr 628thread address 629.It Cm tdev 630control terminal device number 631.It Cm time 632accumulated CPU time, user + system (alias 633.Cm cputime ) 634.It Cm tpgid 635control terminal process group ID 636.\".It Cm trss 637.\"text resident set size (in Kbytes) 638.It Cm tsid 639control terminal session ID 640.It Cm tsiz 641text size (in Kbytes) 642.It Cm tt 643control terminal name (two letter abbreviation) 644.It Cm tty 645full name of control terminal 646.It Cm ucomm 647name to be used for accounting 648.It Cm uid 649effective user ID (alias 650.Cm euid ) 651.It Cm upr 652scheduling priority on return from system call (alias 653.Cm usrpri ) 654.It Cm uprocp 655process pointer 656.It Cm user 657user name (from UID) 658.It Cm usertime 659accumulated user CPU time 660.It Cm vsz 661virtual size in Kbytes (alias 662.Cm vsize ) 663.It Cm wchan 664wait channel (as a symbolic name) 665.It Cm xstat 666exit or stop status (valid only for stopped or zombie process) 667.El 668.Pp 669Note that the 670.Cm pending 671column displays bitmask of signals pending in the process queue when 672.Fl H 673option is not specified, otherwise the per-thread queue of pending signals 674is shown. 675.Sh ENVIRONMENT 676The following environment variables affect the execution of 677.Nm : 678.Bl -tag -width ".Ev COLUMNS" 679.It Ev COLUMNS 680If set, specifies the user's preferred output width in column positions. 681By default, 682.Nm 683attempts to automatically determine the terminal width. 684.El 685.Sh FILES 686.Bl -tag -width ".Pa /boot/kernel/kernel" -compact 687.It Pa /boot/kernel/kernel 688default system namelist 689.It Pa /proc 690the mount point of 691.Xr procfs 5 692.El 693.Sh SEE ALSO 694.Xr kill 1 , 695.Xr pgrep 1 , 696.Xr pkill 1 , 697.Xr procstat 1 , 698.Xr w 1 , 699.Xr kvm 3 , 700.Xr strftime 3 , 701.Xr mac 4 , 702.Xr procfs 5 , 703.Xr pstat 8 , 704.Xr sysctl 8 , 705.Xr mutex 9 706.Sh STANDARDS 707For historical reasons, the 708.Nm 709utility under 710.Fx 711supports a different set of options from what is described by 712.St -p1003.2 , 713and what is supported on 714.No non- Ns Bx 715operating systems. 716.Sh HISTORY 717The 718.Nm 719command appeared in 720.At v4 . 721.Sh BUGS 722Since 723.Nm 724cannot run faster than the system and is run as any other scheduled 725process, the information it displays can never be exact. 726.Pp 727The 728.Nm 729utility does not correctly display argument lists containing multibyte 730characters. 731