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