man-pages/man1p/ps.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "PS" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" ps 
.SH NAME
ps \- report process status
.SH SYNOPSIS
.LP
\fBps\fP \fB[\fP\fB-aA\fP\fB][\fP\fB-defl\fP\fB][\fP\fB-G\fP
\fIgrouplist\fP\fB][\fP\fB-o\fP \fIformat\fP\fB]\fP\fB...\fP\fB[\fP\fB-p\fP
\fIproclist\fP\fB][\fP\fB-t\fP
\fItermlist\fP\fB]
.br
.sp
[\fP\fB-U\fP \fIuserlist\fP\fB][\fP\fB-g\fP \fIgrouplist\fP\fB][\fP\fB-n\fP
\fInamelist\fP\fB][\fP\fB-u\fP
\fIuserlist\fP\fB]\fP\fB\fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIps\fP utility shall write information about processes, subject
to having the appropriate privileges to obtain
information about those processes.
.LP
By default, \fIps\fP shall select all processes with the same effective
user ID as the current user and the same controlling
terminal as the invoker.
.SH OPTIONS
.LP
The \fIps\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following options shall be supported:
.TP 7
\fB-a\fP
Write information for all processes associated with terminals. Implementations
may omit session leaders from this list.
.TP 7
\fB-A\fP
Write information for all processes.
.TP 7
\fB-d\fP
Write information for all processes, except session leaders. 
.TP 7
\fB-e\fP
Write information for all processes.  (Equivalent to
\fB-A\fP.)
.TP 7
\fB-f\fP
Generate a \fBfull\fP listing. (See the STDOUT section for the contents
of a \fBfull\fP listing.) 
.TP 7
\fB-g\ \fP \fIgrouplist\fP
Write information for processes whose session leaders are given in
\fIgrouplist\fP. The application shall ensure that the
\fIgrouplist\fP is a single argument in the form of a <blank> or comma-separated
list. 
.TP 7
\fB-G\ \fP \fIgrouplist\fP
Write information for processes whose real group ID numbers are given
in \fIgrouplist\fP. The application shall ensure that
the \fIgrouplist\fP is a single argument in the form of a <blank>
or comma-separated list.
.TP 7
\fB-l\fP
Generate a \fBlong\fP listing. (See STDOUT for the contents of a \fBlong\fP
listing.) 
.TP 7
\fB-n\ \fP \fInamelist\fP
Specify the name of an alternative system \fInamelist\fP file in place
of the default. The name of the default file and the format
of a \fInamelist\fP file are unspecified. 
.TP 7
\fB-o\ \fP \fIformat\fP
Write information according to the format specification given in \fIformat\fP.
This is fully described in the STDOUT section.
Multiple \fB-o\fP options can be specified; the format specification
shall be interpreted as the <space>-separated
concatenation of all the \fIformat\fP option-arguments.
.TP 7
\fB-p\ \fP \fIproclist\fP
Write information for processes whose process ID numbers are given
in \fIproclist\fP. The application shall ensure that the
\fIproclist\fP is a single argument in the form of a <blank> or comma-separated
list.
.TP 7
\fB-t\ \fP \fItermlist\fP
Write information for processes associated with terminals given in
\fItermlist\fP. The application shall ensure that the
\fItermlist\fP 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, \fBtty04\fP) or, if the device's filename starts with
\fBtty\fP, just the identifier following the characters
\fBtty\fP (for example, \fB"04"\fP ). 
.TP 7
\fB-u\ \fP \fIuserlist\fP
Write information for processes whose user ID numbers or login names
are given in \fIuserlist\fP. The application shall ensure
that the \fIuserlist\fP 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 \fB-f\fP option is used, in which
case the login name shall be written. 
.TP 7
\fB-U\ \fP \fIuserlist\fP
Write information for processes whose real user ID numbers or login
names are given in \fIuserlist\fP. The application shall
ensure that the \fIuserlist\fP is a single argument in the form of
a <blank> or comma-separated list.
.sp
.LP
With the exception of \fB-o\fP \fIformat\fP, all of the options shown
are used to select processes. If any are specified, the
default list shall be ignored and \fIps\fP shall select the processes
represented by the inclusive OR of all the
selection-criteria options.
.SH OPERANDS
.LP
None.
.SH STDIN
.LP
Not used.
.SH INPUT FILES
.LP
None.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIps\fP:
.TP 7
\fICOLUMNS\fP
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, Environment
Variables for valid values and results when it is unset or null.
.TP 7
\fILANG\fP
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 Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
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).
.TP 7
\fILC_MESSAGES\fP
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.
.TP 7
\fILC_TIME\fP
Determine the format and contents of the date and time strings displayed.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.TP 7
\fITZ\fP
Determine the timezone used to calculate date and time strings displayed.
If \fITZ\fP is unset or null, an unspecified default
timezone shall be used.
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
When the \fB-o\fP option is not specified, the standard output format
is unspecified.
.LP
On XSI-conformant systems, the output format shall be as follows.
The column headings and descriptions of the columns in a
\fIps\fP listing are given below. The precise meanings of these fields
are implementation-defined. The letters \fB'f'\fP and
\fB'l'\fP (below) indicate the option ( \fBfull\fP or \fBlong\fP)
that shall cause the corresponding heading to appear;
\fBall\fP 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.
.TS C
center; l l lw(40).
\fBF\fP	(l)	T{
.na
Flags (octal and additive) associated with the process.
.ad
T}
\fBS\fP	(l)	T{
.na
The state of the process.
.ad
T}
\fBUID\fP	(f,l)	T{
.na
The user ID number of the process owner; the login name is printed under the \fB-f\fP option.
.ad
T}
\fBPID\fP	(all)	T{
.na
The process ID of the process; it is possible to kill a process if this datum is known.
.ad
T}
\fBPPID\fP	(f,l)	T{
.na
The process ID of the parent process.
.ad
T}
\fBC\fP	(f,l)	T{
.na
Processor utilization for scheduling.
.ad
T}
\fBPRI\fP	(l)	T{
.na
The priority of the process; higher numbers mean lower priority.
.ad
T}
\fBNI\fP	(l)	T{
.na
Nice value; used in priority computation.
.ad
T}
\fBADDR\fP	(l)	T{
.na
The address of the process.
.ad
T}
\fBSZ\fP	(l)	T{
.na
The size in blocks of the core image of the process.
.ad
T}
\fBWCHAN\fP	(l)	T{
.na
The event for which the process is waiting or sleeping; if blank, the process is running.
.ad
T}
\fBSTIME\fP	(f)	T{
.na
Starting time of the process.
.ad
T}
\fBTTY\fP	(all)	T{
.na
The controlling terminal for the process.
.ad
T}
\fBTIME\fP	(all)	T{
.na
The cumulative execution time for the process.
.ad
T}
\fBCMD\fP	(all)	T{
.na
The command name; the full command name and its arguments are written under the \fB-f\fP option.
.ad
T}
.TE
.LP
A process that has exited and has a parent, but has not yet been waited
for by the parent, shall be marked \fBdefunct\fP.
.LP
Under the option \fB-f\fP, \fIps\fP 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 \fB-f\fP, is written in
square brackets. 
.LP
The \fB-o\fP option allows the output format to be specified under
user control.
.LP
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
\fB-o\fP \fIuser\fP=, 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.
.LP
The following names are recognized in the POSIX locale:
.TP 7
\fBruser\fP
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.
.TP 7
\fBuser\fP
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.
.TP 7
\fBrgroup\fP
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.
.TP 7
\fBgroup\fP
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.
.TP 7
\fBpid\fP
The decimal value of the process ID.
.TP 7
\fBppid\fP
The decimal value of the parent process ID.
.TP 7
\fBpgid\fP
The decimal value of the process group ID.
.TP 7
\fBpcpu\fP
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.
.TP 7
\fBvsz\fP
The size of the process in (virtual) memory in 1024 byte units as
a decimal integer.
.TP 7
\fBnice\fP
The decimal value of the nice value of the process; see \fInice\fP()
\&.
.TP 7
\fBetime\fP
In the POSIX locale, the elapsed time since the process was started,
in the form: 
.sp
.RS
.nf

