Page MenuHomeFreeBSD
Files F150443403

D49605.id152965.diff
No OneTemporary
Actions

D49605.id152965.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,96 @@
.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 in 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 that have controlling
+terminals are shown
+.Po
+as if using
+.Fl U
+with the real user ID and
+.Fl X
+.Pc .
+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 in the
+process' ID, controlling terminal, state, CPU time
+.Pq including both user and system time
+and associated command.
+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 +157,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,8 +190,26 @@
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 other users' processes in addition to your own
+.Po
+as
+.Fl U
+would determine
+.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.
@@ -159,9 +251,21 @@
but works well with it.
.It Fl e
Display the environment as well.
+.It Fl f
+Indicates to print the full command and arguments in
+.Cm commands
+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
@@ -183,7 +287,7 @@
.Fl J
.Sy 0
to display only host processes.
-This flag implies
+Implies
.Fl x
by default.
.It Fl L
@@ -208,21 +312,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 +342,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 +359,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 +390,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
@@ -765,9 +888,9 @@
.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 +924,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.
+Other UNIX systems that provide the 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 +987,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 commands
+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
Thu, Apr 2, 6:21 AM (2 h, 48 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
30711407
Default Alt Text
D49605.id152965.diff (15 KB)

Event Timeline