1PS(P) POSIX Programmer's Manual PS(P)
2
6 ps - report process status
7
9 ps [-aA][-defl][-G grouplist][-o format]...[-p proclist][-t termlist]
10 [-U userlist][-g grouplist][-n namelist][-u userlist]
12
15 The ps utility shall write information about processes, subject to hav‐
16 ing the appropriate privileges to obtain information about those pro‐
17 cesses.
18 By default, ps shall select all processes with the same effective user
20 ID as the current user and the same controlling terminal as the
21 invoker.
22
24 The ps utility shall conform to the Base Definitions volume of
25 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
26 The following options shall be supported:
28 -a Write information for all processes associated with terminals.
30 Implementations may omit session leaders from this list.
31 -A Write information for all processes.
33 -d Write information for all processes, except session leaders.
35 -e Write information for all processes. (Equivalent to -A.)
37 -f Generate a full listing. (See the STDOUT section for the con‐
39 tents of a full listing.)
40 -g grouplist
42 Write information for processes whose session leaders are given
43 in grouplist. The application shall ensure that the grouplist is
44 a single argument in the form of a <blank> or comma-separated
45 list.
46 -G grouplist
48 Write information for processes whose real group ID numbers are
49 given in grouplist. The application shall ensure that the grou‐
50 plist is a single argument in the form of a <blank> or comma-
51 separated list.
52 -l Generate a long listing. (See STDOUT for the contents of a long
54 listing.)
55 -n namelist
57 Specify the name of an alternative system namelist file in place
58 of the default. The name of the default file and the format of a
59 namelist file are unspecified.
60 -o format
62 Write information according to the format specification given in
63 format. This is fully described in the STDOUT section. Multi‐
64 ple -o options can be specified; the format specification shall
65 be interpreted as the <space>-separated concatenation of all the
66 format option-arguments.
67 -p proclist
69 Write information for processes whose process ID numbers are
70 given in proclist. The application shall ensure that the pro‐
71 clist is a single argument in the form of a <blank> or comma-
72 separated list.
73 -t termlist
75 Write information for processes associated with terminals given
76 in termlist. The application shall ensure that the termlist is a
77 single argument in the form of a <blank> or comma-separated
78 list. Terminal identifiers shall be given in an implementation-
79 defined format. On XSI-conformant systems, they shall be
80 given in one of two forms: the device's filename (for example,
81 tty04) or, if the device's filename starts with tty, just the
82 identifier following the characters tty (for example, "04" ).
83 -u userlist
85 Write information for processes whose user ID numbers or login
86 names are given in userlist. The application shall ensure that
87 the userlist is a single argument in the form of a <blank> or
88 comma-separated list. In the listing, the numerical user ID
89 shall be written unless the -f option is used, in which case the
90 login name shall be written.
91 -U userlist
93 Write information for processes whose real user ID numbers or
94 login names are given in userlist. The application shall ensure
95 that the userlist is a single argument in the form of a <blank>
96 or comma-separated list.
97 With the exception of -o format, all of the options shown are used to
100 select processes. If any are specified, the default list shall be
101 ignored and ps shall select the processes represented by the inclusive
102 OR of all the selection-criteria options.
103
105 None.
106
108 Not used.
109
111 None.
112
114 The following environment variables shall affect the execution of ps:
115 COLUMNS
117 Override the system-selected horizontal display line size, used
118 to determine the number of text columns to display. See the Base
119 Definitions volume of IEEE Std 1003.1-2001, Chapter 8, Environ‐
120 ment Variables for valid values and results when it is unset or
121 null.
122 LANG Provide a default value for the internationalization variables
124 that are unset or null. (See the Base Definitions volume of
125 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
126 ables for the precedence of internationalization variables used
127 to determine the values of locale categories.)
128 LC_ALL If set to a non-empty string value, override the values of all
130 the other internationalization variables.
131 LC_CTYPE
133 Determine the locale for the interpretation of sequences of
134 bytes of text data as characters (for example, single-byte as
135 opposed to multi-byte characters in arguments).
136 LC_MESSAGES
138 Determine the locale that should be used to affect the format
139 and contents of diagnostic messages written to standard error
140 and informative messages written to standard output.
141 LC_TIME
143 Determine the format and contents of the date and time strings
144 displayed.
145 NLSPATH
147 Determine the location of message catalogs for the processing of
148 LC_MESSAGES .
149 TZ Determine the timezone used to calculate date and time strings
151 displayed. If TZ is unset or null, an unspecified default time‐
152 zone shall be used.
153
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
172 with 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
178 possible to kill a process if this datum
179 is 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 num‐
183 bers mean lower priority.
184 NI (l) Nice value; used in priority computa‐
185 tion.
186 ADDR (l) The address of the process.
187 SZ (l) The size in blocks of the core image of
188 the process.
189 WCHAN (l) The event for which the process is wait‐
190 ing or sleeping; if blank, the process
191 is running.
192 STIME (f) Starting time of the process.
193 TTY (all) The controlling terminal for the
194 process.
195 TIME (all) The cumulative execution time for the
196 process.
197 CMD (all) The command name; the full command name
198 and its arguments are written under the
199 -f option.
200 A process that has exited and has a parent, but has not yet been waited
202 for by the parent, shall be marked defunct.
203 Under the option -f, ps tries to determine the command name and argu‐
205 ments given when the process was created by examining memory or the
206 swap area. Failing this, the command name, as it would appear without
207 the option -f, is written in square brackets.
208 The -o option allows the output format to be specified under user con‐
210 trol.
211 The application shall ensure that the format specification is a list of
213 names presented as a single argument, <blank> or comma-separated. Each
214 variable has a default header. The default header can be overridden by
215 appending an equals sign and the new text of the header. The rest of
216 the characters in the argument shall be used as the header text. The
217 fields specified shall be written in the order specified on the command
218 line, and should be arranged in columns in the output. The field widths
219 shall be selected by the system to be at least as wide as the header
220 text (default or overridden value). If the header text is null, such as
221 -o user=, the field width shall be at least as wide as the default
222 header text. If all header text fields are null, no header line shall
223 be written.
224 The following names are recognized in the POSIX locale:
226 ruser The real user ID of the process. This shall be the textual user
228 ID, if it can be obtained and the field width permits, or a dec‐
229 imal representation otherwise.
230 user The effective user ID of the process. This shall be the textual
232 user ID, if it can be obtained and the field width permits, or a
233 decimal representation otherwise.
234 rgroup The real group ID of the process. This shall be the textual
236 group ID, if it can be obtained and the field width permits, or
237 a decimal representation otherwise.
238 group The effective group ID of the process. This shall be the textual
240 group ID, if it can be obtained and the field width permits, or
241 a decimal representation otherwise.
242 pid The decimal value of the process ID.
244 ppid The decimal value of the parent process ID.
246 pgid The decimal value of the process group ID.
248 pcpu The ratio of CPU time used recently to CPU time available in the
250 same period, expressed as a percentage. The meaning of
251 "recently" in this context is unspecified. The CPU time avail‐
252 able is determined in an unspecified manner.
253 vsz The size of the process in (virtual) memory in 1024 byte units
255 as a decimal integer.
256 nice The decimal value of the nice value of the process; see nice() .
258 etime In the POSIX locale, the elapsed time since the process was
260 started, in the form:
261 [[dd-]hh:]mm:ss
264 where dd shall represent the number of days, hh the number of hours, mm
266 the number of minutes, and ss the number of seconds. The dd field shall
267 be a decimal integer. The hh, mm, and ss fields shall be two-digit dec‐
268 imal integers padded on the left with zeros.
269 time In the POSIX locale, the cumulative CPU time of the process in
271 the form:
272 [dd-]hh:mm:ss
275 The dd, hh, mm, and ss fields shall be as described in the etime speci‐
277 fier.
278 tty The name of the controlling terminal of the process (if any) in
280 the same format used by the who utility.
281 comm The name of the command being executed ( argv[0] value) as a
283 string.
284 args The command with all its arguments as a string. The implementa‐
286 tion may truncate this value to the field width; it is implemen‐
287 tation-defined whether any further truncation occurs. It is
288 unspecified whether the string represented is a version of the
289 argument list as it was passed to the command when it started,
290 or is a version of the arguments as they may have been modified
291 by the application. Applications cannot depend on being able to
292 modify their argument list and having that modification be
293 reflected in the output of ps.
294 Any field need not be meaningful in all implementations. In such a case
297 a hyphen ( '-' ) should be output in place of the field value.
298 Only comm and args shall be allowed to contain <blank>s; all others
300 shall not. Any implementation-defined variables shall be specified in
301 the system documentation along with the default header and indicating
302 whether the field may contain <blank>s.
303 The following table specifies the default header to be used in the
305 POSIX locale corresponding to each format specifier.
306 Table: Variable Names and Default Headers in ps
308 Format Specifier Default Header Format Specifier Default Header
310 args COMMAND ppid PPID
311 comm COMMAND rgroup RGROUP
312 etime ELAPSED ruser RUSER
313 group GROUP time TIME
314 nice NI tty TT
315 pcpu %CPU user USER
316 pgid PGID vsz VSZ
317 pid PID
318
320 The standard error shall be used only for diagnostic messages.
321
323 None.
324
326 None.
327
329 The following exit values shall be returned:
330 0 Successful completion.
332 >0 An error occurred.
334
337 Default.
338 The following sections are informative.
340
342 Things can change while ps is running; the snapshot it gives is only
343 true for an instant, and might not be accurate by the time it is dis‐
344 played.
345 The args format specifier is allowed to produce a truncated version of
347 the command arguments. In some implementations, this information is no
348 longer available when the ps utility is executed.
349 If the field width is too narrow to display a textual ID, the system
351 may use a numeric version. Normally, the system would be expected to
352 choose large enough field widths, but if a large number of fields were
353 selected to write, it might squeeze fields to their minimum sizes to
354 fit on one line. One way to ensure adequate width for the textual IDs
355 is to override the default header for a field to make it larger than
356 most or all user or group names.
357 There is no special quoting mechanism for header text. The header text
359 is the rest of the argument. If multiple header changes are needed,
360 multiple -o options can be used, such as:
361 ps -o "user=User Name" -o pid=Process\ ID
364 On some implementations, especially multi-level secure systems, ps may
366 be severely restricted and produce information only about child pro‐
367 cesses owned by the user.
368
370 The command:
371 ps -o user,pid,ppid=MOM -o args
374 writes at least the following in the POSIX locale:
376 USER PID MOM COMMAND
379 helene 34 12 ps -o uid,pid,ppid=MOM -o args
380 The contents of the COMMAND field need not be the same in all implemen‐
382 tations, due to possible truncation.
383
385 There is very little commonality between BSD and System V implementa‐
386 tions of ps. Many options conflict or have subtly different usages. The
387 standard developers attempted to select a set of options for the base
388 standard that were useful on a wide range of systems and selected
389 options that either can be implemented on both BSD and System V-based
390 systems without breaking the current implementations or where the
391 options are sufficiently similar that any changes would not be unduly
392 problematic for users or implementors.
393 It is recognized that on some implementations, especially multi-level
395 secure systems, ps may be nearly useless. The default output has there‐
396 fore been chosen such that it does not break historical implementations
397 and also is likely to provide at least some useful information on most
398 systems.
399 The major change is the addition of the format specification capabil‐
401 ity. The motivation for this invention is to provide a mechanism for
402 users to access a wider range of system information, if the system per‐
403 mits it, in a portable manner. The fields chosen to appear in this vol‐
404 ume of IEEE Std 1003.1-2001 were arrived at after considering what con‐
405 cepts were likely to be both reasonably useful to the "average" user
406 and had a reasonable chance of being implemented on a wide range of
407 systems. Again it is recognized that not all systems are able to pro‐
408 vide all the information and, conversely, some may wish to provide
409 more. It is hoped that the approach adopted will be sufficiently flexi‐
410 ble and extensible to accommodate most systems. Implementations may be
411 expected to introduce new format specifiers.
412 The default output should consist of a short listing containing the
414 process ID, terminal name, cumulative execution time, and command name
415 of each process.
416 The preference of the standard developers would have been to make the
418 format specification an operand of the ps command. Unfortunately, BSD
419 usage precluded this.
420 At one time a format was included to display the environment array of
422 the process. This was deleted because there is no portable way to dis‐
423 play it.
424 The -A option is equivalent to the BSD -g and the SVID -e. Because the
426 two systems differed, a mnemonic compromise was selected.
427 The -a option is described with some optional behavior because the SVID
429 omits session leaders, but BSD does not.
430 In an early proposal, format specifiers appeared for priority and start
432 time. The former was not defined adequately in this volume of
433 IEEE Std 1003.1-2001 and was removed in deference to the defined nice
434 value; the latter because elapsed time was considered to be more use‐
435 ful.
436 In a new BSD version of ps, a -O option can be used to write all of the
438 default information, followed by additional format specifiers. This was
439 not adopted because the default output is implementation-defined. Nev‐
440 ertheless, this is a useful option that should be reserved for that
441 purpose. In the -o option for the POSIX Shell and Utilities ps, the
442 format is the concatenation of each -o. Therefore, the user can have an
443 alias or function that defines the beginning of their desired format
444 and add more fields to the end of the output in certain cases where
445 that would be useful.
446 The format of the terminal name is unspecified, but the descriptions of
448 ps, talk, who, and write require that they all use the same format.
449 The pcpu field indicates that the CPU time available is determined in
451 an unspecified manner. This is because it is difficult to express an
452 algorithm that is useful across all possible machine architectures.
453 Historical counterparts to this value have attempted to show percentage
454 of use in the recent past, such as the preceding minute. Frequently,
455 these values for all processes did not add up to 100%. Implementations
456 are encouraged to provide data in this field to users that will help
457 them identify processes currently affecting the performance of the sys‐
458 tem.
459
461 None.
462
464 kill() , nice() , renice
465
467 Portions of this text are reprinted and reproduced in electronic form
468 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
469 -- Portable Operating System Interface (POSIX), The Open Group Base
470 Specifications Issue 6, Copyright (C) 2001-2003 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 .
476IEEE/The Open Group 2003 PS(P)