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