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