1PS(1P)                     POSIX Programmer's Manual                    PS(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       ps — report process status
14

SYNOPSIS

16       ps [−aA] [−defl] [−g grouplist] [−G grouplist]
17           [−n namelist] [−o format]... [−p proclist] [−t termlist]
18           [−u userlist] [−U userlist]
19

DESCRIPTION

21       The ps utility shall write information about processes, subject to hav‐
22       ing appropriate privileges to obtain information about those processes.
23
24       By  default, ps shall select all processes with the same effective user
25       ID as the current  user  and  the  same  controlling  terminal  as  the
26       invoker.
27

OPTIONS

29       The  ps  utility  shall  conform  to  the  Base  Definitions  volume of
30       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
31
32       The following options shall be supported:
33
34       −a        Write information for all processes  associated  with  termi‐
35                 nals.   Implementations  may  omit  session leaders from this
36                 list.
37
38       −A        Write information for all processes.
39
40       −d        Write information for all processes, except session leaders.
41
42       −e        Write information for all processes.  (Equivalent to −A.)
43
44       −f        Generate a full listing. (See the STDOUT section for the con‐
45                 tents of a full listing.)
46
47       −g grouplist
48                 Write  information  for  processes  whose session leaders are
49                 given in grouplist.  The application shall  ensure  that  the
50                 grouplist  is  a  single argument in the form of a <blank> or
51                 <comma>-separated list.
52
53       −G grouplist
54                 Write information for processes whose real group  ID  numbers
55                 are  given  in  grouplist.  The application shall ensure that
56                 the grouplist is a single argument in the form of  a  <blank>
57                 or <comma>-separated list.
58
59       −l        Generate  a  long  listing. (See STDOUT for the contents of a
60                 long listing.)
61
62       −n namelist
63                 Specify the name of an alternative system  namelist  file  in
64                 place  of  the  default. The name of the default file and the
65                 format of a namelist file are unspecified.
66
67       −o format Write information according to the format specification given
68                 in  format.   This  is fully described in the STDOUT section.
69                 Multiple −o options can be specified; the  format  specifica‐
70                 tion shall be interpreted as the <space>-separated concatena‐
71                 tion of all the format option-arguments.
72
73       −p proclist
74                 Write information for processes whose process ID numbers  are
75                 given  in  proclist.   The  application shall ensure that the
76                 proclist is a single argument in the form  of  a  <blank>  or
77                 <comma>-separated list.
78
79       −t termlist
80                 Write  information  for  processes  associated with terminals
81                 given in termlist.  The application  shall  ensure  that  the
82                 termlist  is  a  single  argument in the form of a <blank> or
83                 <comma>-separated list. Terminal identifiers shall  be  given
84                 in  an implementation-defined format.  On XSI-conformant sys‐
85                 tems, they shall be given in one of two forms:  the  device's
86                 filename  (for  example,  tty04) or, if the device's filename
87                 starts with tty, just the identifier following the characters
88                 tty (for example, "04").
89
90       −u userlist
91                 Write  information  for  processes  whose  user ID numbers or
92                 login names are given in  userlist.   The  application  shall
93                 ensure  that the userlist is a single argument in the form of
94                 a <blank> or <comma>-separated  list.  In  the  listing,  the
95                 numerical  user  ID  shall be written unless the −f option is
96                 used, in which case the login name shall be written.
97
98       −U userlist
99                 Write information for processes whose real user ID numbers or
100                 login  names  are  given  in userlist.  The application shall
101                 ensure that the userlist is a single argument in the form  of
102                 a <blank> or <comma>-separated list.
103
104       With  the  exception  of −f, −l, −n namelist, and −o format, all of the
105       options shown are used to select processes. If any are  specified,  the
106       default  list shall be ignored and ps shall select the processes repre‐
107       sented by the inclusive OR of all the selection-criteria options.
108

OPERANDS

110       None.
111

STDIN

113       Not used.
114

INPUT FILES

116       None.
117

ENVIRONMENT VARIABLES

