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][-o format]...[-p proclist][-t termlist]
16 [-U userlist][-g grouplist][-n namelist][-u userlist]
18
21 The ps utility shall write information about processes, subject to hav‐
22 ing the appropriate privileges to obtain information about those pro‐
23 cesses.
24 By default, ps shall select all processes with the same effective user
26 ID as the current user and the same controlling terminal as the
27 invoker.
28
30 The ps utility shall conform to the Base Definitions volume of
31 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
32 The following options shall be supported:
34 -a Write information for all processes associated with terminals.
36 Implementations may omit session leaders from this 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 given
49 in grouplist. The application shall ensure that the grouplist is
50 a single argument in the form of a <blank> or comma-separated
51 list.
52 -G grouplist
54 Write information for processes whose real group ID numbers are
55 given in grouplist. The application shall ensure that the grou‐
56 plist is a single argument in the form of a <blank> or comma-
57 separated list.
58 -l Generate a long listing. (See STDOUT for the contents of a long
60 listing.)
61 -n namelist
63 Specify the name of an alternative system namelist file in place
64 of the default. The name of the default file and the format of a
65 namelist file are unspecified.
66 -o format
68 Write information according to the format specification given in
69 format. This is fully described in the STDOUT section. Multi‐
70 ple -o options can be specified; the format specification shall
71 be interpreted as the <space>-separated concatenation of all the
72 format option-arguments.
73 -p proclist
75 Write information for processes whose process ID numbers are
76 given in proclist. The application shall ensure that the pro‐
77 clist is a single argument in the form of a <blank> or comma-
78 separated list.
79 -t termlist
81 Write information for processes associated with terminals given
82 in termlist. The application shall ensure that the termlist is a
83 single argument in the form of a <blank> or comma-separated
84 list. Terminal identifiers shall be given in an implementation-
85 defined format. On XSI-conformant systems, they shall be given
86 in one of two forms: the device's filename (for example, tty04)
87 or, if the device's filename starts with tty, just the identi‐
88 fier following the characters tty (for example, "04" ).
89 -u userlist
91 Write information for processes whose user ID numbers or login
92 names are given in userlist. The application shall ensure that
93 the userlist is a single argument in the form of a <blank> or
94 comma-separated list. In the listing, the numerical user ID
95 shall be written unless the -f option is used, in which case the
96 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 ensure
101 that the userlist is a single argument in the form of a <blank>
102 or comma-separated list.
103 With the exception of -o format, all of the options shown are used to
106 select processes. If any are specified, the default list shall be
107 ignored and ps shall select the processes represented by the inclusive
108 OR of all the selection-criteria options.
109
111 None.
112
114 Not used.
115
117 None.
118
120 The following environment variables shall affect the execution of ps:
121 COLUMNS
123 Override the system-selected horizontal display line size, used
124 to determine the number of text columns to display. See the Base
125 Definitions volume of IEEE Std 1003.1-2001, Chapter 8, Environ‐
126 ment Variables for valid values and results when it is unset or
127 null.
128 LANG Provide a default value for the internationalization variables
130 that are unset or null. (See the Base Definitions volume of
131 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
132 ables for the precedence of internationalization variables used
133 to determine the values of locale categories.)
134 LC_ALL If set to a non-empty string value, override the values of all
136 the other internationalization variables.
137 LC_CTYPE
139 Determine the locale for the interpretation of sequences of
140 bytes of text data as characters (for example, single-byte as
141 opposed to multi-byte characters in arguments).
142 LC_MESSAGES
144 Determine the locale that should be used to affect the format
145 and contents of diagnostic messages written to standard error
146 and informative messages written to standard output.
147 LC_TIME
149 Determine the format and contents of the date and time strings
150 displayed.
151 NLSPATH
153 Determine the location of message catalogs for the processing of
154 LC_MESSAGES .
155 TZ Determine the timezone used to calculate date and time strings
157 displayed. If TZ is unset or null, an unspecified default time‐
158 zone shall be used.
159
162 Default.
163
165 When the -o option is not specified, the standard output format is
166 unspecified.
167 On XSI-conformant systems, the output format shall be as follows. The
169 column headings and descriptions of the columns in a ps listing are
170 given below. The precise meanings of these fields are implementation-
171 defined. The letters 'f' and 'l' (below) indicate the option ( full or
172 long) that shall cause the corresponding heading to appear; all means
173 that the heading always appears. Note that these two options determine
174 only what information is provided for a process; they do not determine
175 which processes are listed.
176 F (l) Flags (octal and additive) associated
178 with the process.
179 S (l) The state of the process.
180 UID (f,l) The user ID number of the process owner;
181 the login name is printed under the -f
182 option.
183 PID (all) The process ID of the process; it is
184 possible to kill a process if this datum
185 is known.
186 PPID (f,l) The process ID of the parent process.
187 C (f,l) Processor utilization for scheduling.
188 PRI (l) The priority of the process; higher num‐
189 bers mean lower priority.
190 NI (l) Nice value; used in priority computa‐
191 tion.
192 ADDR (l) The address of the process.
193 SZ (l) The size in blocks of the core image of
194 the process.
195 WCHAN (l) The event for which the process is wait‐
196 ing or sleeping; if blank, the process
197 is running.
198 STIME (f) Starting time of the process.
200 TTY (all) The controlling terminal for the
201 process.
202 TIME (all) The cumulative execution time for the
203 process.
204 CMD (all) The command name; the full command name
205 and its arguments are written under the
206 -f option.
207 A process that has exited and has a parent, but has not yet been waited
209 for by the parent, shall be marked defunct.
210 Under the option -f, ps tries to determine the command name and argu‐
212 ments given when the process was created by examining memory or the
213 swap area. Failing this, the command name, as it would appear without
214 the option -f, is written in square brackets.
215 The -o option allows the output format to be specified under user con‐
217 trol.
218 The application shall ensure that the format specification is a list of
220 names presented as a single argument, <blank> or comma-separated. Each
221 variable has a default header. The default header can be overridden by
222 appending an equals sign and the new text of the header. The rest of
223 the characters in the argument shall be used as the header text. The
224 fields specified shall be written in the order specified on the command
225 line, and should be arranged in columns in the output. The field widths
226 shall be selected by the system to be at least as wide as the header
227 text (default or overridden value). If the header text is null, such as
228 -o user=, the field width shall be at least as wide as the default
229 header text. If all header text fields are null, no header line shall
230 be written.
231 The following names are recognized in the POSIX locale:
233 ruser The real user ID of the process. This shall be the textual user
235 ID, if it can be obtained and the field width permits, or a dec‐
236 imal representation otherwise.
237 user The effective user ID of the process. This shall be the textual
239 user ID, if it can be obtained and the field width permits, or a
240 decimal representation otherwise.
241 rgroup The real group ID of the process. This shall be the textual
243 group ID, if it can be obtained and the field width permits, or
244 a decimal representation otherwise.
245 group The effective group ID of the process. This shall be the textual
247 group ID, if it can be obtained and the field width permits, or
248 a decimal representation otherwise.
249 pid The decimal value of the process ID.
251 ppid The decimal value of the parent process ID.
253 pgid The decimal value of the process group ID.
255 pcpu The ratio of CPU time used recently to CPU time available in the
257 same period, expressed as a percentage. The meaning of
258 "recently" in this context is unspecified. The CPU time avail‐
259 able is determined in an unspecified manner.
260 vsz The size of the process in (virtual) memory in 1024 byte units
262 as a decimal integer.
263 nice The decimal value of the nice value of the process; see nice() .
265 etime In the POSIX locale, the elapsed time since the process was
267 started, in the form:
268 [[dd-]hh:]mm:ss
271 where dd shall represent the number of days, hh the number of hours, mm
273 the number of minutes, and ss the number of seconds. The dd field shall
274 be a decimal integer. The hh, mm, and ss fields shall be two-digit dec‐
275 imal integers padded on the left with zeros.
276 time In the POSIX locale, the cumulative CPU time of the process in
278 the form:
279 [dd-]hh:mm:ss
282 The dd, hh, mm, and ss fields shall be as described in the etime speci‐
284 fier.
285 tty The name of the controlling terminal of the process (if any) in
287 the same format used by the who utility.
288 comm The name of the command being executed ( argv[0] value) as a
290 string.
291 args The command with all its arguments as a string. The implementa‐
293 tion may truncate this value to the field width; it is implemen‐
294 tation-defined whether any further truncation occurs. It is
295 unspecified whether the string represented is a version of the
296 argument list as it was passed to the command when it started,
297 or is a version of the arguments as they may have been modified
298 by the application. Applications cannot depend on being able to
299 modify their argument list and having that modification be
300 reflected in the output of ps.
301 Any field need not be meaningful in all implementations. In such a case
304 a hyphen ( '-' ) should be output in place of the field value.
305 Only comm and args shall be allowed to contain <blank>s; all others
307 shall not. Any implementation-defined variables shall be specified in
308 the system documentation along with the default header and indicating
309 whether the field may contain <blank>s.
310 The following table specifies the default header to be used in the
312 POSIX locale corresponding to each format specifier.
313 Table: Variable Names and Default Headers in ps
315 Format Specifier Default Header Format Specifier Default Header
317 args COMMAND ppid PPID
318 comm COMMAND rgroup RGROUP
319 etime ELAPSED ruser RUSER
320 group GROUP time TIME
321 nice NI tty TT
322 pcpu %CPU user USER
323 pgid PGID vsz VSZ
324 pid PID
325
327 The standard error shall be used only for diagnostic messages.
328
330 None.
331
333 None.
334
336 The following exit values shall be returned:
337 0 Successful completion.
339 >0 An error occurred.
341
344 Default.
345 The following sections are informative.
347
349 Things can change while ps is running; the snapshot it gives is only
350 true for an instant, and might not be accurate by the time it is dis‐
351 played.
352 The args format specifier is allowed to produce a truncated version of
354 the command arguments. In some implementations, this information is no
355 longer available when the ps utility is executed.
356 If the field width is too narrow to display a textual ID, the system
358 may use a numeric version. Normally, the system would be expected to
359 choose large enough field widths, but if a large number of fields were
360 selected to write, it might squeeze fields to their minimum sizes to
361 fit on one line. One way to ensure adequate width for the textual IDs
362 is to override the default header for a field to make it larger than
363 most or all user or group names.
364 There is no special quoting mechanism for header text. The header text
366 is the rest of the argument. If multiple header changes are needed,
367 multiple -o options can be used, such as:
368 ps -o "user=User Name" -o pid=Process\ ID
371 On some implementations, especially multi-level secure systems, ps may
373 be severely restricted and produce information only about child pro‐
374 cesses owned by the user.
375
377 The command:
378 ps -o user,pid,ppid=MOM -o args
381 writes at least the following in the POSIX locale:
383 USER PID MOM COMMAND
386 helene 34 12 ps -o uid,pid,ppid=MOM -o args
387 The contents of the COMMAND field need not be the same in all implemen‐
389 tations, due to possible truncation.
390
392 There is very little commonality between BSD and System V implementa‐
393 tions of ps. Many options conflict or have subtly different usages. The
394 standard developers attempted to select a set of options for the base
395 standard that were useful on a wide range of systems and selected
396 options that either can be implemented on both BSD and System V-based
397 systems without breaking the current implementations or where the
398 options are sufficiently similar that any changes would not be unduly
399 problematic for users or implementors.
400 It is recognized that on some implementations, especially multi-level
402 secure systems, ps may be nearly useless. The default output has there‐
403 fore been chosen such that it does not break historical implementations
404 and also is likely to provide at least some useful information on most
405 systems.
406 The major change is the addition of the format specification capabil‐
408 ity. The motivation for this invention is to provide a mechanism for
409 users to access a wider range of system information, if the system per‐
410 mits it, in a portable manner. The fields chosen to appear in this vol‐
411 ume of IEEE Std 1003.1-2001 were arrived at after considering what con‐
412 cepts were likely to be both reasonably useful to the "average" user
413 and had a reasonable chance of being implemented on a wide range of
414 systems. Again it is recognized that not all systems are able to pro‐
415 vide all the information and, conversely, some may wish to provide
416 more. It is hoped that the approach adopted will be sufficiently flexi‐
417 ble and extensible to accommodate most systems. Implementations may be
418 expected to introduce new format specifiers.
419 The default output should consist of a short listing containing the
421 process ID, terminal name, cumulative execution time, and command name
422 of each process.
423 The preference of the standard developers would have been to make the
425 format specification an operand of the ps command. Unfortunately, BSD
426 usage precluded this.
427 At one time a format was included to display the environment array of
429 the process. This was deleted because there is no portable way to dis‐
430 play it.
431 The -A option is equivalent to the BSD -g and the SVID -e. Because the
433 two systems differed, a mnemonic compromise was selected.
434 The -a option is described with some optional behavior because the SVID
436 omits session leaders, but BSD does not.
437 In an early proposal, format specifiers appeared for priority and start
439 time. The former was not defined adequately in this volume of
440 IEEE Std 1003.1-2001 and was removed in deference to the defined nice
441 value; the latter because elapsed time was considered to be more use‐
442 ful.
443 In a new BSD version of ps, a -O option can be used to write all of the
445 default information, followed by additional format specifiers. This was
446 not adopted because the default output is implementation-defined. Nev‐
447 ertheless, this is a useful option that should be reserved for that
448 purpose. In the -o option for the POSIX Shell and Utilities ps, the
449 format is the concatenation of each -o. Therefore, the user can have an
450 alias or function that defines the beginning of their desired format
451 and add more fields to the end of the output in certain cases where
452 that would be useful.
453 The format of the terminal name is unspecified, but the descriptions of
455 ps, talk, who, and write require that they all use the same format.
456 The pcpu field indicates that the CPU time available is determined in
458 an unspecified manner. This is because it is difficult to express an
459 algorithm that is useful across all possible machine architectures.
460 Historical counterparts to this value have attempted to show percentage
461 of use in the recent past, such as the preceding minute. Frequently,
462 these values for all processes did not add up to 100%. Implementations
463 are encouraged to provide data in this field to users that will help
464 them identify processes currently affecting the performance of the sys‐
465 tem.
466
468 None.
469
471 kill(), nice(), renice
472
474 Portions of this text are reprinted and reproduced in electronic form
475 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
476 -- Portable Operating System Interface (POSIX), The Open Group Base
477 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
478 Electrical and Electronics Engineers, Inc and The Open Group. In the
479 event of any discrepancy between this version and the original IEEE and
480 The Open Group Standard, the original IEEE and The Open Group Standard
481 is the referee document. The original Standard can be obtained online
482 at http://www.opengroup.org/unix/online.html .
483IEEE/The Open Group 2003 PS(1P)