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