ps.1p (20145B)
- '\" et
- .TH PS "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- 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.
- .\"
- .SH NAME
- ps
- \(em report process status
- .SH SYNOPSIS
- .LP
- .nf
- ps \fB[\fR-aA\fB] \*![\fR-defl\fB] [\fR-g \fIgrouplist\fB]\*? [\fR-G \fIgrouplist\fB]
- \*![\fR-n \fInamelist\fB]\*? [\fR-o \fIformat\fB]\fR... \fB[\fR-p \fIproclist\fB] [\fR-t \fItermlist\fB]
- \*![\fR-u \fIuserlist\fB]\*? [\fR-U \fIuserlist\fB]
- .fi
- .SH DESCRIPTION
- The
- .IR ps
- utility shall write information about processes, subject to having
- appropriate privileges to obtain information about those processes.
- .P
- By default,
- .IR ps
- shall select all processes with the same effective user ID as the
- current user and the same controlling terminal as the invoker.
- .SH OPTIONS
- The
- .IR ps
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- The following options shall be supported:
- .IP "\fB\-a\fP" 10
- Write information for all processes associated with terminals.
- Implementations may omit session leaders from this list.
- .IP "\fB\-A\fP" 10
- Write information for all processes.
- .IP "\fB\-d\fP" 10
- Write information for all processes, except session leaders.
- .IP "\fB\-e\fP" 10
- Write information for all processes.
- (Equivalent to
- .BR \-A .)
- .IP "\fB\-f\fP" 10
- Generate a
- .BR full
- listing. (See the STDOUT section for the contents of a
- .BR full
- listing.)
- .IP "\fB\-g\ \fIgrouplist\fR" 10
- Write information for processes whose session leaders are given in
- .IR grouplist .
- The application shall ensure that the
- .IR grouplist
- is a single argument in the form of a
- <blank>
- or
- <comma>-separated
- list.
- .IP "\fB\-G\ \fIgrouplist\fR" 10
- Write information for processes whose real group ID numbers are given
- in
- .IR grouplist .
- The application shall ensure that the
- .IR grouplist
- is a single argument in the form of a
- <blank>
- or
- <comma>-separated
- list.
- .IP "\fB\-l\fP" 10
- Generate a
- .BR long
- listing. (See STDOUT for the contents of a
- .BR long
- listing.)
- .IP "\fB\-n\ \fInamelist\fR" 10
- Specify the name of an alternative system
- .IR namelist
- file in place of the default. The name of the default file and the
- format of a
- .IR namelist
- file are unspecified.
- .IP "\fB\-o\ \fIformat\fR" 10
- Write information according to the format specification given in
- .IR format .
- This is fully described in the STDOUT section. Multiple
- .BR \-o
- options can be specified; the format specification shall be interpreted
- as the
- <space>-separated
- concatenation of all the
- .IR format
- option-arguments.
- .IP "\fB\-p\ \fIproclist\fR" 10
- Write information for processes whose process ID numbers are given in
- .IR proclist .
- The application shall ensure that the
- .IR proclist
- is a single argument in the form of a
- <blank>
- or
- <comma>-separated
- list.
- .IP "\fB\-t\ \fItermlist\fR" 10
- Write information for processes associated with terminals given in
- .IR termlist .
- The application shall ensure that the
- .IR 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,
- .BR tty04 )
- or, if the device's filename starts with
- .BR tty ,
- just the identifier following the characters
- .BR tty
- (for example,
- .BR \(dq04\(dq ).
- .IP "\fB\-u\ \fIuserlist\fR" 10
- Write information for processes whose user ID numbers or login names
- are given in
- .IR userlist .
- The application shall ensure that the
- .IR 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
- .BR \-f
- option is used, in which case the login name shall be written.
- .IP "\fB\-U\ \fIuserlist\fR" 10
- Write information for processes whose real user ID numbers or login
- names are given in
- .IR userlist .
- The application shall ensure that the
- .IR userlist
- is a single argument in the form of a
- <blank>
- or
- <comma>-separated
- list.
- .P
- With the exception of
- .BR \-f ,
- .BR \-l ,
- .BR \-n
- .IR namelist ,
- and
- .BR \-o
- .IR format ,
- all of the options shown are used to select processes. If any are
- specified, the default list shall be ignored and
- .IR ps
- shall select the processes represented by the inclusive OR of
- all the selection-criteria options.
- .SH OPERANDS
- None.
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- None.
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR ps :
- .IP "\fICOLUMNS\fP" 10
- 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\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables"
- for valid values and results when it is unset or null.
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- the precedence of internationalization variables used to determine the
- values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_CTYPE\fP" 10
- 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).
- .IP "\fILC_MESSAGES\fP" 10
- .br
- 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.
- .IP "\fILC_TIME\fP" 10
- Determine the format and contents of the date and time strings
- displayed.
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .IP "\fITZ\fP" 10
- Determine the timezone used to calculate date and time strings
- displayed. If
- .IR TZ
- is unset or null, an unspecified default timezone shall be used.
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- When the
- .BR \-o
- option is not specified, the standard output format is unspecified.
- .br
- .P
- On XSI-conformant systems, the output format shall be as follows.
- The column headings and descriptions of the columns in a
- .IR ps
- listing are given below. The precise meanings of these fields are
- implementation-defined. The letters
- .BR 'f'
- and
- .BR 'l'
- (below) indicate the option (\c
- .BR full
- or
- .BR long )
- that shall cause the corresponding heading to appear;
- .BR 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.
- .TS
- tab(@);
- lB l lw(11c).
- F@(l)@T{
- Flags (octal and additive) associated with the process.
- T}
- S@(l)@The state of the process.
- UID@(f,l)@T{
- The user ID number of the process owner; the login name is printed
- under the
- .BR \-f
- option.
- T}
- PID@(all)@T{
- The process ID of the process; it is possible to kill a process if this
- datum is known.
- T}
- PPID@(f,l)@The process ID of the parent process.
- C@(f,l)@Processor utilization for scheduling.
- PRI@(l)@T{
- The priority of the process; higher numbers mean lower priority.
- T}
- NI@(l)@T{
- Nice value; used in priority computation.
- T}
- ADDR@(l)@The address of the process.
- SZ@(l)@T{
- The size in blocks of the core image of the process.
- T}
- WCHAN@(l)@T{
- The event for which the process is waiting or sleeping; if blank, the
- process is running.
- T}
- STIME@(f)@Starting time of the process.
- TTY@(all)@The controlling terminal for the process.
- TIME@(all)@T{
- The cumulative execution time for the process.
- T}
- CMD@(all)@T{
- The command name; the full command name and its arguments are written
- under the
- .BR \-f
- option.
- T}
- .TE
- .P
- A process that has exited and has a parent, but has not yet been waited
- for by the parent, shall be marked
- .BR defunct .
- .P
- Under the option
- .BR \-f ,
- .IR 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
- .BR \-f ,
- is written in square brackets.
- .P
- The
- .BR \-o
- option allows the output format to be specified under user control.
- .P
- 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
- .BR \-o
- .IR 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.
- .P
- The following names are recognized in the POSIX locale:
- .IP "\fBruser\fR" 8
- 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.
- .IP "\fBuser\fR" 8
- 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.
- .IP "\fBrgroup\fR" 8
- 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.
- .IP "\fBgroup\fR" 8
- 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.
- .IP "\fBpid\fR" 8
- The decimal value of the process ID.
- .IP "\fBppid\fR" 8
- The decimal value of the parent process ID.
- .IP "\fBpgid\fR" 8
- The decimal value of the process group ID.
- .IP "\fBpcpu\fR" 8
- 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.
- .IP "\fBvsz\fR" 8
- The size of the process in (virtual) memory in 1\|024 byte units as a
- decimal integer.
- .IP "\fBnice\fR" 8
- The decimal value of the nice value of the process; see
- .IR nice .
- .IP "\fBetime\fR" 8
- In the POSIX locale, the elapsed time since the process was started, in
- the form:
- .RS 8
- .sp
- .RS 4
- .nf
- \fB[[\fIdd\fR-\fB]\fIhh\fR:\fB]\fImm\fR:\fIss\fR
- .fi
- .P
- .RE
- .P
- where
- .IR dd
- shall represent the number of days,
- .IR hh
- the number of hours,
- .IR mm
- the number of minutes, and
- .IR ss
- the number of seconds. The
- .IR dd
- field shall be a decimal integer. The
- .IR hh ,
- .IR mm ,
- and
- .IR ss
- fields shall be two-digit decimal integers padded on the left with
- zeros.
- .RE
- .IP "\fBtime\fR" 8
- In the POSIX locale, the cumulative CPU time of the process in the
- form:
- .RS 8
- .sp
- .RS 4
- .nf
- \fB[\fIdd\fR-\fB]\fIhh\fR:\fImm\fR:\fIss\fR
- .fi
- .P
- .RE
- .P
- The
- .IR dd ,
- .IR hh ,
- .IR mm ,
- and
- .IR ss
- fields shall be as described in the
- .BR etime
- specifier.
- .RE
- .IP "\fBtty\fR" 8
- The name of the controlling terminal of the process (if any) in the
- same format used by the
- .IR who
- utility.
- .IP "\fBcomm\fR" 8
- The name of the command being executed (\c
- .IR argv [0]
- value) as a string.
- .IP "\fBargs\fR" 8
- 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
- .IR ps .
- .P
- Any field need not be meaningful in all implementations. In such a
- case a
- <hyphen-minus>
- (\c
- .BR '\-' )
- should be output in place of the field value.
- .P
- Only
- .BR comm
- and
- .BR 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.
- .P
- 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\fR
- .TS
- center tab(@) box;
- cB cB | cB cB
- lB lB | lB lB.
- 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
- .TE
- .SH STDERR
- The standard error shall be used only for diagnostic messages.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- The following exit values shall be returned:
- .IP "\00" 6
- Successful completion.
- .IP >0 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- Things can change while
- .IR ps
- is running; the snapshot it gives is only true for an instant, and
- might not be accurate by the time it is displayed.
- .P
- The
- .BR 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
- .IR ps
- utility is executed.
- .P
- 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.
- .P
- 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
- .BR \-o
- options can be used, such as:
- .sp
- .RS 4
- .nf
- ps -o "user=User Name" -o pid=Process\e ID
- .fi
- .P
- .RE
- .P
- On some implementations, especially multi-level secure systems,
- .IR ps
- may be severely restricted and produce information only about child
- processes owned by the user.
- .SH EXAMPLES
- The command:
- .sp
- .RS 4
- .nf
- ps -o user,pid,ppid=MOM -o args
- .fi
- .P
- .RE
- .P
- writes at least the following in the POSIX locale:
- .sp
- .RS 4
- .nf
- USER PID MOM COMMAND
- helene 34 12 ps -o uid,pid,ppid=MOM -o args
- .fi
- .P
- .RE
- .P
- The contents of the
- .BR COMMAND
- field need not be the same in all implementations, due to possible
- truncation.
- .SH RATIONALE
- There is very little commonality between BSD and System V
- implementations of
- .IR 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.
- .P
- It is recognized that on some implementations, especially multi-level
- secure systems,
- .IR 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.
- .P
- 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\(hy2017
- 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.
- .P
- The default output should consist of a short listing containing the
- process ID, terminal name, cumulative execution time, and command name
- of each process.
- .P
- The preference of the standard developers would have been to make the
- format specification an operand of the
- .IR ps
- command. Unfortunately, BSD usage precluded this.
- .P
- 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.
- .P
- The
- .BR \-A
- option is equivalent to the BSD
- .BR \-g
- and the SVID
- .BR \-e .
- Because the two systems differed, a mnemonic compromise was selected.
- .P
- The
- .BR \-a
- option is described with some optional behavior because the SVID omits
- session leaders, but BSD does not.
- .P
- In an early proposal, format specifiers appeared for priority and start
- time. The former was not defined adequately in this volume of POSIX.1\(hy2017 and was removed in
- deference to the defined nice value; the latter because elapsed time
- was considered to be more useful.
- .P
- In a new BSD version of
- .IR ps ,
- a
- .BR \-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
- .BR \-o
- option for the POSIX Shell and Utilities
- .IR ps ,
- the format is the concatenation of each
- .BR \-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.
- .P
- The format of the terminal name is unspecified, but the descriptions of
- .IR ps ,
- .IR talk ,
- .IR who ,
- and
- .IR write
- require that they all use the same format.
- .P
- The
- .BR 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.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIkill\fR\^",
- .IR "\fInice\fR\^",
- .IR "\fIrenice\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- 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 .