PS(1P) - phpMan

PS(1P)                     POSIX Programmer's Manual                    PS(1P)
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.
NAME
       ps -- report process status
SYNOPSIS
       ps [-aA] [-defl] [-g grouplist] [-G grouplist]
           [-n namelist] [-o format]... [-p proclist] [-t termlist]
           [-u userlist] [-U userlist]
DESCRIPTION
       The ps utility shall write information about processes, subject to hav-
       ing 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
       POSIX.1-2008, Section 12.2, Utility Syntax Guidelines.
       The following options shall be supported:
       -a        Write information for all processes  associated  with  termi-
                 nals.   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 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  specifica-
                 tion shall be interpreted as the <space>-separated concatena-
                 tion 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 sys-
                 tems, 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 -f, -l, -n namelist, and -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 repre-
       sented 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 POSIX.1-2008, Chapter 8, Envi-
                 ronment  Variables  for  valid  values and results when it is
                 unset or null.
       LANG      Provide a default value for  the  internationalization  vari-
                 ables  that are unset or null. (See the Base Definitions vol-
                 ume of POSIX.1-2008, Section 8.2, Internationalization  Vari-
                 ables  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 possi-
                       ble  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 run-
                       ning.
       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  overrid-
       den  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 tex-
               tual group ID, if it can be obtained and the field  width  per-
               mits, 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 implementa-
               tion  may  truncate this value to the field width; it is imple-
               mentation-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> characters; all
       others shall not. Any implementation-defined variables shall be  speci-
       fied  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.
                                TableNames: Variable
       +----------------------------------+-----------------------------------+
       |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  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 sys-
       tems. 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 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
       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 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 ALSO
       kill, nice, renice
       The Base Definitions volume of  POSIX.1-2008,  Chapter  8,  Environment
       Variables, Section 12.2, Utility Syntax Guidelines
COPYRIGHT
       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 Electri-
       cal  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.ker-
       nel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group                  2013                               PS(1P)