|
PROLOG | NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT |
PS(1P) POSIX Programmer's Manual PS(1P)
This manual page is part of the POSIX Programmer's Manual. The Linux
implementation of this interface may differ (consult the
corresponding Linux manual page for details of Linux behavior), or
the interface may not be implemented on Linux.
ps — report process status
ps [−aA] [−defl] [−g grouplist] [−G grouplist]
[−n namelist] [−o format]... [−p proclist] [−t termlist]
[−u userlist] [−U userlist]
The ps utility shall write information about processes, subject to
having appropriate privileges to obtain information about those
processes.
By default, ps shall select all processes with the same effective
user ID as the current user and the same controlling terminal as the
invoker.
The ps utility shall conform to the Base Definitions volume of
POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
The following options shall be supported:
−a Write information for all processes associated with
terminals. Implementations may omit session leaders from
this list.
−A Write information for all processes.
−d Write information for all processes, except session
leaders.
−e Write information for all processes. (Equivalent to −A.)
−f Generate a full listing. (See the STDOUT section for the
contents of a full listing.)
−g grouplist
Write information for processes whose session leaders are
given in grouplist. The application shall ensure that the
grouplist is a single argument in the form of a <blank> or
<comma>-separated list.
−G grouplist
Write information for processes whose real group ID numbers
are given in grouplist. The application shall ensure that
the grouplist is a single argument in the form of a <blank>
or <comma>-separated list.
−l Generate a long listing. (See STDOUT for the contents of a
long listing.)
−n namelist
Specify the name of an alternative system namelist file in
place of the default. The name of the default file and the
format of a namelist file are unspecified.
−o format Write information according to the format specification
given in format. This is fully described in the STDOUT
section. Multiple −o options can be specified; the format
specification shall be interpreted as the <space>-separated
concatenation of all the format option-arguments.
−p proclist
Write information for processes whose process ID numbers
are given in proclist. The application shall ensure that
the proclist is a single argument in the form of a <blank>
or <comma>-separated list.
−t termlist
Write information for processes associated with terminals
given in termlist. The application shall ensure that the
termlist is a single argument in the form of a <blank> or
<comma>-separated list. Terminal identifiers shall be given
in an implementation-defined format. On XSI-conformant
systems, they shall be given in one of two forms: the
device's filename (for example, tty04) or, if the device's
filename starts with tty, just the identifier following the
characters tty (for example, "04").
−u userlist
Write information for processes whose user ID numbers or
login names are given in userlist. The application shall
ensure that the userlist is a single argument in the form
of a <blank> or <comma>-separated list. In the listing, the
numerical user ID shall be written unless the −f option is
used, in which case the login name shall be written.
−U userlist
Write information for processes whose real user ID numbers
or login names are given in userlist. The application
shall ensure that the userlist is a single argument in the
form of a <blank> or <comma>-separated list.
With the exception of −f, −l, −n namelist, and −o format, all of the
options shown are used to select processes. If any are specified, the
default list shall be ignored and ps shall select the processes
represented by the inclusive OR of all the selection-criteria
options.
None.
Not used.
None.
The following environment variables shall affect the execution of ps:
COLUMNS Override the system-selected horizontal display line size,
used to determine the number of text columns to display.
See the Base Definitions volume of POSIX.1‐2008, Chapter 8,
Environment Variables for valid values and results when it
is unset or null.
LANG Provide a default value for the internationalization
variables that are unset or null. (See the Base Definitions
volume of POSIX.1‐2008, Section 8.2, Internationalization
Variables the precedence of internationalization variables
used to determine the values of locale categories.)
LC_ALL If set to a non-empty string value, override the values of
all the other internationalization variables.
LC_CTYPE Determine the locale for the interpretation of sequences of
bytes of text data as characters (for example, single-byte
as opposed to multi-byte characters in arguments).
LC_MESSAGES
Determine the locale that should be used to affect the
format and contents of diagnostic messages written to
standard error and informative messages written to standard
output.
LC_TIME Determine the format and contents of the date and time
strings displayed.
NLSPATH Determine the location of message catalogs for the
processing of LC_MESSAGES.
TZ Determine the timezone used to calculate date and time
strings displayed. If TZ is unset or null, an unspecified
default timezone shall be used.
Default.
When the −o option is not specified, the standard output format is
unspecified.
On XSI-conformant systems, the output format shall be as follows.
The column headings and descriptions of the columns in a ps listing
are given below. The precise meanings of these fields are
implementation-defined. The letters 'f' and 'l' (below) indicate the
option (full or long) that shall cause the corresponding heading to
appear; all means that the heading always appears. Note that these
two options determine only what information is provided for a
process; they do not determine which processes are listed.
F (l) Flags (octal and additive) associated with
the process.
S (l) The state of the process.
UID (f,l) The user ID number of the process owner;
the login name is printed under the −f
option.
PID (all) The process ID of the process; it is
possible to kill a process if this datum is
known.
PPID (f,l) The process ID of the parent process.
C (f,l) Processor utilization for scheduling.
PRI (l) The priority of the process; higher numbers
mean lower priority.
NI (l) Nice value; used in priority computation.
ADDR (l) The address of the process.
SZ (l) The size in blocks of the core image of the
process.
WCHAN (l) The event for which the process is waiting
or sleeping; if blank, the process is
running.
STIME (f) Starting time of the process.
TTY (all) The controlling terminal for the process.
TIME (all) The cumulative execution time for the
process.
CMD (all) The command name; the full command name and
its arguments are written under the −f
option.
A process that has exited and has a parent, but has not yet been
waited for by the parent, shall be marked defunct.
Under the option −f, ps tries to determine the command name and
arguments given when the process was created by examining memory or
the swap area. Failing this, the command name, as it would appear
without the option −f, is written in square brackets.
The −o option allows the output format to be specified under user
control.
The application shall ensure that the format specification is a list
of names presented as a single argument, <blank> or
<comma>-separated. Each variable has a default header. The default
header can be overridden by appending an <equals-sign> and the new
text of the header. The rest of the characters in the argument shall
be used as the header text. The fields specified shall be written in
the order specified on the command line, and should be arranged in
columns in the output. The field widths shall be selected by the
system to be at least as wide as the header text (default or
overridden value). If the header text is null, such as −o user=, the
field width shall be at least as wide as the default header text. If
all header text fields are null, no header line shall be written.
The following names are recognized in the POSIX locale:
ruser The real user ID of the process. This shall be the textual
user ID, if it can be obtained and the field width permits,
or a decimal representation otherwise.
user The effective user ID of the process. This shall be the
textual user ID, if it can be obtained and the field width
permits, or a decimal representation otherwise.
rgroup The real group ID of the process. This shall be the textual
group ID, if it can be obtained and the field width permits,
or a decimal representation otherwise.
group The effective group ID of the process. This shall be the
textual group ID, if it can be obtained and the field width
permits, or a decimal representation otherwise.
pid The decimal value of the process ID.
ppid The decimal value of the parent process ID.
pgid The decimal value of the process group ID.
pcpu The ratio of CPU time used recently to CPU time available in
the same period, expressed as a percentage. The meaning of
``recently'' in this context is unspecified. The CPU time
available is determined in an unspecified manner.
vsz The size of the process in (virtual) memory in 1024 byte
units as a decimal integer.
nice The decimal value of the nice value of the process; see nice.
etime In the POSIX locale, the elapsed time since the process was
started, in the form:
[[dd−]hh:]mm:ss
where dd shall represent the number of days, hh the number of
hours, mm the number of minutes, and ss the number of
seconds. The dd field shall be a decimal integer. The hh, mm,
and ss fields shall be two-digit decimal integers padded on
the left with zeros.
time In the POSIX locale, the cumulative CPU time of the process
in the form:
[dd−]hh:mm:ss
The dd, hh, mm, and ss fields shall be as described in the
etime specifier.
tty The name of the controlling terminal of the process (if any)
in the same format used by the who utility.
comm The name of the command being executed (argv[0] value) as a
string.
args The command with all its arguments as a string. The
implementation may truncate this value to the field width; it
is implementation-defined whether any further truncation
occurs. It is unspecified whether the string represented is a
version of the argument list as it was passed to the command
when it started, or is a version of the arguments as they may
have been modified by the application. Applications cannot
depend on being able to modify their argument list and having
that modification be reflected in the output of ps.
Any field need not be meaningful in all implementations. In such a
case a <hyphen> ('−') should be output in place of the field value.
Only comm and args shall be allowed to contain <blank> characters;
all others shall not. Any implementation-defined variables shall be
specified in the system documentation along with the default header
and indicating whether the field may contain <blank> characters.
The following table specifies the default header to be used in the
POSIX locale corresponding to each format specifier.
TableNames: Variable
┌──────────────────────────────────┬───────────────────────────────────┐
│Format Specifier Default Header │ Format Specifier Default Header │
├──────────────────────────────────┼───────────────────────────────────┤
│args COMMAND │ ppid PPID │
│comm COMMAND │ rgroup RGROUP │
│etime ELAPSED │ ruser RUSER │
│group GROUP │ time TIME │
│nice NI │ tty TT │
│pcpu %CPU │ user USER │
│pgid PGID │ vsz VSZ │
│pid PID │ │
└──────────────────────────────────┴───────────────────────────────────┘
The standard error shall be used only for diagnostic messages.
None.
None.
The following exit values shall be returned:
0 Successful completion.
>0 An error occurred.
Default.
The following sections are informative.
Things can change while ps is running; the snapshot it gives is only
true for an instant, and might not be accurate by the time it is
displayed.
The args format specifier is allowed to produce a truncated version
of the command arguments. In some implementations, this information
is no longer available when the ps utility is executed.
If the field width is too narrow to display a textual ID, the system
may use a numeric version. Normally, the system would be expected to
choose large enough field widths, but if a large number of fields
were selected to write, it might squeeze fields to their minimum
sizes to fit on one line. One way to ensure adequate width for the
textual IDs is to override the default header for a field to make it
larger than most or all user or group names.
There is no special quoting mechanism for header text. The header
text is the rest of the argument. If multiple header changes are
needed, multiple −o options can be used, such as:
ps −o "user=User Name" −o pid=Process\ ID
On some implementations, especially multi-level secure systems, ps
may be severely restricted and produce information only about child
processes owned by the user.
The command:
ps −o user,pid,ppid=MOM −o args
writes at least the following in the POSIX locale:
USER PID MOM COMMAND
helene 34 12 ps −o uid,pid,ppid=MOM −o args
The contents of the COMMAND field need not be the same in all
implementations, due to possible truncation.
There is very little commonality between BSD and System V
implementations of ps. Many options conflict or have subtly
different usages. The standard developers attempted to select a set
of options for the base standard that were useful on a wide range of
systems and selected options that either can be implemented on both
BSD and System V-based systems without breaking the current
implementations or where the options are sufficiently similar that
any changes would not be unduly problematic for users or
implementors.
It is recognized that on some implementations, especially multi-level
secure systems, ps may be nearly useless. The default output has
therefore been chosen such that it does not break historical
implementations and also is likely to provide at least some useful
information on most systems.
The major change is the addition of the format specification
capability. The motivation for this invention is to provide a
mechanism for users to access a wider range of system information, if
the system permits it, in a portable manner. The fields chosen to
appear in this volume of POSIX.1‐2008 were arrived at after
considering what concepts were likely to be both reasonably useful to
the ``average'' user and had a reasonable chance of being implemented
on a wide range of systems. Again it is recognized that not all
systems are able to provide all the information and, conversely, some
may wish to provide more. It is hoped that the approach adopted will
be sufficiently flexible and extensible to accommodate most systems.
Implementations may be expected to introduce new format specifiers.
The default output should consist of a short listing containing the
process ID, terminal name, cumulative execution time, and command
name of each process.
The preference of the standard developers would have been to make the
format specification an operand of the ps command. Unfortunately, BSD
usage precluded this.
At one time a format was included to display the environment array of
the process. This was deleted because there is no portable way to
display it.
The −A option is equivalent to the BSD −g and the SVID −e. Because
the two systems differed, a mnemonic compromise was selected.
The −a option is described with some optional behavior because the
SVID omits session leaders, but BSD does not.
In an early proposal, format specifiers appeared for priority and
start time. The former was not defined adequately in this volume of
POSIX.1‐2008 and was removed in deference to the defined nice value;
the latter because elapsed time was considered to be more useful.
In a new BSD version of ps, a −O option can be used to write all of
the default information, followed by additional format specifiers.
This was not adopted because the default output is implementation-
defined. Nevertheless, this is a useful option that should be
reserved for that purpose. In the −o option for the POSIX Shell and
Utilities ps, the format is the concatenation of each −o. Therefore,
the user can have an alias or function that defines the beginning of
their desired format and add more fields to the end of the output in
certain cases where that would be useful.
The format of the terminal name is unspecified, but the descriptions
of ps, talk, who, and write require that they all use the same
format.
The pcpu field indicates that the CPU time available is determined in
an unspecified manner. This is because it is difficult to express an
algorithm that is useful across all possible machine architectures.
Historical counterparts to this value have attempted to show
percentage of use in the recent past, such as the preceding minute.
Frequently, these values for all processes did not add up to 100%.
Implementations are encouraged to provide data in this field to users
that will help them identify processes currently affecting the
performance of the system.
None.
kill(1p), nice(1p), renice(1p)
The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
Variables, Section 12.2, Utility Syntax Guidelines
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information
Technology -- Portable Operating System Interface (POSIX), The Open
Group Base Specifications Issue 7, Copyright (C) 2013 by the
Institute of Electrical and Electronics Engineers, Inc and The Open
Group. (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
applied.) In the event of any discrepancy between this version and
the original IEEE and The Open Group Standard, the original IEEE and
The Open Group Standard is the referee document. The original
Standard can be obtained online at http://www.unix.org/online.html .
Any typographical or formatting errors that appear in this page are
most likely to have been introduced during the conversion of the
source files to man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group 2013 PS(1P)
Pages that refer to this page: kill(1p)