Man Pages

ps(1p) - phpMan ps(1p) - phpMan

Command: man perldoc info search(apropos)  


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 dif-
       fer (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][-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 con-
       trolling 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 Syn-
       tax 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 applica-
              tion 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-sepa-
              rated 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 prece-
              dence 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 exam-
              ple, 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  writ-
              ten 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 num-
                                                  bers mean lower priority.
                                  NI      (l)     Nice value; used in priority computa-
                                                  tion.
                                  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 wait-
                                                  ing or sleeping; if blank, the process
                                                  is running.
                                  STIME   (f)     Starting time of the process.
                                  TTY     (all)   The controlling terminal for the pro-
                                                  cess.
                                  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 append-
       ing  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  num-
       ber  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 out-
              put 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 vari-
       ables 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 implemen-
       tations, 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 simi-
       lar 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  con-
       sidering  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 exe-
       cution 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 compro-
       mise 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  ade-
       quately in this volume of IEEE Std 1003.1-2001 and was removed in deference to the defined nice value; the lat-
       ter 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  addi-
       tional  format specifiers. This was not adopted because the default output is implementation-defined. Neverthe-
       less, 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 coun-
       terparts 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, Stan-
       dard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base  Specifica-
       tions  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 Stan-
       dard,  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 .



IEEE/The Open Group                  2003                               PS(1P)