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
12 ps — report process status
13
15 ps [-aA] [-defl] [-g grouplist] [-G grouplist]
16 [-n namelist] [-o format]... [-p proclist] [-t termlist]
17 [-u userlist] [-U userlist]
18
20 The ps utility shall write information about processes, subject to hav‐
21 ing appropriate privileges to obtain information about those processes.
22 By default, ps shall select all processes with the same effective user
24 ID as the current user and the same controlling terminal as the
25 invoker.
26
28 The ps utility shall conform to the Base Definitions volume of
29 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
30 The following options shall be supported:
32 -a Write information for all processes associated with termi‐
34 nals. Implementations may omit session leaders from this
35 list.
36 -A Write information for all processes.
38 -d Write information for all processes, except session leaders.
40 -e Write information for all processes. (Equivalent to -A.)
42 -f Generate a full listing. (See the STDOUT section for the con‐
44 tents of a full listing.)
45 -g grouplist
47 Write information for processes whose session leaders are
48 given in grouplist. The application shall ensure that the
49 grouplist is a single argument in the form of a <blank> or
50 <comma>-separated list.
51 -G grouplist
53 Write information for processes whose real group ID numbers
54 are given in grouplist. The application shall ensure that
55 the grouplist is a single argument in the form of a <blank>
56 or <comma>-separated list.
57 -l Generate a long listing. (See STDOUT for the contents of a
59 long listing.)
60 -n namelist
62 Specify the name of an alternative system namelist file in
63 place of the default. The name of the default file and the
64 format of a namelist file are unspecified.
65 -o format Write information according to the format specification given
67 in format. This is fully described in the STDOUT section.
68 Multiple -o options can be specified; the format specifica‐
69 tion shall be interpreted as the <space>-separated concatena‐
70 tion of all the format option-arguments.
71 -p proclist
73 Write information for processes whose process ID numbers are
74 given in proclist. The application shall ensure that the
75 proclist is a single argument in the form of a <blank> or
76 <comma>-separated list.
77 -t termlist
79 Write information for processes associated with terminals
80 given in termlist. The application shall ensure that the
81 termlist is a single argument in the form of a <blank> or
82 <comma>-separated list. Terminal identifiers shall be given
83 in an implementation-defined format. On XSI-conformant sys‐
84 tems, they shall be given in one of two forms: the device's
85 filename (for example, tty04) or, if the device's filename
86 starts with tty, just the identifier following the characters
87 tty (for example, "04").
88 -u userlist
90 Write information for processes whose user ID numbers or
91 login names are given in userlist. The application shall
92 ensure that the userlist is a single argument in the form of
93 a <blank> or <comma>-separated list. In the listing, the
94 numerical user ID shall be written unless the -f option is
95 used, in which case the login name shall be written.
96 -U userlist
98 Write information for processes whose real user ID numbers or
99 login names are given in userlist. The application shall
100 ensure that the userlist is a single argument in the form of
101 a <blank> or <comma>-separated list.
102 With the exception of -f, -l, -n namelist, and -o format, all of the
104 options shown are used to select processes. If any are specified, the
105 default list shall be ignored and ps shall select the processes repre‐
106 sented by the inclusive OR of all the selection-criteria options.
107
109 None.
110
112 Not used.
113
115 None.
116
118 The following environment variables shall affect the execution of ps:
119 COLUMNS Override the system-selected horizontal display line size,
121 used to determine the number of text columns to display. See
122 the Base Definitions volume of POSIX.1‐2017, Chapter 8, Envi‐
123 ronment Variables for valid values and results when it is
124 unset or null.
125 LANG Provide a default value for the internationalization vari‐
127 ables that are unset or null. (See the Base Definitions vol‐
128 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
129 ables the precedence of internationalization variables used
130 to determine the values of locale categories.)
131 LC_ALL If set to a non-empty string value, override the values of
133 all the other internationalization variables.
134 LC_CTYPE Determine the locale for the interpretation of sequences of
136 bytes of text data as characters (for example, single-byte as
137 opposed to multi-byte characters in arguments).
138 LC_MESSAGES
140 Determine the locale that should be used to affect the format
141 and contents of diagnostic messages written to standard error
142 and informative messages written to standard output.
143 LC_TIME Determine the format and contents of the date and time
145 strings displayed.
146 NLSPATH Determine the location of message catalogs for the processing
148 of LC_MESSAGES.
149 TZ Determine the timezone used to calculate date and time
151 strings displayed. If TZ is unset or null, an unspecified
152 default timezone shall be used.
153
155 Default.
156
158 When the -o option is not specified, the standard output format is
159 unspecified.
160 On XSI-conformant systems, the output format shall be as follows. The
162 column headings and descriptions of the columns in a ps listing are
163 given below. The precise meanings of these fields are implementation-
164 defined. The letters 'f' and 'l' (below) indicate the option (full or
165 long) that shall cause the corresponding heading to appear; all means
166 that the heading always appears. Note that these two options determine
167 only what information is provided for a process; they do not determine
168 which processes are listed.
169 F (l) Flags (octal and additive) associated with
171 the process.
172 S (l) The state of the process.
173 UID (f,l) The user ID number of the process owner;
174 the login name is printed under the -f
175 option.
176 PID (all) The process ID of the process; it is possi‐
177 ble to kill a process if this datum is
178 known.
179 PPID (f,l) The process ID of the parent process.
180 C (f,l) Processor utilization for scheduling.
181 PRI (l) The priority of the process; higher numbers
182 mean lower priority.
183 NI (l) Nice value; used in priority computation.
184 ADDR (l) The address of the process.
185 SZ (l) The size in blocks of the core image of the
186 process.
187 WCHAN (l) The event for which the process is waiting
188 or sleeping; if blank, the process is run‐
189 ning.
190 STIME (f) Starting time of the process.
191 TTY (all) The controlling terminal for the process.
192 TIME (all) The cumulative execution time for the
193 process.
194 CMD (all) The command name; the full command name and
195 its arguments are written under the -f
196 option.
197 A process that has exited and has a parent, but has not yet been waited
199 for by the parent, shall be marked defunct.
200 Under the option -f, ps tries to determine the command name and argu‐
202 ments given when the process was created by examining memory or the
203 swap area. Failing this, the command name, as it would appear without
204 the option -f, is written in square brackets.
205 The -o option allows the output format to be specified under user con‐
207 trol.
208 The application shall ensure that the format specification is a list of
210 names presented as a single argument, <blank> or <comma>-separated.
211 Each variable has a default header. The default header can be overrid‐
212 den by appending an <equals-sign> and the new text of the header. The
213 rest of the characters in the argument shall be used as the header
214 text. The fields specified shall be written in the order specified on
215 the command line, and should be arranged in columns in the output. The
216 field widths shall be selected by the system to be at least as wide as
217 the header text (default or overridden value). If the header text is
218 null, such as -o user=, the field width shall be at least as wide as
219 the default header text. If all header text fields are null, no header
220 line shall be written.
221 The following names are recognized in the POSIX locale:
223 ruser The real user ID of the process. This shall be the textual user
225 ID, if it can be obtained and the field width permits, or a
226 decimal representation otherwise.
227 user The effective user ID of the process. This shall be the textual
229 user ID, if it can be obtained and the field width permits, or
230 a decimal representation otherwise.
231 rgroup The real group ID of the process. This shall be the textual
233 group ID, if it can be obtained and the field width permits, or
234 a decimal representation otherwise.
235 group The effective group ID of the process. This shall be the tex‐
237 tual group ID, if it can be obtained and the field width per‐
238 mits, or a decimal representation otherwise.
239 pid The decimal value of the process ID.
241 ppid The decimal value of the parent process ID.
243 pgid The decimal value of the process group ID.
245 pcpu The ratio of CPU time used recently to CPU time available in
247 the same period, expressed as a percentage. The meaning of
248 ``recently'' in this context is unspecified. The CPU time
249 available is determined in an unspecified manner.
250 vsz The size of the process in (virtual) memory in 1024 byte units
252 as a decimal integer.
253 nice The decimal value of the nice value of the process; see nice.
255 etime In the POSIX locale, the elapsed time since the process was
257 started, in the form:
258 [[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
273 The dd, hh, mm, and ss fields shall be as described in the
275 etime specifier.
276 tty The name of the controlling terminal of the process (if any) in
278 the same format used by the who utility.
279 comm The name of the command being executed (argv[0] value) as a
281 string.
282 args The command with all its arguments as a string. The implementa‐
284 tion may truncate this value to the field width; it is imple‐
285 mentation-defined whether any further truncation occurs. It is
286 unspecified whether the string represented is a version of the
287 argument list as it was passed to the command when it started,
288 or is a version of the arguments as they may have been modified
289 by the application. Applications cannot depend on being able to
290 modify their argument list and having that modification be
291 reflected in the output of ps.
292 Any field need not be meaningful in all implementations. In such a case
294 a <hyphen-minus> ('-') should be output in place of the field value.
295 Only comm and args shall be allowed to contain <blank> characters; all
297 others shall not. Any implementation-defined variables shall be speci‐
298 fied in the system documentation along with the default header and
299 indicating whether the field may contain <blank> characters.
300 The following table specifies the default header to be used in the
302 POSIX locale corresponding to each format specifier.
303 Table: Variable Names and Default Headers in ps
305 ┌──────────────────────────────────┬───────────────────────────────────┐
307 │Format Specifier Default Header │ Format Specifier Default Header │
308 ├──────────────────────────────────┼───────────────────────────────────┤
309 │args COMMAND │ ppid PPID │
310 │comm COMMAND │ rgroup RGROUP │
311 │etime ELAPSED │ ruser RUSER │
312 │group GROUP │ time TIME │
313 │nice NI │ tty TT │
314 │pcpu %CPU │ user USER │
315 │pgid PGID │ vsz VSZ │
316 │pid PID │ │
317 └──────────────────────────────────┴───────────────────────────────────┘
319 The standard error shall be used only for diagnostic messages.
320
322 None.
323
325 None.
326
328 The following exit values shall be returned:
329 0 Successful completion.
331 >0 An error occurred.
333
335 Default.
336 The following sections are informative.
338
340 Things can change while ps is running; the snapshot it gives is only
341 true for an instant, and might not be accurate by the time it is dis‐
342 played.
343 The args format specifier is allowed to produce a truncated version of
345 the command arguments. In some implementations, this information is no
346 longer available when the ps utility is executed.
347 If the field width is too narrow to display a textual ID, the system
349 may use a numeric version. Normally, the system would be expected to
350 choose large enough field widths, but if a large number of fields were
351 selected to write, it might squeeze fields to their minimum sizes to
352 fit on one line. One way to ensure adequate width for the textual IDs
353 is to override the default header for a field to make it larger than
354 most or all user or group names.
355 There is no special quoting mechanism for header text. The header text
357 is the rest of the argument. If multiple header changes are needed,
358 multiple -o options can be used, such as:
359 ps -o "user=User Name" -o pid=Process\ ID
362 On some implementations, especially multi-level secure systems, ps may
364 be severely restricted and produce information only about child pro‐
365 cesses owned by the user.
366
368 The command:
369 ps -o user,pid,ppid=MOM -o args
372 writes at least the following in the POSIX locale:
374 USER PID MOM COMMAND
377 helene 34 12 ps -o uid,pid,ppid=MOM -o args
378 The contents of the COMMAND field need not be the same in all implemen‐
380 tations, due to possible truncation.
381
383 There is very little commonality between BSD and System V implementa‐
384 tions of ps. Many options conflict or have subtly different usages.
385 The standard developers attempted to select a set of options for the
386 base standard that were useful on a wide range of systems and selected
387 options that either can be implemented on both BSD and System V-based
388 systems without breaking the current implementations or where the
389 options are sufficiently similar that any changes would not be unduly
390 problematic for users or implementors.
391 It is recognized that on some implementations, especially multi-level
393 secure systems, ps may be nearly useless. The default output has there‐
394 fore been chosen such that it does not break historical implementations
395 and also is likely to provide at least some useful information on most
396 systems.
397 The major change is the addition of the format specification capabil‐
399 ity. The motivation for this invention is to provide a mechanism for
400 users to access a wider range of system information, if the system per‐
401 mits it, in a portable manner. The fields chosen to appear in this vol‐
402 ume of POSIX.1‐2017 were arrived at after considering what concepts
403 were likely to be both reasonably useful to the ``average'' user and
404 had a reasonable chance of being implemented on a wide range of sys‐
405 tems. Again it is recognized that not all systems are able to provide
406 all the information and, conversely, some may wish to provide more. It
407 is hoped that the approach adopted will be sufficiently flexible and
408 extensible to accommodate most systems. Implementations may be expected
409 to introduce new format specifiers.
410 The default output should consist of a short listing containing the
412 process ID, terminal name, cumulative execution time, and command name
413 of each process.
414 The preference of the standard developers would have been to make the
416 format specification an operand of the ps command. Unfortunately, BSD
417 usage precluded this.
418 At one time a format was included to display the environment array of
420 the process. This was deleted because there is no portable way to dis‐
421 play it.
422 The -A option is equivalent to the BSD -g and the SVID -e. Because the
424 two systems differed, a mnemonic compromise was selected.
425 The -a option is described with some optional behavior because the SVID
427 omits session leaders, but BSD does not.
428 In an early proposal, format specifiers appeared for priority and start
430 time. The former was not defined adequately in this volume of
431 POSIX.1‐2017 and was removed in deference to the defined nice value;
432 the latter because elapsed time was considered to be more useful.
433 In a new BSD version of ps, a -O option can be used to write all of the
435 default information, followed by additional format specifiers. This was
436 not adopted because the default output is implementation-defined. Nev‐
437 ertheless, this is a useful option that should be reserved for that
438 purpose. In the -o option for the POSIX Shell and Utilities ps, the
439 format is the concatenation of each -o. Therefore, the user can have
440 an alias or function that defines the beginning of their desired format
441 and add more fields to the end of the output in certain cases where
442 that would be useful.
443 The format of the terminal name is unspecified, but the descriptions of
445 ps, talk, who, and write require that they all use the same format.
446 The pcpu field indicates that the CPU time available is determined in
448 an unspecified manner. This is because it is difficult to express an
449 algorithm that is useful across all possible machine architectures.
450 Historical counterparts to this value have attempted to show percentage
451 of use in the recent past, such as the preceding minute. Frequently,
452 these values for all processes did not add up to 100%. Implementations
453 are encouraged to provide data in this field to users that will help
454 them identify processes currently affecting the performance of the sys‐
455 tem.
456
458 None.
459
461 kill, nice, renice
462 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
464 Variables, Section 12.2, Utility Syntax Guidelines
465
467 Portions of this text are reprinted and reproduced in electronic form
468 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
469 table Operating System Interface (POSIX), The Open Group Base Specifi‐
470 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
471 Electrical and Electronics Engineers, Inc and The Open Group. In the
472 event of any discrepancy between this version and the original IEEE and
473 The Open Group Standard, the original IEEE and The Open Group Standard
474 is the referee document. The original Standard can be obtained online
475 at http://www.opengroup.org/unix/online.html .
476 Any typographical or formatting errors that appear in this page are
478 most likely to have been introduced during the conversion of the source
479 files to man page format. To report such errors, see https://www.ker‐
480 nel.org/doc/man-pages/reporting_bugs.html .
481IEEE/The Open Group 2017 PS(1P)