PS(P) POSIX Programmer's Manual PS(P)NAMEps - report process status
SYNOPSISps [-aA][-defl][-G grouplist][-o format]...[-p proclist][-t termlist]
[-U userlist][-g grouplist][-n namelist][-u userlist]
DESCRIPTION
The ps utility shall write information about processes, subject to hav‐
ing the appropriate privileges to obtain information about those pro‐
cesses.
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.
OPTIONS
The ps utility shall conform to the Base Definitions volume of
IEEE Std 1003.1-2001, 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 con‐
tents 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 grou‐
plist 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. Multi‐
ple -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 pro‐
clist 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 -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.
OPERANDS
None.
STDIN
Not used.
INPUT FILES
None.
ENVIRONMENT VARIABLES
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 IEEE Std 1003.1-2001, Chapter 8, Environ‐
ment 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
IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
ables for 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 time‐
zone shall be used.
ASYNCHRONOUS EVENTS
Default.
STDOUT
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 num‐
bers mean lower priority.
NI (l) Nice value; used in priority computa‐
tion.
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 wait‐
ing 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 argu‐
ments 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 con‐
trol.
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 dec‐
imal 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 avail‐
able 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 dec‐
imal 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 speci‐
fier.
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 implementa‐
tion may truncate this value to the field width; it is implemen‐
tation-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>s; 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>s.
The following table specifies the default header to be used in the
POSIX locale corresponding to each format specifier.
Table: Variable Names and Default Headers in ps
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
STDERR
The standard error shall be used only for diagnostic messages.
OUTPUT FILES
None.
EXTENDED DESCRIPTION
None.
EXIT STATUS
The following exit values shall be returned:
0 Successful completion.
>0 An error occurred.
CONSEQUENCES OF ERRORS
Default.
The following sections are informative.
APPLICATION USAGE
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 dis‐
played.
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 pro‐
cesses owned by the user.
EXAMPLES
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 implemen‐
tations, due to possible truncation.
RATIONALE
There is very little commonality between BSD and System V implementa‐
tions 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 there‐
fore 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 capabil‐
ity. The motivation for this invention is to provide a mechanism for
users to access a wider range of system information, if the system per‐
mits it, in a portable manner. The fields chosen to appear in this vol‐
ume of IEEE Std 1003.1-2001 were arrived at after considering what con‐
cepts 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 pro‐
vide all the information and, conversely, some may wish to provide
more. It is hoped that the approach adopted will be sufficiently flexi‐
ble 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 dis‐
play 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
IEEE Std 1003.1-2001 and was removed in deference to the defined nice
value; the latter because elapsed time was considered to be more use‐
ful.
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. Nev‐
ertheless, 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 sys‐
tem.
FUTURE DIRECTIONS
None.
SEE ALSOkill() , nice() , renice
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. 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.opengroup.org/unix/online.html .
IEEE/The Open Group 2003 PS(P)
