1PS(1P) POSIX Programmer's Manual PS(1P)
2
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
13 ps — report process status
14
16 ps [−aA] [−defl] [−g grouplist] [−G grouplist]
17 [−n namelist] [−o format]... [−p proclist] [−t termlist]
18 [−u userlist] [−U userlist]
19
21 The ps utility shall write information about processes, subject to hav‐
22 ing appropriate privileges to obtain information about those processes.
23 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
29 The ps utility shall conform to the Base Definitions volume of
30 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
31 The following options shall be supported:
33 −a Write information for all processes associated with termi‐
35 nals. Implementations may omit session leaders from this
36 list.
37 −A Write information for all processes.
39 −d Write information for all processes, except session leaders.
41 −e Write information for all processes. (Equivalent to −A.)
43 −f Generate a full listing. (See the STDOUT section for the con‐
45 tents of a full listing.)
46 −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 −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 −l Generate a long listing. (See STDOUT for the contents of a
60 long listing.)
61 −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 −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 −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 −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 −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 −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 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
110 None.
111
113 Not used.
114
116 None.
117
119 The following environment variables shall affect the execution of ps:
120 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 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 LC_ALL If set to a non-empty string value, override the values of
134 all the other internationalization variables.
135 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 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 LC_TIME Determine the format and contents of the date and time
146 strings displayed.
147 NLSPATH Determine the location of message catalogs for the processing
149 of LC_MESSAGES.
150 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
156 Default.
157
159 When the −o option is not specified, the standard output format is
160 unspecified.
161 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 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 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 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 The −o option allows the output format to be specified under user con‐
208 trol.
209 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 The following names are recognized in the POSIX locale:
224 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 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 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 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 pid The decimal value of the process ID.
242 ppid The decimal value of the parent process ID.
244 pgid The decimal value of the process group ID.
246 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 vsz The size of the process in (virtual) memory in 1024 byte units
253 as a decimal integer.
254 nice The decimal value of the nice value of the process; see nice.
256 etime In the POSIX locale, the elapsed time since the process was
258 started, in the form:
259 [[dd−]hh:]mm:ss
261 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 time In the POSIX locale, the cumulative CPU time of the process in
269 the form:
270 [dd−]hh:mm:ss
272 The dd, hh, mm, and ss fields shall be as described in the
274 etime specifier.
275 tty The name of the controlling terminal of the process (if any) in
277 the same format used by the who utility.
278 comm The name of the command being executed (argv[0] value) as a
280 string.
281 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 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 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 The following table specifies the default header to be used in the
301 POSIX locale corresponding to each format specifier.
302 TableNames: Variable
304 ┌──────────────────────────────────┬───────────────────────────────────┐
306 │Format Specifier Default Header │ Format Specifier Default Header │
307 ├──────────────────────────────────┼───────────────────────────────────┤
308 │args COMMAND │ ppid PPID │
309 │comm COMMAND │ rgroup RGROUP │
310 │etime ELAPSED │ ruser RUSER │
311 │group GROUP │ time TIME │
312 │nice NI │ tty TT │
313 │pcpu %CPU │ user USER │
314 │pgid PGID │ vsz VSZ │
315 │pid PID │ │
316 └──────────────────────────────────┴───────────────────────────────────┘
318 The standard error shall be used only for diagnostic messages.
319
321 None.
322
324 None.
325
327 The following exit values shall be returned:
328 0 Successful completion.
330 >0 An error occurred.
332
334 Default.
335 The following sections are informative.
337
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 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 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 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 ps −o "user=User Name" −o pid=Process\ ID
360 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
366 The command:
367 ps −o user,pid,ppid=MOM −o args
369 writes at least the following in the POSIX locale:
371 USER PID MOM COMMAND
373 helene 34 12 ps −o uid,pid,ppid=MOM −o args
374 The contents of the COMMAND field need not be the same in all implemen‐
376 tations, due to possible truncation.
377
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 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 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 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 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 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 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 The −a option is described with some optional behavior because the SVID
423 omits session leaders, but BSD does not.
424 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 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 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 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
454 None.
455
457 kill, nice, renice
458 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 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 .
478IEEE/The Open Group 2013 PS(1P)