Man Linux: Main Page and Category List

NAME

       ps - report process status

SYNOPSIS

       ps [-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
       having the 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.

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
              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 -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,
              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
              IEEE Std 1003.1-2001,    Section    8.2,    Internationalization
              Variables  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
              timezone 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
                              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>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
       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.

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
       implementations, due to possible truncation.

RATIONALE

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

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

       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.

FUTURE DIRECTIONS

       None.

SEE ALSO

       kill() , 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 .