PS(1)                      POSIX Programmer's Manual                     PS(1)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       ps -- report process status

SSYYNNOOPPSSIISS
       ps [[-aA]] [[-defl]] [[-g _g_r_o_u_p_l_i_s_t]] [[-G _g_r_o_u_p_l_i_s_t]]
           [[-n _n_a_m_e_l_i_s_t]] [[-o _f_o_r_m_a_t]]... [[-p _p_r_o_c_l_i_s_t]] [[-t _t_e_r_m_l_i_s_t]]
           [[-u _u_s_e_r_l_i_s_t]] [[-U _u_s_e_r_l_i_s_t]]

DDEESSCCRRIIPPTTIIOONN
       The _p_s utility shall write information about processes, subject to
       having appropriate privileges to obtain information about those
       processes.

       By default, _p_s shall select all processes with the same effective user
       ID as the current user and the same controlling terminal as the
       invoker.

OOPPTTIIOONNSS
       The _p_s utility shall conform to the Base Definitions volume of
       POSIX.1-2008, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The following options shall be supported:

       --aa        Write information for all processes associated with
                 terminals.  Implementations may omit session leaders from
                 this list.

       --AA        Write information for all processes.

       --dd        Write information for all processes, except session leaders.

       --ee        Write information for all processes.  (Equivalent to --AA.)

       --ff        Generate a ffuullll listing. (See the STDOUT section for the
                 contents of a ffuullll listing.)

       --gg _g_r_o_u_p_l_i_s_t
                 Write information for processes whose session leaders are
                 given in _g_r_o_u_p_l_i_s_t.  The application shall ensure that the
                 _g_r_o_u_p_l_i_s_t is a single argument in the form of a <blank> or
                 <comma>-separated list.

       --GG _g_r_o_u_p_l_i_s_t
                 Write information for processes whose real group ID numbers
                 are given in _g_r_o_u_p_l_i_s_t.  The application shall ensure that
                 the _g_r_o_u_p_l_i_s_t is a single argument in the form of a <blank>
                 or <comma>-separated list.

       --ll        Generate a lloonngg listing. (See STDOUT for the contents of a
                 lloonngg listing.)

       --nn _n_a_m_e_l_i_s_t
                 Specify the name of an alternative system _n_a_m_e_l_i_s_t file in
                 place of the default. The name of the default file and the
                 format of a _n_a_m_e_l_i_s_t file are unspecified.

       --oo _f_o_r_m_a_t Write information according to the format specification given
                 in _f_o_r_m_a_t.  This is fully described in the STDOUT section.
                 Multiple --oo options can be specified; the format
                 specification shall be interpreted as the <space>-separated
                 concatenation of all the _f_o_r_m_a_t option-arguments.

       --pp _p_r_o_c_l_i_s_t
                 Write information for processes whose process ID numbers are
                 given in _p_r_o_c_l_i_s_t.  The application shall ensure that the
                 _p_r_o_c_l_i_s_t is a single argument in the form of a <blank> or
                 <comma>-separated list.

       --tt _t_e_r_m_l_i_s_t
                 Write information for processes associated with terminals
                 given in _t_e_r_m_l_i_s_t.  The application shall ensure that the
                 _t_e_r_m_l_i_s_t 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, ttttyy0044) or, if the device's
                 filename starts with ttttyy, just the identifier following the
                 characters ttttyy (for example, ""0044"").

       --uu _u_s_e_r_l_i_s_t
                 Write information for processes whose user ID numbers or
                 login names are given in _u_s_e_r_l_i_s_t.  The application shall
                 ensure that the _u_s_e_r_l_i_s_t 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 --ff option is
                 used, in which case the login name shall be written.

       --UU _u_s_e_r_l_i_s_t
                 Write information for processes whose real user ID numbers or
                 login names are given in _u_s_e_r_l_i_s_t.  The application shall
                 ensure that the _u_s_e_r_l_i_s_t is a single argument in the form of
                 a <blank> or <comma>-separated list.

       With the exception of --ff, --ll, --nn _n_a_m_e_l_i_s_t, and --oo _f_o_r_m_a_t, all of the
       options shown are used to select processes. If any are specified, the
       default list shall be ignored and _p_s shall select the processes
       represented by the inclusive OR of all the selection-criteria options.

OOPPEERRAANNDDSS
       None.

SSTTDDIINN
       Not used.