119       The following environment variables shall affect the execution of ps:
120
121       COLUMNS   Override the system-selected horizontal  display  line  size,
122                 used  to determine the number of text columns to display. See
123                 the Base Definitions volume of POSIX.1‐2008, Chapter 8, Envi‐
124                 ronment  Variables  for  valid  values and results when it is
125                 unset or null.
126
127       LANG      Provide a default value for  the  internationalization  vari‐
128                 ables  that are unset or null. (See the Base Definitions vol‐
129                 ume of POSIX.1‐2008, Section 8.2, Internationalization  Vari‐
130                 ables  the  precedence of internationalization variables used
131                 to determine the values of locale categories.)
132
133       LC_ALL    If set to a non-empty string value, override  the  values  of
134                 all the other internationalization variables.
135
136       LC_CTYPE  Determine  the  locale for the interpretation of sequences of
137                 bytes of text data as characters (for example, single-byte as
138                 opposed to multi-byte characters in arguments).
139
140       LC_MESSAGES
141                 Determine the locale that should be used to affect the format
142                 and contents of diagnostic messages written to standard error
143                 and informative messages written to standard output.
144
145       LC_TIME   Determine  the  format  and  contents  of  the  date and time
146                 strings displayed.
147
148       NLSPATH   Determine the location of message catalogs for the processing
149                 of LC_MESSAGES.
150
151       TZ        Determine  the  timezone  used  to  calculate  date  and time
152                 strings displayed. If TZ is unset  or  null,  an  unspecified
153                 default timezone shall be used.
154

ASYNCHRONOUS EVENTS

156       Default.
157

STDOUT

159       When  the  −o  option  is  not specified, the standard output format is
160       unspecified.
161
162       On XSI-conformant systems, the output format shall be as follows.   The
163       column  headings  and  descriptions  of the columns in a ps listing are
164       given below. The precise meanings of these fields  are  implementation-
165       defined.  The  letters 'f' and 'l' (below) indicate the option (full or
166       long) that shall cause the corresponding heading to appear;  all  means
167       that  the heading always appears. Note that these two options determine
168       only what information is provided for a process; they do not  determine
169       which processes are listed.
170
171       F       (l)     Flags  (octal and additive) associated with
172                       the process.
173       S       (l)     The state of the process.
174       UID     (f,l)   The user ID number of  the  process  owner;
175                       the  login  name  is  printed  under the −f
176                       option.
177       PID     (all)   The process ID of the process; it is possi‐
178                       ble  to  kill  a  process  if this datum is
179                       known.
180       PPID    (f,l)   The process ID of the parent process.
181       C       (f,l)   Processor utilization for scheduling.
182       PRI     (l)     The priority of the process; higher numbers
183                       mean lower priority.
184       NI      (l)     Nice value; used in priority computation.
185       ADDR    (l)     The address of the process.
186       SZ      (l)     The size in blocks of the core image of the
187                       process.
188       WCHAN   (l)     The event for which the process is  waiting
189                       or  sleeping; if blank, the process is run‐
190                       ning.
191       STIME   (f)     Starting time of the process.
192       TTY     (all)   The controlling terminal for the process.
193       TIME    (all)   The  cumulative  execution  time  for   the
194                       process.
195       CMD     (all)   The command name; the full command name and
196                       its arguments  are  written  under  the  −f
197                       option.
198
199       A process that has exited and has a parent, but has not yet been waited
200       for by the parent, shall be marked defunct.
201
202       Under the option −f, ps tries to determine the command name  and  argu‐
203       ments  given  when  the  process was created by examining memory or the
204       swap area. Failing this, the command name, as it would  appear  without
205       the option −f, is written in square brackets.
206
207       The  −o option allows the output format to be specified under user con‐
208       trol.
209
210       The application shall ensure that the format specification is a list of
211       names  presented  as  a  single argument, <blank> or <comma>-separated.
212       Each variable has a default header. The default header can be  overrid‐
213       den  by  appending an <equals-sign> and the new text of the header. The
214       rest of the characters in the argument shall  be  used  as  the  header
215       text.  The  fields specified shall be written in the order specified on
216       the command line, and should be arranged in columns in the output.  The
217       field  widths shall be selected by the system to be at least as wide as
218       the header text (default or overridden value). If the  header  text  is
219       null,  such  as  −o user=, the field width shall be at least as wide as
220       the default header text.  If all header text fields are null, no header
221       line shall be written.
222
223       The following names are recognized in the POSIX locale:
224
225       ruser   The real user ID of the process. This shall be the textual user
226               ID, if it can be obtained and the field  width  permits,  or  a
227               decimal representation otherwise.
228
229       user    The effective user ID of the process. This shall be the textual
230               user ID, if it can be obtained and the field width permits,  or
231               a decimal representation otherwise.
232
233       rgroup  The  real  group  ID  of the process. This shall be the textual
234               group ID, if it can be obtained and the field width permits, or
235               a decimal representation otherwise.
236
237       group   The  effective  group ID of the process. This shall be the tex‐
238               tual group ID, if it can be obtained and the field  width  per‐
239               mits, or a decimal representation otherwise.
240
241       pid     The decimal value of the process ID.
242
243       ppid    The decimal value of the parent process ID.
244
245       pgid    The decimal value of the process group ID.
246
247       pcpu    The  ratio  of  CPU time used recently to CPU time available in
248               the same period, expressed as  a  percentage.  The  meaning  of
249               ``recently''  in  this  context  is  unspecified.  The CPU time
250               available is determined in an unspecified manner.
251
252       vsz     The size of the process in (virtual) memory in 1024 byte  units
253               as a decimal integer.
254
255       nice    The decimal value of the nice value of the process; see nice.
256
257       etime   In  the  POSIX  locale,  the elapsed time since the process was
258               started, in the form:
259
260                   [[dd−]hh:]mm:ss
261
262               where dd shall represent the number of days, hh the  number  of
263               hours,  mm the number of minutes, and ss the number of seconds.
264               The dd field shall be a decimal integer. The  hh,  mm,  and  ss
265               fields  shall  be two-digit decimal integers padded on the left
266               with zeros.
267
268       time    In the POSIX locale, the cumulative CPU time of the process  in
269               the form:
270
271                   [dd−]hh:mm:ss
272
273               The  dd,  hh,  mm,  and  ss fields shall be as described in the
274               etime specifier.
275
276       tty     The name of the controlling terminal of the process (if any) in
277               the same format used by the who utility.
278
279       comm    The  name  of  the  command being executed (argv[0] value) as a
280               string.
281
282       args    The command with all its arguments as a string. The implementa‐
283               tion  may  truncate this value to the field width; it is imple‐
284               mentation-defined whether any further truncation occurs. It  is
285               unspecified  whether the string represented is a version of the
286               argument list as it was passed to the command when it  started,
287               or is a version of the arguments as they may have been modified
288               by the application. Applications cannot depend on being able to
289               modify  their  argument  list  and  having that modification be
290               reflected in the output of ps.
291
292       Any field need not be meaningful in all implementations. In such a case
293       a <hyphen> ('−') should be output in place of the field value.
294
295       Only  comm and args shall be allowed to contain <blank> characters; all
296       others shall not. Any implementation-defined variables shall be  speci‐
297       fied  in  the  system  documentation  along with the default header and
298       indicating whether the field may contain <blank> characters.
299
300       The following table specifies the default header  to  be  used  in  the
301       POSIX locale corresponding to each format specifier.
302
303                                TableNames: Variable
304
305       ┌──────────────────────────────────┬───────────────────────────────────┐
306Format Specifier   Default Header Format Specifier   Default Header 
307       ├──────────────────────────────────┼───────────────────────────────────┤
308args               COMMAND        ppid               PPID           
309comm               COMMAND        rgroup             RGROUP         
310etime              ELAPSED        ruser              RUSER          
311group              GROUP          time               TIME           
312nice               NI             tty                TT             
313pcpu               %CPU           user               USER           
314pgid               PGID           vsz                VSZ            
315pid                PID            │                                   │
316       └──────────────────────────────────┴───────────────────────────────────┘