\fB[[\fP\fIdd\fP\fB-\fP\fB]\fP\fIhh\fP\fB:\fP\fB]\fP\fImm\fP\fB:\fP\fIss\fP
.fi
.RE
.LP
where \fIdd\fP shall represent the number of days, \fIhh\fP the number
of hours, \fImm\fP the number of minutes, and
\fIss\fP the number of seconds. The \fIdd\fP field shall be a decimal
integer. The \fIhh\fP, \fImm\fP, and \fIss\fP fields
shall be two-digit decimal integers padded on the left with zeros.
.TP 7
\fBtime\fP
In the POSIX locale, the cumulative CPU time of the process in the
form: 
.sp
.RS
.nf

\fB[\fP\fIdd\fP\fB-\fP\fB]\fP\fIhh\fP\fB:\fP\fImm\fP\fB:\fP\fIss\fP
.fi
.RE
.LP
The \fIdd\fP, \fIhh\fP, \fImm\fP, and \fIss\fP fields shall be as
described in the \fBetime\fP specifier.
.TP 7
\fBtty\fP
The name of the controlling terminal of the process (if any) in the
same format used by the \fIwho\fP utility.
.TP 7
\fBcomm\fP
The name of the command being executed ( \fIargv\fP[0] value) as a
string.
.TP 7
\fBargs\fP
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 \fIps\fP.
.sp
.LP
Any field need not be meaningful in all implementations. In such a
case a hyphen ( \fB'-'\fP ) should be output in place of
the field value.
.LP
Only \fBcomm\fP and \fBargs\fP 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.
.LP
The following table specifies the default header to be used in the
POSIX locale corresponding to each format specifier.
.br
.sp
.ce 1
\fBTable: Variable Names and Default Headers in \fIps\fP\fP
.TS C
center; l1 l1 l1 l.
\fBFormat Specifier\fP	\fBDefault Header\fP	\fBFormat Specifier\fP	\fBDefault Header\fP
\fBargs\fP	\fBCOMMAND\fP	\fBppid\fP	\fBPPID\fP
\fBcomm\fP	\fBCOMMAND\fP	\fBrgroup\fP	\fBRGROUP\fP
\fBetime\fP	\fBELAPSED\fP	\fBruser\fP	\fBRUSER\fP
\fBgroup\fP	\fBGROUP\fP	\fBtime\fP	\fBTIME\fP
\fBnice\fP	\fBNI\fP	\fBtty\fP	\fBTT\fP
\fBpcpu\fP	\fB%CPU\fP	\fBuser\fP	\fBUSER\fP
\fBpgid\fP	\fBPGID\fP	\fBvsz\fP	\fBVSZ\fP
\fBpid\fP	\fBPID\fP	\fB\ \fP	\fB\ \fP
.TE
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.LP
None.
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
Successful completion.
.TP 7
>0
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
Default.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
Things can change while \fIps\fP is running; the snapshot it gives
is only true for an instant, and might not be accurate by
the time it is displayed.
.LP
The \fBargs\fP format specifier is allowed to produce a truncated
version of the command arguments. In some implementations,
this information is no longer available when the \fIps\fP utility
is executed.
.LP
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.
.LP
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 \fB-o\fP options can be used, such as:
.sp
.RS
.nf