IINNPPUUTT FFIILLEESS
       None.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _p_s:

       _C_O_L_U_M_N_S   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, _C_h_a_p_t_e_r _8,
                 _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s for valid values and results when it is
                 unset or null.

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2008, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s the precedence of internationalization variables
                 used to determine the values of locale categories.)

       _L_C___A_L_L    If set to a non-empty string value, override the values of
                 all the other internationalization variables.

       _L_C___C_T_Y_P_E  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).

       _L_C___M_E_S_S_A_G_E_S
                 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.

       _L_C___T_I_M_E   Determine the format and contents of the date and time
                 strings displayed.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

       _T_Z        Determine the timezone used to calculate date and time
                 strings displayed. If _T_Z is unset or null, an unspecified
                 default timezone shall be used.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       When the --oo 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 _p_s listing are
       given below. The precise meanings of these fields are implementation-
       defined. The letters ''ff'' and ''ll'' (below) indicate the option (ffuullll or
       lloonngg) that shall cause the corresponding heading to appear; aallll 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.

       FF       (l)     Flags (octal and additive) associated with
                       the process.
       SS       (l)     The state of the process.
       UUIIDD     (f,l)   The user ID number of the process owner;
                       the login name is printed under the --ff
                       option.
       PPIIDD     (all)   The process ID of the process; it is
                       possible to kill a process if this datum is
                       known.
       PPPPIIDD    (f,l)   The process ID of the parent process.
       CC       (f,l)   Processor utilization for scheduling.
       PPRRII     (l)     The priority of the process; higher numbers
                       mean lower priority.
       NNII      (l)     Nice value; used in priority computation.
       AADDDDRR    (l)     The address of the process.
       SSZZ      (l)     The size in blocks of the core image of the
                       process.
       WWCCHHAANN   (l)     The event for which the process is waiting
                       or sleeping; if blank, the process is
                       running.
       SSTTIIMMEE   (f)     Starting time of the process.
       TTTTYY     (all)   The controlling terminal for the process.
       TTIIMMEE    (all)   The cumulative execution time for the
                       process.



       CCMMDD     (all)   The command name; the full command name and
                       its arguments are written under the --ff
                       option.

       A process that has exited and has a parent, but has not yet been waited
       for by the parent, shall be marked ddeeffuunncctt.

       Under the option --ff, _p_s 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 --ff, is written in square brackets.

       The --oo 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 --oo _u_s_e_r=, 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:

       rruusseerr   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.

       uusseerr    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.

       rrggrroouupp  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.

       ggrroouupp   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.

       ppiidd     The decimal value of the process ID.

       ppppiidd    The decimal value of the parent process ID.

       ppggiidd    The decimal value of the process group ID.

       ppccppuu    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.

       vvsszz     The size of the process in (virtual) memory in 1024 byte units
               as a decimal integer.

       nniiccee    The decimal value of the nice value of the process; see _n_i_c_e.

       eettiimmee   In the POSIX locale, the elapsed time since the process was
               started, in the form:

                   [[[[_d_d-]]_h_h:]]_m_m:_s_s

               where _d_d shall represent the number of days, _h_h the number of
               hours, _m_m the number of minutes, and _s_s the number of seconds.
               The _d_d field shall be a decimal integer. The _h_h, _m_m, and _s_s
               fields shall be two-digit decimal integers padded on the left
               with zeros.

       ttiimmee    In the POSIX locale, the cumulative CPU time of the process in
               the form:

                   [[_d_d-]]_h_h:_m_m:_s_s

               The _d_d, _h_h, _m_m, and _s_s fields shall be as described in the
               eettiimmee specifier.

       ttttyy     The name of the controlling terminal of the process (if any) in
               the same format used by the _w_h_o utility.

       ccoommmm    The name of the command being executed (_a_r_g_v[0] value) as a
               string.

       aarrggss    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 _p_s.

       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 ccoommmm and aarrggss 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.

                                TTaabblleeNNaammeess:: VVaarriiaabbllee

       +----------------------------------+-----------------------------------+
       |FFoorrmmaatt SSppeecciiffiieerr   DDeeffaauulltt HHeeaaddeerr | FFoorrmmaatt SSppeecciiffiieerr   DDeeffaauulltt HHeeaaddeerr |
       +----------------------------------+-----------------------------------+
       |aarrggss               CCOOMMMMAANNDD        | ppppiidd               PPPPIIDD           |
       |ccoommmm               CCOOMMMMAANNDD        | rrggrroouupp             RRGGRROOUUPP         |
       |eettiimmee              EELLAAPPSSEEDD        | rruusseerr              RRUUSSEERR          |
       |ggrroouupp              GGRROOUUPP          | ttiimmee               TTIIMMEE           |
       |nniiccee               NNII             | ttttyy                TTTT             |
       |ppccppuu               %%CCPPUU           | uusseerr               UUSSEERR           |
       |ppggiidd               PPGGIIDD           | vvsszz                VVSSZZ            |
       |ppiidd                PPIIDD            |                                   |
       +----------------------------------+-----------------------------------+
SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Things can change while _p_s is running; the snapshot it gives is only
       true for an instant, and might not be accurate by the time it is
       displayed.

       The aarrggss format specifier is allowed to produce a truncated version of
       the command arguments. In some implementations, this information is no
       longer available when the _p_s 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 --oo options can be used, such as:

           ppss --oo ""uusseerr==UUsseerr NNaammee"" --oo ppiidd==PPrroocceessss\\ IIDD

       On some implementations, especially multi-level secure systems, _p_s may
       be severely restricted and produce information only about child
       processes owned by the user.

EEXXAAMMPPLLEESS
       The command:

           ppss --oo uusseerr,,ppiidd,,ppppiidd==MMOOMM --oo aarrggss

       writes at least the following in the POSIX locale:

             UUSSEERR   PPIIDD   MMOOMM   CCOOMMMMAANNDD
           hheelleennee    3344    1122   ppss --oo uuiidd,,ppiidd,,ppppiidd==MMOOMM --oo aarrggss

       The contents of the CCOOMMMMAANNDD field need not be the same in all
       implementations, due to possible truncation.

RRAATTIIOONNAALLEE
       There is very little commonality between BSD and System V
       implementations of _p_s.  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, _p_s 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 _p_s 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 --AA option is equivalent to the BSD --gg and the SVID --ee.  Because the
       two systems differed, a mnemonic compromise was selected.

       The --aa 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 _p_s, a --OO 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 --oo option for the POSIX Shell and Utilities _p_s, the
       format is the concatenation of each --oo.  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
       _p_s, _t_a_l_k, _w_h_o, and _w_r_i_t_e require that they all use the same format.

       The ppccppuu 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.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _k_i_l_l, _n_i_c_e, _r_e_n_i_c_e

       The Base Definitions volume of POSIX.1-2008, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

CCOOPPYYRRIIGGHHTT
       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(1)