STDERR

318       The standard error shall be used only for diagnostic messages.
319

OUTPUT FILES

321       None.
322

EXTENDED DESCRIPTION

324       None.
325

EXIT STATUS

327       The following exit values shall be returned:
328
329        0    Successful completion.
330
331       >0    An error occurred.
332

CONSEQUENCES OF ERRORS

334       Default.
335
336       The following sections are informative.
337

APPLICATION USAGE

339       Things  can  change  while ps is running; the snapshot it gives is only
340       true for an instant, and might not be accurate by the time it  is  dis‐
341       played.
342
343       The  args format specifier is allowed to produce a truncated version of
344       the command arguments. In some implementations, this information is  no
345       longer available when the ps utility is executed.
346
347       If  the  field  width is too narrow to display a textual ID, the system
348       may use a numeric version. Normally, the system would  be  expected  to
349       choose  large enough field widths, but if a large number of fields were
350       selected to write, it might squeeze fields to their  minimum  sizes  to
351       fit  on  one line. One way to ensure adequate width for the textual IDs
352       is to override the default header for a field to make  it  larger  than
353       most or all user or group names.
354
355       There  is no special quoting mechanism for header text. The header text
356       is the rest of the argument. If multiple  header  changes  are  needed,
357       multiple −o options can be used, such as:
358
359           ps −o "user=User Name" −o pid=Process\ ID
360
361       On  some implementations, especially multi-level secure systems, ps may
362       be severely restricted and produce information only  about  child  pro‐
363       cesses owned by the user.
364

EXAMPLES

366       The command:
367
368           ps −o user,pid,ppid=MOM −o args
369
370       writes at least the following in the POSIX locale:
371
372             USER   PID   MOM   COMMAND
373           helene    34    12   ps −o uid,pid,ppid=MOM −o args
374
375       The contents of the COMMAND field need not be the same in all implemen‐
376       tations, due to possible truncation.
377

