Page MenuHomeFreeBSD
Files F113848547

D49605.id153088.diff
No OneTemporary
Actions

D49605.id153088.diff
View Options

diff --git a/bin/ps/ps.1 b/bin/ps/ps.1
--- 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,7 +33,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd November 11, 2023
+.Dd March 14, 2025
.Dt PS 1
.Os
.Sh NAME
@@ -35,8 +42,9 @@
.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 ...
@@ -51,36 +59,97 @@
.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
-.Fl x
-options is specified,
-.Nm
-will also display processes that do not have controlling terminals.
-.Pp
-A different set of processes can be selected for display by using any
-combination of the
-.Fl a , D , G , J , p , T , t ,
-and
-.Fl U
-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
+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
-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.
+.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 the real user ID 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.
+Except for options
+.Fl A , a , 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 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
+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 .
+The displayed information can be tweaked by using combinations of the
+.Fl o
+and
+.Fl O
+options, which add columns with data corresponding to the passed keywords, and
+for
+.Fl O
+possibly the columns of the default display, as well as combinations of the
+.Fl j , l , u ,
+and
+.Fl v
+options, each designating a specific predefined group of columns, also called
+a canned display.
+Appearance of any of these options inhibits the default display, replacing it
+all with the requested columns, and in the order options are passed
+.Po
+except for
+.Fl O
+.Pc .
+The individual columns requested via a canned display option which have the same
+keyword as that of some column added by earlier options are not added again.
+This kind of automatic removal of duplicate keywords in canned displays is
+useful for slightly tweaking these displays without having to rebuild variants
+from scratch, e.g., using
+.Fl o
+options.
+.Pp
+Output information lines are by default sorted first by controlling terminal,
+then by process ID, and then, if
+.Fl H
+has been specified, by lightweight-process (thread) ID.
The
.Fl m , r , u ,
and
@@ -89,23 +158,29 @@
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,16 +191,33 @@
See
.Xr xo_parse_args 3
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 .
+Currently, this option has no effect if any other option selecting processes to
+display is present, except for
+.Fl X
+and
+.Fl x .
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
@@ -133,18 +225,11 @@
.Dq resident
time (this normally has
no effect).
-.It Fl d
-Arrange processes into descendancy order and prefix each command with
-indentation text showing sibling and parent/child relationships as a tree.
-If either of the
-.Fl m
-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
+.It Fl c
+Change the
.Dq command
-column is not the last column displayed.
+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
@@ -157,21 +242,43 @@
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.
+If either of the
+.Fl m
+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 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
+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
@@ -183,9 +290,14 @@
.Fl J
.Sy 0
to display only host processes.
-This flag implies
+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
@@ -208,21 +320,26 @@
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
+On first occurence, add all columns of the default display
+.Po
+as if by
+.Fl o
+.Pc
+and insert just after the process ID column in that default display the columns
+associated with the passed space- or comma-separated list of keywords.
+On next occurences, just insert the keywords of the passed list, as if by
+.Fl o .
+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.
@@ -233,6 +350,8 @@
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.
@@ -248,8 +367,15 @@
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 effective 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 ,
@@ -272,33 +398,38 @@
.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.
.It Fl Z
@@ -308,242 +439,10 @@
.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 "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 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
-.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
@@ -729,7 +628,7 @@
.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 )
@@ -753,21 +652,258 @@
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
@@ -801,10 +937,57 @@
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
+.Po
+which is the current behavior of option
+.Fl U
+.Pc .
+.Pp
+However, options
+.Fl G , l , o , p ,
+and
+.Fl t
+behave as prescribed by
+.St -p1003.1-2024 .
+Options
+.Fl A , a , f , U ,
+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.
+.Pp
+.Nm
+currently determines the processes of the current user by matching their
+effective user IDs with its own real user ID, whereas
+.St -p1003.1-2024
+mandates the traditional UNIX practice of using the effective user ID as the
+current user.
+This is expected to be changed soon.
.Sh HISTORY
The
.Nm
@@ -817,6 +1000,78 @@
cannot run faster than the system and is run as any other scheduled
process, the information it displays can never be exact.
.Pp
+.Nm
+currently uses its real user ID as the current user when determining default
+processes to show.
+Besides being inconsistent with POSIX, using the real user ID essentially makes
+sense for programs installed as setuid executables, which
+.Nm
+is not.
+It also complicates the use of
+.Nm
+from other setuid executables, which cannot rely on its default process listing.
+Finally, no other
+.Nm
+implementation (for other BSDs, illumos or Linux) behaves like this.
+For all these reasons, the behavior is expected to be changed soon to using the
+effective user ID instead.
+.Pp
+Option
+.Fl O
+has not been designed to be combined with other options as it forces insertion
+of the default display on first occurence.
+Moreover, these default display's columns are then not considered for duplicate
+elimination, contrary to those of canned displays.
+Finally, columns requested through multiple occurences are not grouped together,
+as one may naturally expect.
+.Pp
+Automatic removal of duplicate columns from canned displays only works backwards
+at time of insertion, i.e., adding a new canned display will lead to checking
+columns before it but not those after it.
+Besides the inconsistency, this prevents relocating columns of canned displays
+further right, which can be useful, e.g., to relocate a column with the
+.Cm command
+keyword at end of display.
+.Pp
+The
+.Fl a
+option has no effect if other options affecting the selection of processes are
+used, except for (non-)filters
+.Fl X
+and
+.Fl x.
+Option
+.Fl A
+has the same restriction.
+This idiosyncrasy is both in contradiction with
+.St -p1003.1-2024
+and arguably with common sense, and is expected to be removed soon.
+.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

File Metadata

Mime Type
text/plain
Expires
Sat, Apr 5, 1:05 PM (56 m, 44 s)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
17389597
Default Alt Text
D49605.id153088.diff (37 KB)

Event Timeline