diff options
Diffstat (limited to 'bin/ps/ps.1')
| -rw-r--r-- | bin/ps/ps.1 | 889 |
1 files changed, 553 insertions, 336 deletions
diff --git a/bin/ps/ps.1 b/bin/ps/ps.1 index 25373adb7d73..542004453658 100644 --- a/bin/ps/ps.1 +++ b/bin/ps/ps.1 @@ -1,6 +1,13 @@ .\"- +.\" SPDX-License-Identifier: BSD-3-Clause +.\" .\" Copyright (c) 1980, 1990, 1991, 1993, 1994 .\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Olivier Certner +.\" <olce@FreeBSD.org> at Kumacom SARL under sponsorship from the FreeBSD + \" Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -26,10 +33,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)ps.1 8.3 (Berkeley) 4/18/94 -.\" $FreeBSD$ -.\" -.Dd June 27, 2020 +.Dd July 16, 2025 .Dt PS 1 .Os .Sh NAME @@ -38,8 +42,10 @@ .Sh SYNOPSIS .Nm .Op Fl -libxo -.Op Fl aCcdefHhjlmrSTuvwXxZ -.Op Fl O Ar fmt | Fl o Ar fmt +.Op Fl AaCcdefHhjlmrSTuvwXxZ +.Op Fl O Ar fmt +.Op Fl o Ar fmt +.Op Fl D Ar up | down | both .Op Fl G Ar gid Ns Op , Ns Ar gid Ns Ar ... .Op Fl J Ar jid Ns Op , Ns Ar jid Ns Ar ... .Op Fl M Ar core @@ -49,40 +55,106 @@ .Op Fl U Ar user Ns Op , Ns Ar user Ns Ar ... .Nm .Op Fl -libxo -.Op Fl L +.Fl L .Sh DESCRIPTION The .Nm -utility -displays a header line, followed by lines containing information about -all of your -processes that have controlling terminals. -If the +utility displays information about a selection of processes. +Its traditional text style output consists of a header line followed by one line +of information per selected process, or possibly multiple ones if using +.Fl H +.Pq one per lightweight-process . +Other output styles can be requested via +.Fl -libxo . +.Pp +By default, only the processes of the calling user, determined by matching their +effective user ID with that of the +.Nm +process, that have controlling terminals are shown. +A different set of processes can be selected for display by using combinations +of the +.Fl A , a , D , G , J , p , T , t , U , X , +and .Fl x -options is specified, +options. +Except for options +.Fl X +and +.Fl x , +as soon as one of them appears, it inhibits the default process selection, i.e., +the calling user's processes are shown only on request. +If more than one of these +.Pq with same exceptions +appear, .Nm -will also display processes that do not have controlling terminals. +will select processes as soon as they are matched by at least one of them +.Pq inclusive OR . +The +.Fl X +option can be independently used to further filter the listed processes to only +those that have a controlling terminal +.Po +except for those selected by +.Fl p +.Pc . +Its opposite, +.Fl x , +forcefully removes that filter. +If none of +.Fl X +and +.Fl x +is specified, the implied default behavior is that of +.Fl X +unless using another option whose description explicitly says that +.Fl x +is implied. .Pp -A different set of processes can be selected for display by using any -combination of the -.Fl a , G , J , p , T , t , +For each selected process, the default displayed information consists of the +process' ID, controlling terminal, state, CPU time +.Pq including both user and system time +and associated command +.Po +see the documentation for the +.Cm command +keyword below +.Pc . +This information can be tweaked using two groups of options which can be +combined as needed. +First, options +.Fl o +and +.Fl O +add columns with data corresponding to the explicitly passed keywords. +Available keywords are documented in the +.Sx KEYWORDS +section below. +They can be listed using option +.Fl L . +Second, options +.Fl j , l , u , and -.Fl U +.Fl v +designate specific predefined groups of columns, also called canned displays. +Appearance of any of these options inhibits the default display, replacing it +all with the requested columns, and in the order options are passed. +The individual columns requested via a canned display option that have the same +keyword or an alias to that of some column added by an earlier canned display +option, or by an explicit +.Fl O +or +.Fl o +option anywhere on the command line, are suppressed. +This automatic removal of duplicate data in canned displays is useful for +slightly tweaking these displays and/or combining multiple ones without having +to rebuild variants from scratch, e.g., using only +.Fl o options. -If more than one of these options are given, then -.Nm -will select all processes which are matched by at least one of the -given options. .Pp -For the processes which have been selected for display, -.Nm -will usually display one line per process. -The +Output information lines are by default sorted first by controlling terminal, +then by process ID, and then, if .Fl H -option may result in multiple output lines (one line per thread) for -some processes. -By default all of these output lines are sorted first by controlling -terminal, then by process ID. +has been specified, by lightweight-process (thread) ID. The .Fl m , r , u , and @@ -91,23 +163,29 @@ options will change the sort order. If more than one sorting option was given, then the selected processes will be sorted by the last sorting option which was specified. .Pp -For the processes which have been selected for display, the information -to display is selected based on a set of keywords (see the -.Fl L , O , -and -.Fl o -options). -The default output format includes, for each process, the process' ID, -controlling terminal, state, CPU time (including both user and system time) -and associated command. -.Pp -If the +If the traditional text output (the default) is used, the default output width is that requested by the +.Ev COLUMNS +environment variable if present, else the line width of the terminal associated +to the .Nm -process is associated with a terminal, the default output width is that of the -terminal; otherwise the output width is unlimited. +process, if any. +In all other situations, the output width is unlimited. See also the .Fl w +option and the +.Sx BUGS +section. +.Pp +For backwards compatibility, +.Nm +attempts to interpret any positional argument as a process ID, as if specified +by the +.Fl p option. +Failure to do so will trigger an error. +.Nm +also accepts the old-style BSD options, whose format and effect are left +undocumented on purpose. .Pp The options are as follows: .Bl -tag -width indent @@ -116,18 +194,30 @@ Generate output via .Xr libxo 3 in a selection of different human and machine readable formats. See -.Xr xo_parse_args 3 +.Xr xo_options 7 for details on command line arguments. +The default is the traditional text style output. +.It Fl A +Display information about all processes in the system. +Using this option is strictly equivalent to specifying both +.Fl a +and +.Fl x . +Please see their description for more information. .It Fl a -Display information about other users' processes as well as your own. +Display information about all users' processes. +It does not, however, list all processes +.Po +see +.Fl A +and +.Fl x +.Pc . If the .Va security.bsd.see_other_uids -sysctl is set to zero, this option is honored only if the UID of the user is 0. -.It Fl c -Change the -.Dq command -column output to just contain the executable name, -rather than the full command line. +sysctl is set to zero, this option is honored only if the real user ID of the +.Nm +process is 0. .It Fl C Change the way the CPU percentage is calculated by using a .Dq raw @@ -135,6 +225,23 @@ CPU calculation that ignores .Dq resident time (this normally has no effect). +.It Fl c +Change the +.Dq command +column output to just contain the executable name, +rather than the full command line. +.It Fl D +Expand the list of selected processes based on the process tree. +.Dq UP +will add the ancestor processes, +.Dq DOWN +will add the descendant processes, and +.Dq BOTH +will add both the ancestor and the descendant processes. +.Fl D +does not imply +.Fl d , +but works well with it. .It Fl d Arrange processes into descendancy order and prefix each command with indentation text showing sibling and parent/child relationships as a tree. @@ -144,27 +251,34 @@ and .Fl r options are also used, they control how sibling processes are sorted relative to each other. -Note that this option has no effect if the -.Dq command -column is not the last column displayed. +Note that this option has no effect if the last column does not have +.Cm comm , +.Cm command +or +.Cm ucomm +as its keyword. .It Fl e Display the environment as well. .It Fl f -Show command-line and environment information about swapped out processes. -This option is honored only if the UID of the user is 0. +Indicates to print the full command and arguments in +.Cm command +columns. +This is the default behavior on +.Fx . +See +.Fl c +to turn it off. .It Fl G -Display information about processes which are running with the specified -real group IDs. +Display information about processes whose real group ID matches the specified +group IDs or names. +Implies +.Fl x +by default. .It Fl H Show all of the threads associated with each process. .It Fl h Repeat the information header as often as necessary to guarantee one header per page of information. -.It Fl j -Print information associated with the following keywords: -.Cm user , pid , ppid , pgid , sid , jobc , state , tt , time , -and -.Cm command . .It Fl J Display information about processes which match the specified jail IDs. This may be either the @@ -175,10 +289,15 @@ of the jail. Use .Fl J .Sy 0 -to display only host processes. -This flag implies +to request display of host processes. +Implies .Fl x by default. +.It Fl j +Print information associated with the following keywords: +.Cm user , pid , ppid , pgid , sid , jobc , state , tt , time , +and +.Cm command . .It Fl L List the set of keywords available for the .Fl O @@ -201,21 +320,26 @@ terminal and process ID. Extract the name list from the specified system instead of the default, which is the kernel image the system has booted from. .It Fl O -Add the information associated with the space or comma separated list -of keywords specified, after the process ID, -in the default information -display. -Keywords may be appended with an equals +Save passed columns in a separate list that in the end is grafted just after the +display's first occurence of the process ID column as specified by other +options, or the default display if there is none. +If the display prepared by other options does not include a process ID column, +the list is inserted at start of the display. +Further occurences of +.Fl O +append to the to-be-grafted list of columns. +This option takes a space- or comma-separated list of keywords. +The last keyword in the list may be appended with an equals sign .Pq Ql = -sign and a string. -This causes the printed header to use the specified string instead of -the standard header. +as explained for option +.Fl o +and with the same effect. .It Fl o -Display information associated with the space or comma separated -list of keywords specified. -The last keyword in the list may be appended with an equals +Display information associated with the space- or comma-separated list of +keywords specified. +The last keyword in the list may be appended with an equals sign .Pq Ql = -sign and a string that spans the rest of the argument, and can contain +and a string that spans the rest of the argument, and can contain space and comma characters. This causes the printed header to use the specified string instead of the standard header. @@ -226,6 +350,8 @@ So the header texts for multiple keywords can be changed. If all keywords have empty header texts, no header line is written. .It Fl p Display information about processes which match the specified process IDs. +Processes selected by this option are not subject to being filtered by +.Fl X . .It Fl r Sort by current CPU usage, instead of the combination of controlling terminal and process ID. @@ -241,8 +367,15 @@ devices. Full pathnames, as well as abbreviations (see explanation of the .Cm tt keyword) can be specified. +Implies +.Fl x +by default. .It Fl U -Display the processes belonging to the specified usernames. +Display information about processes whose real user ID matches the specified +user IDs or names. +Implies +.Fl x +by default. .It Fl u Display information associated with the following keywords: .Cm user , pid , %cpu , %mem , vsz , rss , tt , state , start , time , @@ -265,35 +398,40 @@ option implies the .Fl m option. .It Fl w -Use at least 132 columns to display information, instead of the default which -is the window size if -.Nm -is associated with a terminal. -If the +Use at least 131 columns to display information. +If .Fl w -option is specified more than once, +is specified more than once, .Nm -will use as many columns as necessary without regard for the window size. -Note that this option has no effect if the -.Dq command -column is not the last column displayed. +will use as many columns as necessary. +Please see the preamble of this manual page for how the output width is +initially determined. +In particular, if the initial output width is unlimited, specifying +.Fl w +has no effect. +Please also consult the +.Sx BUGS +section. .It Fl X -When displaying processes matched by other options, skip any processes -which do not have a controlling terminal. -This is the default behaviour. +When displaying processes selected by other options, skip any processes which do +not have a controlling terminal, except for those selected through +.Fl p . +This is the default behaviour, unless using another option whose description +explicitly says that +.Fl x +is implied. .It Fl x -When displaying processes matched by other options, include processes -which do not have a controlling terminal. -This is the opposite of the -.Fl X -option. +When displaying processes selected by other options, include processes which do +not have a controlling terminal. +This option has the opposite behavior to that of +.Fl X . If both .Fl X and .Fl x -are specified in the same command, then +are specified, .Nm -will use the one which was specified last. +will obey the last occurence. .It Fl Z Add .Xr mac 4 @@ -301,228 +439,10 @@ label to the list of keywords for which .Nm will display information. .El -.Pp -A complete list of the available keywords are listed below. -Some of these keywords are further specified as follows: -.Bl -tag -width lockname -.It Cm %cpu -The CPU utilization of the process; this is a decaying average over up to -a minute of previous (real) time. -Since the time base over which this is computed varies (since processes may -be very young) it is possible for the sum of all -.Cm %cpu -fields to exceed 100%. -.It Cm %mem -The percentage of real memory used by this process. -.It Cm class -Login class associated with the process. -.It Cm flags -The flags associated with the process as in -the include file -.In sys/proc.h : -.Bl -column P_SINGLE_BOUNDARY 0x40000000 -.It Dv "P_ADVLOCK" Ta No "0x00001" Ta "Process may hold a POSIX advisory lock" -.It Dv "P_CONTROLT" Ta No "0x00002" Ta "Has a controlling terminal" -.It Dv "P_KPROC" Ta No "0x00004" Ta "Kernel process" -.It Dv "P_PPWAIT" Ta No "0x00010" Ta "Parent is waiting for child to exec/exit" -.It Dv "P_PROFIL" Ta No "0x00020" Ta "Has started profiling" -.It Dv "P_STOPPROF" Ta No "0x00040" Ta "Has thread in requesting to stop prof" -.It Dv "P_HADTHREADS" Ta No "0x00080" Ta "Has had threads (no cleanup shortcuts)" -.It Dv "P_SUGID" Ta No "0x00100" Ta "Had set id privileges since last exec" -.It Dv "P_SYSTEM" Ta No "0x00200" Ta "System proc: no sigs, stats or swapping" -.It Dv "P_SINGLE_EXIT" Ta No "0x00400" Ta "Threads suspending should exit, not wait" -.It Dv "P_TRACED" Ta No "0x00800" Ta "Debugged process being traced" -.It Dv "P_WAITED" Ta No "0x01000" Ta "Someone is waiting for us" -.It Dv "P_WEXIT" Ta No "0x02000" Ta "Working on exiting" -.It Dv "P_EXEC" Ta No "0x04000" Ta "Process called exec" -.It Dv "P_WKILLED" Ta No "0x08000" Ta "Killed, shall go to kernel/user boundary ASAP" -.It Dv "P_CONTINUED" Ta No "0x10000" Ta "Proc has continued from a stopped state" -.It Dv "P_STOPPED_SIG" Ta No "0x20000" Ta "Stopped due to SIGSTOP/SIGTSTP" -.It Dv "P_STOPPED_TRACE" Ta No "0x40000" Ta "Stopped because of tracing" -.It Dv "P_STOPPED_SINGLE" Ta No "0x80000" Ta "Only one thread can continue" -.It Dv "P_PROTECTED" Ta No "0x100000" Ta "Do not kill on memory overcommit" -.It Dv "P_SIGEVENT" Ta No "0x200000" Ta "Process pending signals changed" -.It Dv "P_SINGLE_BOUNDARY" Ta No "0x400000" Ta "Threads should suspend at user boundary" -.It Dv "P_HWPMC" Ta No "0x800000" Ta "Process is using HWPMCs" -.It Dv "P_JAILED" Ta No "0x1000000" Ta "Process is in jail" -.It Dv "P_TOTAL_STOP" Ta No "0x2000000" Ta "Stopped for system suspend" -.It Dv "P_INEXEC" Ta No "0x4000000" Ta Process is in Xr execve 2 -.It Dv "P_STATCHILD" Ta No "0x8000000" Ta "Child process stopped or exited" -.It Dv "P_INMEM" Ta No "0x10000000" Ta "Loaded into memory" -.It Dv "P_SWAPPINGOUT" Ta No "0x20000000" Ta "Process is being swapped out" -.It Dv "P_SWAPPINGIN" Ta No "0x40000000" Ta "Process is being swapped in" -.It Dv "P_PPTRACE" Ta No "0x80000000" Ta "Vforked child issued ptrace(PT_TRACEME)" -.El -.It Cm flags2 -The flags kept in -.Va p_flag2 -associated with the process as in -the include file -.In sys/proc.h : -.Bl -column P2_INHERIT_PROTECTED 0x00000001 -.It Dv "P2_INHERIT_PROTECTED" Ta No "0x00000001" Ta "New children get P_PROTECTED" -.It Dv "P2_NOTRACE" Ta No "0x00000002" Ta "No" Xr ptrace 2 attach or coredumps -.It Dv "P2_NOTRACE_EXEC" Ta No "0x00000004" Ta Keep P2_NOPTRACE on Xr execve 2 -.It Dv "P2_AST_SU" Ta No "0x00000008" Ta "Handles SU ast for kthreads" -.It Dv "P2_PTRACE_FSTP" Ta No "0x00000010" Ta "SIGSTOP from PT_ATTACH not yet handled" -.El -.It Cm label -The MAC label of the process. -.It Cm lim -The soft limit on memory used, specified via a call to -.Xr setrlimit 2 . -.It Cm lstart -The exact time the command started, using the -.Ql %c -format described in -.Xr strftime 3 . -.It Cm lockname -The name of the lock that the process is currently blocked on. -If the name is invalid or unknown, then -.Dq ???\& -is displayed. -.It Cm logname -The login name associated with the session the process is in (see -.Xr getlogin 2 ) . -.It Cm mwchan -The event name if the process is blocked normally, or the lock name if -the process is blocked on a lock. -See the wchan and lockname keywords -for details. -.It Cm nice -The process scheduling increment (see -.Xr setpriority 2 ) . -.It Cm rss -the real memory (resident set) size of the process (in 1024 byte units). -.It Cm start -The time the command started. -If the command started less than 24 hours ago, the start time is -displayed using the -.Dq Li %H:%M -format described in -.Xr strftime 3 . -If the command started less than 7 days ago, the start time is -displayed using the -.Dq Li %a%H -format. -Otherwise, the start time is displayed using the -.Dq Li %e%b%y -format. -.It Cm state -The state is given by a sequence of characters, for example, -.Dq Li RWNA . -The first character indicates the run state of the process: -.Pp -.Bl -tag -width indent -compact -.It Li D -Marks a process in disk (or other short term, uninterruptible) wait. -.It Li I -Marks a process that is idle (sleeping for longer than about 20 seconds). -.It Li L -Marks a process that is waiting to acquire a lock. -.It Li R -Marks a runnable process. -.It Li S -Marks a process that is sleeping for less than about 20 seconds. -.It Li T -Marks a stopped process. -.It Li W -Marks an idle interrupt thread. -.It Li Z -Marks a dead process (a -.Dq zombie ) . -.El -.Pp -Additional characters after these, if any, indicate additional state -information: -.Pp -.Bl -tag -width indent -compact -.It Li + -The process is in the foreground process group of its control terminal. -.It Li < -The process has raised CPU scheduling priority. -.It Li C -The process is in -.Xr capsicum 4 -capability mode. -.It Li E -The process is trying to exit. -.It Li J -Marks a process which is in -.Xr jail 2 . -The hostname of the prison can be found in -.Pa /proc/ Ns Ao Ar pid Ac Ns Pa /status . -.It Li L -The process has pages locked in core (for example, for raw I/O). -.It Li N -The process has reduced CPU scheduling priority (see -.Xr setpriority 2 ) . -.It Li s -The process is a session leader. -.It Li V -The process' parent is suspended during a -.Xr vfork 2 , -waiting for the process to exec or exit. -.It Li W -The process is swapped out. -.It Li X -The process is being traced or debugged. -.El -.It Cm tt -An abbreviation for the pathname of the controlling terminal, if any. -The abbreviation consists of the three letters following -.Pa /dev/tty , -or, for pseudo-terminals, the corresponding entry in -.Pa /dev/pts . -This is followed by a -.Ql - -if the process can no longer reach that -controlling terminal (i.e., it has been revoked). -A -.Ql - -without a preceding two letter abbreviation or pseudo-terminal device number -indicates a process which never had a controlling terminal. -The full pathname of the controlling terminal is available via the -.Cm tty -keyword. -.It Cm wchan -The event (an address in the system) on which a process waits. -When printed numerically, the initial part of the address is -trimmed off and the result is printed in hex, for example, 0x80324000 prints -as 324000. -.El -.Pp -When printing using the command keyword, a process that has exited and -has a parent that has not yet waited for the process (in other words, a zombie) -is listed as -.Dq Li <defunct> , -and a process which is blocked while trying -to exit is listed as -.Dq Li <exiting> . -If the arguments cannot be located (usually because it has not been set, as is -the case of system processes and/or kernel threads) the command name is printed -within square brackets. -The -.Nm -utility first tries to obtain the arguments cached by the kernel (if they were -shorter than the value of the -.Va kern.ps_arg_cache_limit -sysctl). -The process can change the arguments shown with -.Xr setproctitle 3 . -Otherwise, -.Nm -makes an educated guess as to the file name and arguments given when the -process was created by examining memory or the swap area. -The method is inherently somewhat unreliable and in any event a process -is entitled to destroy this information. -The ucomm (accounting) keyword can, however, be depended on. -If the arguments are unavailable or do not agree with the ucomm keyword, -the value for the ucomm keyword is appended to the arguments in parentheses. .Sh KEYWORDS -The following is a complete list of the available keywords and their -meanings. +The following is a complete list of the available keywords and their meanings. Several of them have aliases (keywords which are synonyms). +Detailed descriptions for some of them can be found after this list. .Pp .Bl -tag -width ".Cm sigignore" -compact .It Cm %cpu @@ -548,7 +468,7 @@ number of copy-on-write faults The processor number on which the process is executing (visible only on SMP systems). .It Cm dsiz -data size (in Kbytes) +data size in KiB .It Cm emul system-call emulation environment (ABI) .It Cm etime @@ -647,7 +567,7 @@ real group ID .It Cm rgroup group name (from rgid) .It Cm rss -resident set size +resident set size in KiB .It Cm rtprio realtime priority (see .Xr rtprio 1) @@ -672,7 +592,7 @@ blocked signals (alias .It Cm sl sleep time (in seconds; 127 = infinity) .It Cm ssiz -stack size (in Kbytes) +stack size in KiB .It Cm start time started .It Cm state @@ -698,17 +618,17 @@ control terminal process group ID .It Cm tracer tracer process ID .\".It Cm trss -.\"text resident set size (in Kbytes) +.\"text resident set size in KiB .It Cm tsid control terminal session ID .It Cm tsiz -text size (in Kbytes) +text size in KiB .It Cm tt control terminal name (two letter abbreviation) .It Cm tty full name of control terminal .It Cm ucomm -name to be used for accounting +process name used for accounting .It Cm uid effective user ID (alias .Cm euid ) @@ -724,7 +644,7 @@ accumulated user CPU time .It Cm vmaddr vmspace pointer .It Cm vsz -virtual size in Kbytes (alias +virtual size in KiB (alias .Cm vsize ) .It Cm wchan wait channel (as a symbolic name) @@ -732,21 +652,258 @@ wait channel (as a symbolic name) exit or stop status (valid only for stopped or zombie process) .El .Pp -Note that the -.Cm pending -column displays bitmask of signals pending in the process queue when +Some of these keywords are further specified as follows: +.Bl -tag -width lockname +.It Cm %cpu +The CPU utilization of the process; this is a decaying average over up to +a minute of previous (real) time. +Since the time base over which this is computed varies (since processes may +be very young) it is possible for the sum of all +.Cm %cpu +fields to exceed 100%. +.It Cm %mem +The percentage of real memory used by this process. +.It Cm class +Login class associated with the process. +.It Cm command +The printed command and arguments are determined as follows. +A process that has exited and has a parent that has not yet waited for the +process (in other words, a zombie) is listed as +.Dq Li <defunct>. +If the arguments cannot be located +.Po +usually because they have not been set, as is the case for system processes +and/or kernel threads +.Pc , +the command name is printed within square brackets. +The +.Nm +utility first tries to obtain the arguments cached by the kernel +.Po +if they were shorter than the value of the +.Va kern.ps_arg_cache_limit +sysctl +.Pc . +The process can change the arguments shown with +.Xr setproctitle 3 . +Otherwise, +.Nm +makes an educated guess as to the file name and arguments given when the +process was created by examining memory or the swap area. +The method is inherently somewhat unreliable and in any event a process +is entitled to destroy this information. +The +.Cm ucomm +keyword +.Pq accounting +can, however, be depended on. +If the arguments are unavailable or do not agree with the +.Cm ucomm +keyword, the value for the +.Cm ucomm +keyword is appended to the arguments in parentheses. +.It Cm flags +The flags associated with the process as in +the include file +.In sys/proc.h : +.Bl -column P_SINGLE_BOUNDARY 0x40000000 +.It Dv "P_ADVLOCK" Ta No "0x00000001" Ta "Process may hold a POSIX advisory lock" +.It Dv "P_CONTROLT" Ta No "0x00000002" Ta "Has a controlling terminal" +.It Dv "P_KPROC" Ta No "0x00000004" Ta "Kernel process" +.It Dv "P_PPWAIT" Ta No "0x00000010" Ta "Parent is waiting for child to exec/exit" +.It Dv "P_PROFIL" Ta No "0x00000020" Ta "Has started profiling" +.It Dv "P_STOPPROF" Ta No "0x00000040" Ta "Has thread in requesting to stop prof" +.It Dv "P_HADTHREADS" Ta No "0x00000080" Ta "Has had threads (no cleanup shortcuts)" +.It Dv "P_SUGID" Ta No "0x00000100" Ta "Had set id privileges since last exec" +.It Dv "P_SYSTEM" Ta No "0x00000200" Ta "System proc: no sigs, stats or swapping" +.It Dv "P_SINGLE_EXIT" Ta No "0x00000400" Ta "Threads suspending should exit, not wait" +.It Dv "P_TRACED" Ta No "0x00000800" Ta "Debugged process being traced" +.It Dv "P_WAITED" Ta No "0x00001000" Ta "Someone is waiting for us" +.It Dv "P_WEXIT" Ta No "0x00002000" Ta "Working on exiting" +.It Dv "P_EXEC" Ta No "0x00004000" Ta "Process called exec" +.It Dv "P_WKILLED" Ta No "0x00008000" Ta "Killed, shall go to kernel/user boundary ASAP" +.It Dv "P_CONTINUED" Ta No "0x00010000" Ta "Proc has continued from a stopped state" +.It Dv "P_STOPPED_SIG" Ta No "0x00020000" Ta "Stopped due to SIGSTOP/SIGTSTP" +.It Dv "P_STOPPED_TRACE" Ta No "0x00040000" Ta "Stopped because of tracing" +.It Dv "P_STOPPED_SINGLE" Ta No "0x00080000" Ta "Only one thread can continue" +.It Dv "P_PROTECTED" Ta No "0x00100000" Ta "Do not kill on memory overcommit" +.It Dv "P_SIGEVENT" Ta No "0x00200000" Ta "Process pending signals changed" +.It Dv "P_SINGLE_BOUNDARY" Ta No "0x00400000" Ta "Threads should suspend at user boundary" +.It Dv "P_HWPMC" Ta No "0x00800000" Ta "Process is using HWPMCs" +.It Dv "P_JAILED" Ta No "0x01000000" Ta "Process is in jail" +.It Dv "P_TOTAL_STOP" Ta No "0x02000000" Ta "Stopped for system suspend" +.It Dv "P_INEXEC" Ta No "0x04000000" Ta Process is in Xr execve 2 +.It Dv "P_STATCHILD" Ta No "0x08000000" Ta "Child process stopped or exited" +.It Dv "P_INMEM" Ta No "0x10000000" Ta "Always set, unused" +.It Dv "P_PPTRACE" Ta No "0x80000000" Ta "Vforked child issued ptrace(PT_TRACEME)" +.El +.It Cm flags2 +The flags kept in +.Va p_flag2 +associated with the process as in +the include file +.In sys/proc.h : +.Bl -column P2_INHERIT_PROTECTED 0x00000001 +.It Dv "P2_INHERIT_PROTECTED" Ta No "0x00000001" Ta "New children get P_PROTECTED" +.It Dv "P2_NOTRACE" Ta No "0x00000002" Ta "No" Xr ptrace 2 attach or coredumps +.It Dv "P2_NOTRACE_EXEC" Ta No "0x00000004" Ta Keep P2_NOPTRACE on Xr execve 2 +.It Dv "P2_AST_SU" Ta No "0x00000008" Ta "Handles SU ast for kthreads" +.It Dv "P2_PTRACE_FSTP" Ta No "0x00000010" Ta "SIGSTOP from PT_ATTACH not yet handled" +.It Dv "P2_TRAPCAP" Ta No "0x00000020" Ta "SIGTRAP on ENOTCAPABLE" +.It Dv "P2_ASLR_ENABLE" Ta No "0x00000040" Ta "Force enable ASLR" +.It Dv "P2_ASLR_DISABLE" Ta No "0x00000080" Ta "Force disable ASLR" +.It Dv "P2_ASLR_IGNSTART" Ta No "0x00000100" Ta "Enable ASLR to consume sbrk area" +.It Dv "P2_PROTMAX_ENABLE" Ta No "0x00000200" Ta "Force enable implied PROT_MAX" +.It Dv "P2_PROTMAX_DISABLE" Ta No "0x00000400" Ta "Force disable implied PROT_MAX" +.It Dv "P2_STKGAP_DISABLE" Ta No "0x00000800" Ta "Disable stack gap for MAP_STACK" +.It Dv "P2_STKGAP_DISABLE_EXEC" Ta No "0x00001000" Ta "Stack gap disabled after exec" +.It Dv "P2_ITSTOPPED" Ta No "0x00002000" Ta "itimers stopped (as part of process stop)" +.It Dv "P2_PTRACEREQ" Ta No "0x00004000" Ta "Active ptrace req" +.It Dv "P2_NO_NEW_PRIVS" Ta No "0x00008000" Ta "Ignore setuid on exec" +.It Dv "P2_WXORX_DISABLE" Ta No "0x00010000" Ta "WX mappings enabled" +.It Dv "P2_WXORX_ENABLE_EXEC" Ta No "0x00020000" Ta "WxorX enabled after exec" +.It Dv "P2_WEXIT" Ta No "0x00040000" Ta "Internal exit early state" +.It Dv "P2_REAPKILLED" Ta No "0x00080000" Ta "REAP_KILL pass handled the process" +.It Dv "P2_MEMBAR_PRIVE" Ta No "0x00100000" Ta "membarrier private expedited registered" +.It Dv "P2_MEMBAR_PRIVE_SYNCORE" Ta No "0x00200000" Ta "membarrier private expedited sync core registered" +.It Dv "P2_MEMBAR_GLOBE" Ta No "0x00400000" Ta "membar global expedited registered" +.El +.It Cm label +The MAC label of the process. +.It Cm lim +The soft limit on memory used, specified via a call to +.Xr setrlimit 2 . +.It Cm lstart +The exact time the command started, using the +.Ql %c +format described in +.Xr strftime 3 . +.It Cm lockname +The name of the lock that the process is currently blocked on. +If the name is invalid or unknown, then +.Dq ???\& +is displayed. +.It Cm logname +The login name associated with the session the process is in (see +.Xr getlogin 2 ) . +.It Cm mwchan +The event name if the process is blocked normally, or the lock name if +the process is blocked on a lock. +See the wchan and lockname keywords +for details. +.It Cm nice +The process scheduling increment (see +.Xr setpriority 2 ) . +.It Cm rss +the real memory (resident set) size of the process in KiB. +.It Cm start +The time the command started. +If the command started less than 24 hours ago, the start time is +displayed using the +.Dq Li %H:%M +format described in +.Xr strftime 3 . +If the command started less than 7 days ago, the start time is +displayed using the +.Dq Li %a%H +format. +Otherwise, the start time is displayed using the +.Dq Li %e%b%y +format. +.It Cm sig +The bitmask of signals pending in the process queue if the .Fl H -option is not specified, otherwise the per-thread queue of pending signals -is shown. +option has not been specified, else the per-thread queue of pending signals. +.It Cm state +The state is given by a sequence of characters, for example, +.Dq Li RWNA . +The first character indicates the run state of the process: +.Pp +.Bl -tag -width indent -compact +.It Li D +Marks a process in disk (or other short term, uninterruptible) wait. +.It Li I +Marks a process that is idle (sleeping for longer than about 20 seconds). +.It Li L +Marks a process that is waiting to acquire a lock. +.It Li R +Marks a runnable process. +.It Li S +Marks a process that is sleeping for less than about 20 seconds. +.It Li T +Marks a stopped process. +.It Li W +Marks an idle interrupt thread. +.It Li Z +Marks a dead process (a +.Dq zombie ) . +.El +.Pp +Additional characters after these, if any, indicate additional state +information: +.Pp +.Bl -tag -width indent -compact +.It Li + +The process is in the foreground process group of its control terminal. +.It Li < +The process has raised CPU scheduling priority. +.It Li C +The process is in +.Xr capsicum 4 +capability mode. +.It Li E +The process is trying to exit. +.It Li J +Marks a process which is in +.Xr jail 2 . +The hostname of the prison can be found in +.Pa /proc/ Ns Ao Ar pid Ac Ns Pa /status . +.It Li L +The process has pages locked in core (for example, for raw I/O). +.It Li N +The process has reduced CPU scheduling priority (see +.Xr setpriority 2 ) . +.It Li s +The process is a session leader. +.It Li V +The process' parent is suspended during a +.Xr vfork 2 , +waiting for the process to exec or exit. +.It Li X +The process is being traced or debugged. +.El +.It Cm tt +An abbreviation for the pathname of the controlling terminal, if any. +The abbreviation consists of the three letters following +.Pa /dev/tty , +or, for pseudo-terminals, the corresponding entry in +.Pa /dev/pts . +This is followed by a +.Ql - +if the process can no longer reach that +controlling terminal (i.e., it has been revoked). +A +.Ql - +without a preceding two letter abbreviation or pseudo-terminal device number +indicates a process which never had a controlling terminal. +The full pathname of the controlling terminal is available via the +.Cm tty +keyword. +.It Cm wchan +The event (an address in the system) on which a process waits. +When printed numerically, the initial part of the address is +trimmed off and the result is printed in hex, for example, 0x80324000 prints +as 324000. +.El .Sh ENVIRONMENT The following environment variables affect the execution of .Nm : .Bl -tag -width ".Ev COLUMNS" .It Ev COLUMNS If set, specifies the user's preferred output width in column positions. -By default, -.Nm -attempts to automatically determine the terminal width. +Only affects the traditional text style output. +Please see the preamble of this manual page on how the final output width is +determined. .El .Sh FILES .Bl -tag -width ".Pa /boot/kernel/kernel" -compact @@ -768,9 +925,9 @@ Display information on all system processes: .Xr kvm 3 , .Xr libxo 3 , .Xr strftime 3 , -.Xr xo_parse_args 3 , +.Xr xo_options 7 , .Xr mac 4 , -.Xr procfs 5 , +.Xr procfs 4 , .Xr pstat 8 , .Xr sysctl 8 , .Xr mutex 9 @@ -780,10 +937,45 @@ For historical reasons, the utility under .Fx supports a different set of options from what is described by -.St -p1003.2 , +.St -p1003.1-2024 and what is supported on .No non- Ns Bx operating systems. +.Pp +In particular, and contrary to this implementation, POSIX specifies that option +.Fl d +should serve to select all processes except session leaders, option +.Fl e +to select all processes +.Po +equivalently to +.Fl A +.Pc , +and option +.Fl u +to select processes by effective user ID. +.Pp +However, options +.Fl A , a , G , l , o , p , U , +and +.Fl t +behave as prescribed by +.St -p1003.1-2024 . +Options +.Fl f +and +.Fl w +currently do not, but may be changed to in the future. +.Pp +POSIX's option +.Fl g , +to select processes having the specified processes as their session leader, is +not implemented. +However, other UNIX systems that provide this functionality do so via option +.Fl s +instead, reserving +.Fl g +to query by group leaders. .Sh HISTORY The .Nm @@ -796,6 +988,31 @@ Since cannot run faster than the system and is run as any other scheduled process, the information it displays can never be exact. .Pp +.Nm ps +currently does not correctly limit the ouput width, and in most cases does not +limit it at all when it should. +Regardless of the target width, requested columns are always all printed and +with widths allowing to entirely print their longest values, except for columns +with keyword +.Cm command +or +.Cm args +that are not last in the display +.Pq they are truncated to 16 bytes , +and for the last column in the display if its keyword requests textual +information of variable length, such as the +.Cm command , jail , +and +.Cm user +keywords do. +This considerably limits the effects and usefulness of the terminal width on the +output, and consequently that of the +.Ev COLUMNS +environment variable and the +.Fl w +option +.Pq if specified only once . +.Pp The .Nm utility does not correctly display argument lists containing multibyte |