RATIONALE

379       There is very little commonality between BSD and System  V  implementa‐
380       tions  of  ps.   Many options conflict or have subtly different usages.
381       The standard developers attempted to select a set of  options  for  the
382       base  standard that were useful on a wide range of systems and selected
383       options that either can be implemented on both BSD and  System  V-based
384       systems  without  breaking  the  current  implementations  or where the
385       options are sufficiently similar that any changes would not  be  unduly
386       problematic for users or implementors.
387
388       It  is  recognized that on some implementations, especially multi-level
389       secure systems, ps may be nearly useless. The default output has there‐
390       fore been chosen such that it does not break historical implementations
391       and also is likely to provide at least some useful information on  most
392       systems.
393
394       The  major  change is the addition of the format specification capabil‐
395       ity. The motivation for this invention is to provide  a  mechanism  for
396       users to access a wider range of system information, if the system per‐
397       mits it, in a portable manner. The fields chosen to appear in this vol‐
398       ume  of  POSIX.1‐2008  were  arrived at after considering what concepts
399       were likely to be both reasonably useful to the  ``average''  user  and
400       had  a  reasonable  chance of being implemented on a wide range of sys‐
401       tems. Again it is recognized that not all systems are able  to  provide
402       all  the information and, conversely, some may wish to provide more. It
403       is hoped that the approach adopted will be  sufficiently  flexible  and
404       extensible to accommodate most systems. Implementations may be expected
405       to introduce new format specifiers.
406
407       The default output should consist of a  short  listing  containing  the
408       process  ID, terminal name, cumulative execution time, and command name
409       of each process.
410
411       The preference of the standard developers would have been to  make  the
412       format  specification  an operand of the ps command. Unfortunately, BSD
413       usage precluded this.
414
415       At one time a format was included to display the environment  array  of
416       the  process. This was deleted because there is no portable way to dis‐
417       play it.
418
419       The −A option is equivalent to the BSD −g and the SVID −e.  Because the
420       two systems differed, a mnemonic compromise was selected.
421
422       The −a option is described with some optional behavior because the SVID
423       omits session leaders, but BSD does not.
424
425       In an early proposal, format specifiers appeared for priority and start
426       time.  The  former  was  not  defined  adequately  in  this  volume  of
427       POSIX.1‐2008 and was removed in deference to the  defined  nice  value;
428       the latter because elapsed time was considered to be more useful.
429
430       In a new BSD version of ps, a −O option can be used to write all of the
431       default information, followed by additional format specifiers. This was
432       not  adopted because the default output is implementation-defined. Nev‐
433       ertheless, this is a useful option that should  be  reserved  for  that
434       purpose.  In  the  −o  option for the POSIX Shell and Utilities ps, the
435       format is the concatenation of each −o.  Therefore, the user  can  have
436       an alias or function that defines the beginning of their desired format
437       and add more fields to the end of the output  in  certain  cases  where
438       that would be useful.
439
440       The format of the terminal name is unspecified, but the descriptions of
441       ps, talk, who, and write require that they all use the same format.
442
443       The pcpu field indicates that the CPU time available is  determined  in
444       an  unspecified  manner.  This is because it is difficult to express an
445       algorithm that is useful across  all  possible  machine  architectures.
446       Historical counterparts to this value have attempted to show percentage
447       of use in the recent past, such as the  preceding  minute.  Frequently,
448       these  values for all processes did not add up to 100%. Implementations
449       are encouraged to provide data in this field to users  that  will  help
450       them identify processes currently affecting the performance of the sys‐
451       tem.
452

FUTURE DIRECTIONS

454       None.
455

SEE ALSO

457       kill, nice, renice
458
459       The Base Definitions volume of  POSIX.1‐2008,  Chapter  8,  Environment
460       Variables, Section 12.2, Utility Syntax Guidelines
461
463       Portions  of  this text are reprinted and reproduced in electronic form
464       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
465       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
466       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
467       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
468       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
469       event of any discrepancy between this version and the original IEEE and
470       The Open Group Standard, the original IEEE and The Open Group  Standard
471       is  the  referee document. The original Standard can be obtained online
472       at http://www.unix.org/online.html .
473
474       Any typographical or formatting errors that appear  in  this  page  are
475       most likely to have been introduced during the conversion of the source
476       files to man page format. To report such errors,  see  https://www.ker
477       nel.org/doc/man-pages/reporting_bugs.html .
478
479
480
481IEEE/The Open Group                  2013                               PS(1P)
Impressum