1.\" $OpenBSD: ps.1,v 1.117 2020/02/08 16:41:25 schwarze Exp $ 2.\" $NetBSD: ps.1,v 1.16 1996/03/21 01:36:28 jtc Exp $ 3.\" 4.\" Copyright (c) 1980, 1990, 1991, 1993, 1994 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)ps.1 8.3 (Berkeley) 4/18/94 32.\" 33.Dd $Mdocdate: February 8 2020 $ 34.Dt PS 1 35.Os 36.Sh NAME 37.Nm ps 38.Nd display process status 39.Sh SYNOPSIS 40.Nm ps 41.Sm off 42.Op Oo Fl Oc Cm AaceHhjkLlmrSTuvwx 43.Sm on 44.Op Fl M Ar core 45.Op Fl N Ar system 46.Op Fl O Ar fmt 47.Op Fl o Ar fmt 48.Op Fl p Ar pid 49.Op Fl t Ar tty 50.Op Fl U Ar username 51.Op Fl W Ar swap 52.Sh DESCRIPTION 53The 54.Nm 55utility displays information about active processes. 56When given no options, 57.Nm 58prints information about processes of the current user that have a 59controlling terminal. 60.Pp 61The information displayed is selected based on a set of keywords (and for 62even more control, see the 63.Fl L , 64.Fl O , 65and 66.Fl o 67options). 68The default output format includes, for each process, the process's ID, 69controlling terminal, state, CPU time (including both user and system time), 70and associated command. 71.Pp 72The options are as follows: 73.Bl -tag -width Ds 74.It Fl A 75Display information about processes for all users, including those without controlling 76terminals. 77.It Fl a 78Display information about processes for all users with controlling terminals. 79.It Fl c 80Do not display full command with arguments, but only the 81executable name. 82This may be somewhat confusing; for example, all 83.Xr sh 1 84scripts will show as 85.Dq sh . 86.It Fl e 87Display the environment as well. 88.It Fl H 89Also display information about kernel visible threads. 90.It Fl h 91Repeat the information header as often as necessary to guarantee one 92header per page of information. 93.It Fl j 94Print information associated with the following keywords: 95user, pid, ppid, pgid, sess, jobc, state, tt, time, and command. 96.It Fl k 97Also display information about kernel threads. 98.It Fl L 99List the set of available keywords. 100This option should not be specified with other options. 101.It Fl l 102Display information associated with the following keywords: 103uid, pid, ppid, cpu, pri, nice, vsz, rss, wchan, state, tt, time, 104and command. 105.It Fl M Ar core 106Extract values associated with the name list from the specified core 107instead of the running kernel. 108.It Fl m 109Sort by memory usage, instead of by start time ID. 110.It Fl N Ar system 111Extract the name list from the specified system instead of the running kernel. 112.It Fl O Ar fmt 113Add the information associated with the space or comma separated list 114of keywords specified, after the process ID, 115in the default information 116display. 117Keywords may be appended with an equals sign 118.Pq Sq = 119and a string. 120This causes the printed header to use the specified string instead of 121the standard header. 122.It Fl o Ar fmt 123Display information associated with the space or comma separated list 124of keywords specified. 125Keywords may be appended with an equals sign 126.Pq Sq = 127and a string. 128This causes the printed header to use the specified string instead of 129the standard header. 130.It Fl p Ar pid 131Display information associated with the specified process ID. 132.It Fl r 133Sort by current CPU usage, instead of by start time ID. 134.It Fl S 135Change the way the process time is calculated by summing all exited 136children to their parent process. 137.It Fl T 138Display information about processes attached to the device associated 139with the standard input. 140.It Fl t Ar tty 141Display information about processes attached to the specified terminal 142device. 143.It Fl U Ar username 144Display the processes belonging to the specified 145.Ar username . 146.It Fl u 147Display information associated with the following keywords: 148user, pid, %cpu, %mem, vsz, rss, tt, state, start, time, and command. 149The 150.Fl u 151option implies the 152.Fl r 153option. 154.It Fl v 155Display information associated with the following keywords: 156pid, state, time, sl, re, pagein, vsz, rss, lim, tsiz, 157%cpu, %mem, and command. 158The 159.Fl v 160option implies the 161.Fl m 162option. 163.It Fl W Ar swap 164When not using the running kernel, 165extract swap information from the specified file. 166.It Fl w 167Use 132 columns to display information, instead of the default, which 168is the window size. 169If the 170.Fl w 171option is specified more than once, 172.Nm 173will use as many columns as necessary without regard for window size. 174.It Fl x 175Display information about processes without controlling terminals. 176.El 177.Sh KEYWORDS 178The following is a complete list of the available keywords 179and their meanings. 180Several of them have aliases, 181which are also noted. 182.Bl -tag -width "sigignoreXX" -offset 3n 183.It Cm %cpu 184Alias: 185.Cm pcpu . 186The CPU utilization of the process; this is a decaying average over up to 187a minute of previous (real) time. 188Since the time base over which this is computed varies (since processes may 189be very young) it is possible for the sum of all 190.Cm %cpu 191fields to exceed 100%. 192.It Cm %mem 193Alias: 194.Cm pmem . 195The percentage of real memory used by this process. 196.It Cm acflag 197Alias: 198.Cm acflg . 199Accounting flag. 200.It Cm command 201Alias: 202.Cm args . 203Command and arguments. 204.It Cm cpu 205Short-term CPU usage factor (for scheduling). 206.It Cm cpuid 207CPU ID (zero on single processor systems). 208.It Cm cwd 209Current working directory. 210.It Cm dsiz 211Data size, in Kilobytes. 212.It Cm emul 213Name of system call emulation environment. 214.It Cm etime 215Elapsed time since the process was started. 216.It Cm flags 217Alias: 218.Cm f . 219The thread flags (in hexadecimal), as defined in the include file 220.In sys/proc.h : 221.Bd -literal 222P_INKTR 0x1 writing ktrace(2) record 223P_PROFPEND 0x2 this thread needs SIGPROF 224P_ALRMPEND 0x4 this thread needs SIGVTALRM 225P_SIGSUSPEND 0x8 need to restore before-suspend mask 226P_CANTSLEEP 0x10 this thread is not permitted to sleep 227P_SELECT 0x40 selecting; wakeup/waiting danger 228P_SINTR 0x80 sleep is interruptible 229P_SYSTEM 0x200 system process: no sigs, stats, or 230 swapping 231P_TIMEOUT 0x400 timing out during sleep 232P_WEXIT 0x2000 working on exiting 233P_OWEUPC 0x8000 profiling sample needs recording 234P_SUSPSINGLE 0x80000 need to suspend for single threading 235P_CONTINUED 0x800000 thread has continued after a stop 236P_THREAD 0x4000000 not the original thread 237P_SUSPSIG 0x8000000 stopped because of a signal 238P_SOFTDEP 0x10000000 stuck processing softdep worklist 239P_CPUPEG 0x40000000 do not move to another cpu 240.Ed 241.It Cm gid 242Effective group. 243.It Cm group 244Text name of effective group ID. 245.It Cm inblk 246Alias: 247.Cm inblock . 248Total blocks read. 249.It Cm jobc 250Job control count. 251.It Cm ktrace 252Tracing flags. 253.It Cm ktracep 254Tracing vnode. 255.It Cm lim 256The soft limit on memory used, specified via a call to 257.Xr setrlimit 2 . 258.It Cm logname 259Alias: 260.Cm login . 261Login name of user who started the process. 262.It Cm lstart 263The exact time the command started, using the 264.Dq %c 265format described in 266.Xr strftime 3 . 267.It Cm majflt 268Total page faults. 269.It Cm maxrss 270Maximum resident set size (in 1024 byte units). 271.It Cm minflt 272Total page reclaims. 273.It Cm msgrcv 274Total messages received (reads from pipes/sockets). 275.It Cm msgsnd 276Total messages sent (writes on pipes/sockets). 277.It Cm nice 278Alias: 279.Cm ni . 280The process scheduling increment (see 281.Xr setpriority 2 ) . 282.It Cm nivcsw 283Total involuntary context switches. 284.It Cm nsigs 285Alias: 286.Cm nsignals . 287Total signals taken. 288.It Cm nswap 289Total swaps in/out. 290.It Cm nvcsw 291Total voluntary context switches. 292.It Cm nwchan 293Wait channel (as an address). 294.It Cm oublk 295Alias: 296.Cm oublock . 297Total blocks written. 298.It Cm p_ru 299Resource usage (valid only for zombie processes). 300.It Cm paddr 301Swap address. 302.It Cm pagein 303Pageins (same as 304.Cm majflt ) . 305.It Cm pgid 306Process group number. 307.It Cm pid 308Process ID. 309.It Cm pledge 310Comma separated list of active 311.Xr pledge 2 312promises. 313.It Cm ppid 314Parent process ID. 315.It Cm pri 316Scheduling priority. 317.It Cm procflags 318The process flags (in hexadecimal), as defined in the include file 319.In sys/proc.h : 320.Bd -literal 321PS_CONTROLT 0x1 process has a controlling 322 terminal 323PS_EXEC 0x2 process called exec(3) 324PS_INEXEC 0x4 process is doing an exec right 325 now 326PS_EXITING 0x8 process is exiting 327PS_SUGID 0x10 process had set ID privileges 328 since last exec 329PS_SUGIDEXEC 0x20 last exec(3) was set[ug]id 330PS_PPWAIT 0x40 parent is waiting for process 331 to exec/exit 332PS_ISPWAIT 0x80 process is parent of PPWAIT 333 child 334PS_PROFIL 0x100 process has started profiling 335PS_TRACED 0x200 process is being traced 336PS_WAITED 0x400 debugging process has waited 337 for child 338PS_COREDUMP 0x800 busy coredumping 339PS_SINGLEEXIT 0x1000 other threads must die 340PS_SINGLEUNWIND 0x2000 other threads must unwind 341PS_NOZOMBIE 0x4000 pid 1 waits for me instead of 342 dad 343PS_STOPPED 0x8000 just stopped, need to send 344 SIGCHLD 345PS_SYSTEM 0x10000 No signals, stats or swapping 346PS_EMBRYO 0x20000 New process, not yet fledged 347PS_ZOMBIE 0x40000 Dead and ready to be waited for 348PS_NOBROADCASTKILL 0x80000 Process excluded from kill -1 349PS_PLEDGE 0x100000 process has called pledge(2) 350.Ed 351.It Cm re 352Core residency time (in seconds; 127 = infinity). 353.It Cm rgid 354Real group ID. 355.It Cm rgroup 356Text name of real group ID. 357.It Cm rlink 358Reverse link on run queue, or 0. 359.It Cm rss 360The real memory (resident set) size of the process (in 1024 byte units). 361.It Cm rsz 362Alias: 363.Cm rssize . 364Resident set size + (text size / text use count). 365.It Cm rtable 366Routing table. 367.It Cm ruid 368Real user ID. 369.It Cm ruser 370User name (from 371.Cm ruid ) . 372.It Cm sess 373Session pointer. 374.It Cm sig 375Alias: 376.Cm pending . 377Pending signals. 378.It Cm sigcatch 379Alias: 380.Cm caught . 381Caught signals. 382.It Cm sigignore 383Alias: 384.Cm ignored . 385Ignored signals. 386.It Cm sigmask 387Alias: 388.Cm blocked . 389Blocked signals. 390.It Cm sl 391Sleep time (in seconds; 127 = infinity). 392.It Cm ssiz 393Stack size, in Kilobytes. 394.It Cm start 395The time the command started. 396If the command started less than 24 hours ago, the start time is 397displayed using the 398.Dq %l:%M%p 399format described in 400.Xr strftime 3 . 401If the command started less than 7 days ago, the start time is 402displayed using the 403.Dq %a%I%p 404format. 405Otherwise, the start time is displayed using the 406.Dq %e%b%y 407format. 408.It Cm state 409Alias: 410.Cm stat . 411The state is given by a sequence of letters, for example, 412.Dq RWN . 413The first letter indicates the run state of the process: 414.Pp 415.Bl -tag -width indent -compact 416.It D 417Marks a process in disk (or other short term, uninterruptible) wait. 418.It I 419Marks a process that is idle (sleeping for longer than about 20 seconds). 420.It R 421Marks a runnable process. 422.It S 423Marks a process that is sleeping for less than about 20 seconds. 424.It T 425Marks a stopped process. 426.It Z 427Marks a dead process (a 428.Dq zombie ) . 429.El 430.Pp 431Additional characters after these, if any, indicate additional state 432information: 433.Pp 434.Bl -tag -width indent -compact 435.It + 436The process is in the foreground process group of its control terminal. 437.It \*(Lt 438The process has a raised CPU 439scheduling priority (see 440.Xr setpriority 2 ) . 441.It \*(Gt 442The process has specified a soft limit on memory requirements and is 443currently exceeding that limit; such a process is (necessarily) not 444swapped. 445.\" .It A 446.\" the process has asked for random page replacement 447.\" .Pf ( Dv MADV_RANDOM , 448.\" from 449.\" .Xr madvise 2 , 450.\" for example, 451.\" .Xr lisp 1 452.\" in a garbage collect). 453.It E 454The process is trying to exit. 455.It K 456The process is a kernel thread. 457.It N 458The process has a reduced CPU 459scheduling priority. 460.It p 461The process has called 462.Xr pledge 2 . 463.\" .It S 464.\" The process has asked for FIFO 465.\" page replacement 466.\" .Pf ( Dv MADV_SEQUENTIAL , 467.\" from 468.\" .Xr madvise 2 , 469.\" for example, a large image processing program using virtual memory to 470.\" sequentially address voluminous data). 471.It s 472The process is a session leader. 473.It U 474The process has unveiled, and 475.Xr unveil 2 476is now locked. 477.It u 478The process has unveiled, but not yet locked 479.Xr unveil 2 480(could be a program error). 481.It V 482The process is suspended during a 483.Xr vfork 2 . 484.It X 485The process is being traced or debugged. 486.It / Ns Ar n 487On multiprocessor machines, specifies processor number 488.Ar n . 489.El 490.It Cm svgid 491Saved GID from a setgid executable. 492.It Cm svuid 493Saved UID from a setuid executable. 494.It Cm tdev 495Control terminal device number. 496.It Cm tid 497Thread ID. 498Used together with 499.Fl H . 500.It Cm time 501Alias: 502.Cm cputime . 503Accumulated CPU time, user + system. 504.It Cm tpgid 505Control terminal process group ID. 506.\".It trss 507.\"Text resident set size, in Kilobytes. 508.It Cm tsess 509Control terminal session pointer. 510.It Cm tsiz 511Text size, in Kilobytes. 512.It Cm tt 513An abbreviation for the pathname of the controlling terminal, if any. 514The abbreviation consists of the two letters following 515.Dq /dev/tty , 516or, for the console, 517.Dq co . 518This is followed by a 519.Sq - 520if the process can no longer reach that 521controlling terminal (i.e. it has been revoked). 522.It Cm tty 523Full name of control terminal. 524.It Cm ucomm 525Alias: 526.Cm comm . 527Name to be used for accounting. 528.It Cm uid 529Effective user ID. 530.It Cm upr 531Alias: 532.Cm usrpri . 533Scheduling priority on return from system call. 534.It Cm user 535User name (from 536.Cm uid ) . 537.It Cm vsz 538Alias: 539.Cm vsize . 540Virtual size, in Kilobytes. 541.It Cm wchan 542The event (an address in the system) on which a process waits. 543When printed numerically, the initial part of the address is 544trimmed off and the result is printed in hex; for example, 0x80324000 prints 545as 324000. 546.It Cm xstat 547Exit or stop status (valid only for stopped or zombie process). 548.El 549.Sh ENVIRONMENT 550The following environment variables affect the execution of 551.Nm : 552.Bl -tag -width LC_CTYPE 553.It Ev COLUMNS 554If set to a positive integer, 555output is formatted to the given width in columns. 556Otherwise, 557.Nm 558defaults to the terminal width minus 1. 559If none of 560.Dv stdout , 561.Dv stderr , 562and 563.Dv stdin 564are a terminal, 56579 columns are used. 566.It Ev LC_CTYPE 567The character encoding 568.Xr locale 1 . 569It decides which byte sequences form characters, 570which characters are printable, and what their display width is. 571If unset or set to 572.Qq C , 573.Qq POSIX , 574or an unsupported value, only printable ASCII characters are printed. 575Tabs, newlines, non-printable ASCII characters, and non-ASCII bytes 576are encoded with 577.Xr vis 3 . 578If UTF-8 output is enabled, valid characters that are not printable 579are replaced with the Unicode replacement character U+FFFD. 580These rules for example apply to command names, arguments, and 581environments and to directory, user, and group names. 582.It Ev TZ 583The time zone to use when displaying dates. 584See 585.Xr environ 7 586for more information. 587.El 588.Sh FILES 589.Bl -tag -width "/var/db/kvm_bsd.dbXXX" -compact 590.It Pa /dev 591special files and device names 592.It Pa /var/db/kvm_bsd.db 593system namelist database 594.It Pa /var/run/dev.db 595.Pa /dev 596name database 597.El 598.Sh EXIT STATUS 599.Ex -std ps 600.Sh EXAMPLES 601Display information on all system processes: 602.Pp 603.Dl $ ps -auxw 604.Sh SEE ALSO 605.Xr fstat 1 , 606.Xr kill 1 , 607.Xr netstat 1 , 608.Xr pgrep 1 , 609.Xr pkill 1 , 610.Xr procmap 1 , 611.Xr systat 1 , 612.Xr top 1 , 613.Xr w 1 , 614.Xr kvm 3 , 615.Xr strftime 3 , 616.Xr dev_mkdb 8 , 617.Xr iostat 8 , 618.Xr pstat 8 , 619.Xr vmstat 8 620.Sh STANDARDS 621The 622.Nm 623utility is compliant with the 624.St -p1003.1-2008 625specification, 626except that the flag 627.Op Fl G 628is unsupported and 629the flags 630.Op Fl ptU 631support only single arguments, not lists. 632.Pp 633The flags 634.Op Fl defglnu 635are marked by 636.St -p1003.1-2008 637as being an X/Open System Interfaces option. 638Of these, 639.Op Fl dfgn 640are not supported by this implementation of 641.Nm ; 642behaviour for the flags 643.Op Fl elu 644differs between this implementation and the 645X/Open System Interfaces option of 646.St -p1003.1-2008 . 647.Pp 648The flags 649.Op Fl cHhjkLMmNOrSTvWwx 650are extensions to 651.St -p1003.1-2008 . 652.Pp 653Only the following keywords are recognised by 654.St -p1003.1-2008 : 655.Cm args , 656.Cm comm , 657.Cm etime , 658.Cm group , 659.Cm nice , 660.Cm pcpu , 661.Cm pgid , 662.Cm pid , 663.Cm ppid , 664.Cm rgroup , 665.Cm ruser , 666.Cm time , 667.Cm tty , 668.Cm user , 669and 670.Cm vsz . 671.Sh HISTORY 672A 673.Nm 674command first appeared in 675.At v3 . 676.Sh CAVEATS 677When printing using the 678.Cm command 679keyword, a process that has exited and 680has a parent that has not yet waited for the process (in other words, a zombie) 681is listed as 682.Dq Aq defunct , 683and a process which is blocked while trying 684to exit is listed as 685.Dq Aq exiting . 686.Nm 687makes an educated guess as to the file name and arguments given when the 688process was created by examining memory or the swap area. 689The method is inherently somewhat unreliable and in any event a process 690is entitled to destroy this information, so the names cannot be depended 691on too much. 692The 693.Cm ucomm 694(accounting) keyword can, however, be depended on. 695.Pp 696The information displayed is only a snapshot of a constantly changing system. 697