\fBps -o "user=User Name" -o pid=Process\\ ID
\fP
.fi
.RE
.LP
On some implementations, especially multi-level secure systems, \fIps\fP
may be severely restricted and produce information
only about child processes owned by the user.
.SH EXAMPLES
.LP
The command:
.sp
.RS
.nf

\fBps -o user,pid,ppid=MOM -o args
\fP
.fi
.RE
.LP
writes at least the following in the POSIX locale:
.sp
.RS
.nf

\fB USER   PID   MOM   COMMAND
helene    34    12   ps -o uid,pid,ppid=MOM -o args
\fP
.fi
.RE
.LP
The contents of the \fBCOMMAND\fP field need not be the same in all
implementations, due to possible truncation.
.SH RATIONALE
.LP
There is very little commonality between BSD and System V implementations
of \fIps\fP. 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.
.LP
It is recognized that on some implementations, especially multi-level
secure systems, \fIps\fP 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.
.LP
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 IEEE\ Std\ 1003.1-2001 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.
.LP
The default output should consist of a short listing containing the
process ID, terminal name, cumulative execution time, and
command name of each process.
.LP
The preference of the standard developers would have been to make
the format specification an operand of the \fIps\fP command.
Unfortunately, BSD usage precluded this.
.LP
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.
.LP
The \fB-A\fP option is equivalent to the BSD \fB-g\fP and the SVID
\fB-e\fP. Because the two systems differed, a mnemonic
compromise was selected.
.LP
The \fB-a\fP option is described with some optional behavior because
the SVID omits session leaders, but BSD does not.
.LP
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 useful.
.LP
In a new BSD version of \fIps\fP, a \fB-O\fP 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 \fB-o\fP
option for the POSIX Shell and Utilities \fIps\fP, the
format is the concatenation of each \fB-o\fP. 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.
.LP
The format of the terminal name is unspecified, but the descriptions
of \fIps\fP, \fItalk\fP, \fIwho\fP, and \fIwrite\fP require that they
all use the same format.
.LP
The \fBpcpu\fP 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.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIkill\fP() , \fInice\fP() , \fIrenice\fP
.SH 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 .