1.\" $NetBSD: ps.1,v 1.103 2014/01/15 09:24:31 wiz Exp $ 2.\" 3.\" Copyright (c) 1980, 1990, 1991, 1993, 1994 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)ps.1 8.3 (Berkeley) 4/18/94 31.\" 32.Dd January 15, 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 AaCcehjlmrSsTuvwx 41.Op Fl k Ar key 42.Op Fl M Ar core 43.Op Fl N Ar system 44.Op Fl O Ar fmt 45.Op Fl o Ar fmt 46.Op Fl p Ar pid 47.Op Fl t Ar tty 48.Op Fl U Ar user 49.Op Fl W Ar swap 50.Nm 51.Fl L 52.Sh DESCRIPTION 53.Nm 54displays a header line followed by lines containing information about 55running processes. 56By default, the display includes only processes that have 57controlling terminals and are owned by your uid. 58The default sort order of controlling terminal and 59(among processes with the same controlling terminal) process 60.Tn ID 61may be changed using the 62.Fl k , Fl m , 63or 64.Fl r 65options. 66.Pp 67The information displayed for each process 68is selected based on a set of keywords (see the 69.Fl L , 70.Fl O , 71and 72.Fl o 73options). 74The default output format includes, for each process, the process' 75.Tn ID , 76controlling terminal, CPU time (including both user and system time), 77state, and associated command. 78.Pp 79The options are as follows: 80.Bl -tag -width XNXsystemXX 81.It Fl A 82Display information about all processes. 83This is equivalent to 84.Fl a Fl x . 85.It Fl a 86Display information about other users' processes as well as your own. 87Note that this does not display information about processes 88without controlling terminals. 89.It Fl C 90Change the way the CPU percentage is calculated by using a 91.Dq raw 92CPU calculation that ignores 93.Dq resident 94time (this normally has no effect). 95.It Fl c 96Do not display full command with arguments, but only the 97executable name. 98This may be somewhat confusing; for example, all 99.Xr sh 1 100scripts will show as 101.Dq sh . 102.It Fl e 103Display the environment as well. 104The environment for other 105users' processes can only be displayed by the super-user. 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.Ar user , pid , ppid , pgid , sess , jobc , state , tt , time , 112and 113.Ar command . 114.It Fl k Ar key 115Sort the output using the space or comma separated list of keywords. 116Multiple sort keys may be specified, using any of the 117.Fl k , Fl m , 118or 119.Fl r 120options. 121The default sort order is equivalent to 122.Fl k Ar tdev,pid . 123.It Fl L 124List the set of available keywords. 125.It Fl l 126Display information associated with the following keywords: 127.Ar uid , pid , ppid , cpu , pri , nice , vsz , rss , wchan , state , 128.Ar tt , time , 129and 130.Ar command . 131.It Fl M Ar core 132Extract values from the specified core file instead of the running system. 133.It Fl m 134Sort by memory usage. 135This is equivalent to 136.Fl k Ar vsz . 137.It Fl N Ar system 138Extract the name list from the specified system instead of the default, 139.Dq Pa /netbsd . 140Ignored unless 141.Fl M 142is specified. 143.It Fl O Ar fmt 144Display information associated with the space or comma separated list 145of keywords specified. 146The 147.Fl O 148option does not suppress the default display; 149it inserts additional keywords just after the 150.Ar pid 151keyword in the default display, or after the 152.Ar pid 153keyword (if any) in a non-default display specified before the 154first use of the 155.Fl O 156flag. 157Keywords inserted by multiple 158.Fl O 159options will be adjacent. 160.Pp 161An equals sign 162.Pq Dq \&= 163followed by a customised header string may be appended to a keyword, 164as described in more detail under the 165.Fl o 166option. 167.It Fl o Ar fmt 168Display information associated with the space or comma separated list 169of keywords specified. 170Use of the 171.Fl o 172option suppresses the set of keywords that would be displayed by default, 173or appends to the set of keywords specified by other options. 174.Pp 175An equals sign 176.Pq Dq \&= 177followed by a customised header string may be appended to a keyword. 178This causes the printed header to use the specified string instead of 179the default header associated with the keyword. 180.Pp 181Everything after the first equals sign is part of the customised 182header text, and this may include embedded spaces 183.Pq Dq " " , 184commas 185.Pq Dq \&, , 186or equals signs 187.Pq Dq \&= . 188To specify multiple keywords with customised headers, use multiple 189.Fl o 190or 191.Fl O 192options. 193.Pp 194If all the keywords to be displayed have customised headers, 195and all the customised headers are entirely empty, 196then the header line is not printed at all. 197.It Fl p Ar pid 198Display information associated with the specified process 199.Tn ID . 200.It Fl r 201Sort by current CPU usage. 202This is equivalent to 203.Fl k Ar %cpu . 204.It Fl S 205Change the way the process time is calculated by summing all exited 206children to their parent process. 207.It Fl s 208Display one line for each LWP, rather than one line for each process, 209and display information associated with the following keywords: 210.Ar uid , pid , ppid , cpu , lid , nlwp , pri , nice , vsz , rss , 211.Ar wchan , lstate , tt , time , 212and 213.Ar command . 214.It Fl T 215Display information about processes attached to the device associated 216with the standard input. 217.It Fl t Ar tty 218Display information about processes attached to the specified terminal 219device. 220Use a question mark 221.Pq Dq \&? 222for processes not attached to a 223terminal device and a minus sign 224.Pq Dq - 225for processes that have 226been revoked from their terminal device. 227.It Fl U Ar user 228Display processes belonging to the specified user, 229given either as a user name or a uid. 230.It Fl u 231Display information associated with the following keywords: 232.Ar user , pid , %cpu , %mem , vsz , rss , tt , state , start , time , 233and 234.Ar command . 235The 236.Fl u 237option implies the 238.Fl r 239option. 240.It Fl v 241Display information associated with the following keywords: 242.Ar pid , state , time , sl , re , pagein , vsz , rss , lim , tsiz , 243.Ar %cpu , %mem , 244and 245.Ar command . 246The 247.Fl v 248option implies the 249.Fl m 250option. 251.It Fl W Ar swap 252Extract swap information from the specified file instead of the default, 253.Dq Pa /dev/drum . 254Ignored unless 255.Fl M 256is specified. 257.It Fl w 258Use 132 columns to display information instead of the default, which 259is your window size. 260If the 261.Fl w 262option is specified more than once, 263.Nm 264will use as many columns as necessary without regard to your window size. 265.It Fl x 266Also display information about processes without controlling terminals. 267.El 268.Pp 269A complete list of the available keywords are listed below. 270Some of these keywords are further specified as follows: 271.Bl -tag -width indent 272.It Ar %cpu 273The CPU utilization of the process; this is a decaying average over up to 274a minute of previous (real) time. 275Since the time base over which this is computed varies (since processes may 276be very young) it is possible for the sum of all 277.Tn %CPU 278fields to exceed 100%. 279.It Ar %mem 280The percentage of real memory used by this process. 281.It Ar flags 282The flags (in hexadecimal) associated with the process as in 283the include file 284.In sys/proc.h : 285.Bl -column P_NOCLDSTOP P_NOCLDSTOP compact 286.It Dv "P_ADVLOCK" Ta No "0x00000001 process may hold a POSIX advisory lock" 287.It Dv "P_CONTROLT" Ta No "0x00000002 process has a controlling terminal" 288.It Dv "P_NOCLDSTOP" Ta No "0x00000008 no" Dv SIGCHLD No when children stop 289.It Dv "P_PPWAIT" Ta No "0x00000010 parent is waiting for child to exec/exit" 290.It Dv "P_PROFIL" Ta No "0x00000020 process has started profiling" 291.It Dv "P_SELECT" Ta No "0x00000040 selecting; wakeup/waiting danger" 292.It Dv "P_SINTR" Ta No "0x00000080 sleep is interruptible" 293.It Dv "P_SUGID" Ta No "0x00000100 process had set id privileges since last exec" 294.It Dv "P_SYSTEM" Ta No "0x00000200 system process: no sigs or stats" 295.It Dv "P_TIMEOUT" Ta No "0x00000400 timing out during sleep" 296.It Dv "P_TRACED" Ta No "0x00000800 process is being traced" 297.It Dv "P_WAITED" Ta No "0x00001000 debugging process has waited for child" 298.It Dv "P_WEXIT" Ta No "0x00002000 working on exiting" 299.It Dv "P_EXEC" Ta No "0x00004000 process called" Xr execve 2 300.It Dv "P_OWEUPC" Ta No "0x00008000 owe process an addupc() call at next ast" 301.\" the routine addupc is not documented in the man pages 302.It Dv "P_FSTRACE" Ta No "0x00010000 tracing via file system" 303.It Dv "P_NOCLDWAIT" Ta No "0x00020000 no zombies when children die" 304.It Dv "P_32" Ta No "0x00040000 32-bit process (used on 64-bit kernels)" 305.It Dv "P_BIGLOCK" Ta No "0x00080000 process needs kernel ``big lock'' to run" 306.It Dv "P_INEXEC" Ta No "0x00100000 process is exec'ing and cannot be traced" 307.El 308.It Ar lim 309The soft limit on memory used, specified via a call to 310.Xr setrlimit 2 . 311.It Ar lstart 312The exact time the command started, using the 313.Dq \&%c 314format described in 315.Xr strftime 3 . 316.It Ar nice 317The process scheduling increment (see 318.Xr setpriority 2 ) . 319.It Ar rss 320the real memory (resident set) size of the process (in 1024 byte units). 321.It Ar start 322The time the command started. 323If the command started less than 24 hours ago, the start time is 324displayed using the 325.Dq %l:%M%p 326format described in 327.Xr strftime 3 . 328If the command started less than 7 days ago, the start time is 329displayed using the 330.Dq %a%p 331format. 332Otherwise, the start time is displayed using the 333.Dq %e%b%y 334format. 335.It Ar state 336The state is given by a sequence of letters, for example, 337.Dq Tn RNs . 338The first letter indicates the run state of the process: 339.Pp 340.Bl -tag -width indent -compact 341.It D 342Marks a process in device or other short term, uninterruptible wait. 343.It I 344Marks a process that is idle (sleeping interruptibly for longer than about 345.Dv MAXSLP 346(default 20) seconds). 347.It O 348Marks a process running on a processor. 349.It R 350Marks a runnable process, or one that is in the process of creation. 351.It S 352Marks a process that is sleeping interruptibly for less than about 353.Dv MAXSLP 354(default 20) seconds. 355.It T 356Marks a stopped process. 357.It U 358Marks a suspended process. 359.It Z 360Marks a dead process that has exited, but not been waited for (a 361.Dq zombie ) . 362.El 363.Pp 364Additional characters after these, if any, indicate additional state 365information: 366.Pp 367.Bl -tag -width indent -compact 368.It + 369The process is in the foreground process group of its control terminal. 370.It - 371The LWP is detached (can't be waited for). 372.It \*[Lt] 373The process has raised 374.Tn CPU 375scheduling priority. 376.It a 377The process is using scheduler activations (deprecated). 378.It E 379The process is in the process of exiting. 380.It K 381The process is a kernel thread or system process. 382.It l 383The process has multiple LWPs. 384.It N 385The process is niced (has reduced 386.Tn CPU 387scheduling priority) (see 388.Xr setpriority 2 ) . 389.It s 390The process is a session leader. 391.It V 392The process is suspended during a 393.Xr vfork 2 . 394.It X 395The process is being traced or debugged. 396.El 397.It Ar tt 398An abbreviation for the pathname of the controlling terminal, if any. 399The abbreviation consists of the two letters following 400.Dq Pa /dev/tty 401or, for the console, 402.Dq co . 403This is followed by a 404.Dq \&- 405if the process can no longer reach that 406controlling terminal (i.e., it has been revoked). 407.It Ar wchan 408The event (an address in the system) on which a process waits. 409When printed numerically, the initial part of the address is 410trimmed off and the result is printed in hex, for example, 0x80324000 prints 411as 324000. 412.El 413.Pp 414When printing using the 415.Ar command 416keyword, a process that has exited and has a parent that has not yet 417waited for the process (in other words, a zombie) is listed as 418.Dq Aq defunct , 419and a process which is blocked while trying to exit is listed as 420.Dq Aq exiting . 421.Pp 422.Nm 423will try to locate the processes' argument vector from the user 424area in order to print the command name and arguments. 425This method is not reliable because a process is allowed to destroy this 426information. 427The 428.Ar ucomm 429(accounting) keyword will always contain the real command name as 430contained in the process structure's 431.Va p_comm 432field. 433.Pp 434If the command vector cannot be located (usually because it has not 435been set, as is the case of system processes and/or kernel threads) 436the command name is printed within square brackets. 437.Pp 438To indicate that the argument vector has been tampered with, 439.Nm 440will append the real command name to the output within parentheses 441if the basename of the first argument in the argument vector 442does not match the contents of the real command name. 443.Pp 444In addition, 445.Nm 446checks for the following two situations and does not append the 447real command name parenthesized: 448.Bl -tag -width indent 449.It -shellname 450The login process traditionally adds a 451.Sq - 452in front of the shell name to indicate a login shell. 453.Nm 454will not append parenthesized the command name if it matches with 455the name in the first argument of the argument vector, skipping 456the leading 457.Sq - . 458.It daemonname: current-activity 459Daemon processes frequently report their current activity by setting 460their name to be like 461.Dq daemonname: current-activity . 462.Nm 463will not append parenthesized the command name, if the string preceding the 464.Sq \&: 465in the first argument of the argument vector matches the command name. 466.El 467.Sh KEYWORDS 468The following is a complete list of the available keywords and their 469meanings. 470Several of them have aliases (keywords which are synonyms). 471.Pp 472.Bl -tag -width groupnames -compact 473.It Ar %cpu 474percentage CPU usage (alias 475.Ar pcpu ) 476.It Ar %mem 477percentage memory usage (alias 478.Ar pmem ) 479.It Ar acflag 480accounting flag (alias 481.Ar acflg ) 482.It Ar comm 483command (the argv[0] value) 484.It Ar command 485command and arguments (alias 486.Ar args ) 487.It Ar cpu 488short-term CPU usage factor (for scheduling) 489.It Ar cpuid 490CPU number the current process or lwp is running on. 491.It Ar ctime 492accumulated CPU time of all children that have exited 493.It Ar egid 494effective group id 495.It Ar egroup 496group name (from egid) 497.It Ar emul 498emulation name 499.It Ar etime 500elapsed time since the process was started, in the form 501.Li [[dd-]hh:]mm:ss 502.It Ar euid 503effective user id 504.It Ar euser 505user name (from euid) 506.It Ar flags 507the process flags, in hexadecimal (alias 508.Ar f ) 509.It Ar gid 510effective group id 511.It Ar group 512group name (from gid) 513.It Ar groupnames 514group names (from group access list) 515.It Ar groups 516group access list 517.It Ar inblk 518total blocks read (alias 519.Ar inblock ) 520.It Ar jobc 521job control count 522.It Ar ktrace 523tracing flags 524.It Ar ktracep 525tracing vnode 526.It Ar laddr 527kernel virtual address of the 528.Tn "struct lwp" 529belonging to the LWP. 530.It Ar lid 531ID of the LWP 532.It Ar lim 533memory use limit 534.It Ar lname 535descriptive name of the LWP 536.It Ar logname 537login name of user who started the process (alias 538.Ar login ) 539.It Ar lstart 540time started 541.It Ar lstate 542symbolic LWP state 543.It Ar ltime 544CPU time of the LWP 545.It Ar majflt 546total page faults 547.It Ar minflt 548total page reclaims 549.It Ar msgrcv 550total messages received (reads from pipes/sockets) 551.It Ar msgsnd 552total messages sent (writes on pipes/sockets) 553.It Ar nice 554nice value (alias 555.Ar ni ) 556.It Ar nivcsw 557total involuntary context switches 558.It Ar nlwp 559number of LWPs in the process 560.It Ar nsigs 561total signals taken (alias 562.Ar nsignals ) 563.It Ar nvcsw 564total voluntary context switches 565.It Ar nwchan 566wait channel (as an address) 567.It Ar oublk 568total blocks written (alias 569.Ar oublock ) 570.It Ar p_ru 571resource usage pointer (valid only for zombie) 572.It Ar paddr 573kernel virtual address of the 574.Tn "struct proc" 575belonging to the process. 576.It Ar pagein 577pageins (same as majflt) 578.It Ar pgid 579process group number 580.It Ar pid 581process 582.Tn ID 583.It Ar ppid 584parent process 585.Tn ID 586.It Ar pri 587scheduling priority 588.It Ar re 589core residency time (in seconds; 127 = infinity) 590.It Ar rgid 591real group 592.Tn ID 593.It Ar rlink 594reverse link on run queue, or 0 595.It Ar rlwp 596number of LWPs on a processor or run queue 597.It Ar rss 598resident set size 599.It Ar rsz 600resident set size + (text size / text use count) (alias 601.Ar rssize ) 602.It Ar ruid 603real user 604.Tn ID 605.It Ar ruser 606user name (from ruid) 607.It Ar sess 608session pointer 609.It Ar sid 610session 611.Tn ID 612.It Ar sig 613pending signals (alias 614.Ar pending ) 615.It Ar sigcatch 616caught signals (alias 617.Ar caught ) 618.It Ar sigignore 619ignored signals (alias 620.Ar ignored ) 621.It Ar sigmask 622blocked signals (alias 623.Ar blocked ) 624.It Ar sl 625sleep time (in seconds; 127 = infinity) 626.It Ar start 627time started 628.It Ar state 629symbolic process state (alias 630.Ar stat ) 631.It Ar stime 632accumulated system CPU time 633.It Ar svgid 634saved gid from a setgid executable 635.It Ar svgroup 636group name (from svgid) 637.It Ar svuid 638saved uid from a setuid executable 639.It Ar svuser 640user name (from svuid) 641.It Ar tdev 642control terminal device number 643.It Ar time 644accumulated CPU time, user + system (alias 645.Ar cputime ) 646.It Ar tpgid 647control terminal process group 648.Tn ID 649.It Ar tsess 650control terminal session pointer 651.It Ar tsiz 652text size (in Kbytes) 653.It Ar tt 654control terminal name (two letter abbreviation) 655.It Ar tty 656full name of control terminal 657.It Ar uaddr 658kernel virtual address of the 659.Tn "struct user" 660belonging to the LWP. 661.It Ar ucomm 662name to be used for accounting 663.It Ar uid 664effective user 665.Tn ID 666.It Ar upr 667scheduling priority on return from system call (alias 668.Ar usrpri ) 669.It Ar user 670user name (from uid) 671.It Ar utime 672accumulated user CPU time 673.It Ar vsz 674virtual size in Kbytes (alias 675.Ar vsize ) 676.It Ar wchan 677wait channel (as a symbolic name) 678.It Ar xstat 679exit or stop status (valid only for stopped or zombie process) 680.El 681.Sh FILES 682.Bl -tag -width /var/run/kvm.db -compact 683.It Pa /dev 684special files and device names 685.It Pa /dev/drum 686default swap device 687.It Pa /var/run/dev.cdb 688/dev name database 689.It Pa /var/db/kvm.db 690system name list database 691.It Pa /netbsd 692default system name list 693.El 694.Sh SEE ALSO 695.Xr kill 1 , 696.Xr pgrep 1 , 697.Xr pkill 1 , 698.Xr sh 1 , 699.Xr w 1 , 700.Xr kvm 3 , 701.Xr strftime 3 , 702.Xr dev_mkdb 8 , 703.Xr pstat 8 704.Sh BUGS 705Since 706.Nm 707cannot run faster than the system and is run as any other scheduled 708process, the information it displays can never be exact. 709