PS(1POSIX)

📦 version 2017a, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🌸 PS(1POSIX) — the POSIX Programmer's Manual 💅

okay bestie, sit down, hydrate, because we're about to talk about ps — report process status — and she's lowkey one of the most iconic utilities in the whole POSIX lineup. this is PS(1POSIX), from the POSIX Programmer's Manual. 🫶

✨ PROLOG ✨

real talk before we even start: this manual page is part of the POSIX Programmer's Manual. the Linux implementation of this interface may differ — so consult the corresponding Linux manual page for details on Linux behavior, bestie, don't come for me — or the interface may not be implemented on Linux at all. 😭 it's giving "check your local listings."

💖 NAME 💖

ps — report process status. that's it. that's the whole job. and she ate. 👑

🎀 SYNOPSIS 🎀

ps [-aA] [-defl] [-g grouplist] [-G grouplist]
    [-n namelist] [-o format]... [-p proclist] [-t termlist]
    [-u userlist] [-U userlist]

look at all those flags, she's serving versatility, no cap. 🌈

🦋 DESCRIPTION 🦋

so the ps utility shall write information about processes, subject to having appropriate privileges to obtain information about those processes. translation: you only get the tea on processes you're allowed to see. 🔒

and by default — like, with zero flags, raw, unedited — ps shall select all processes with the same effective user ID as the current user and the same controlling terminal as the invoker. so basically: you, your terminal, your processes. the group chat you actually belong to. 💅

⭐ OPTIONS ⭐

the ps utility shall conform to the Base Definitions volume of POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines. (we love a compliant queen.)

the following options shall be supported:

  • -a — write information for all processes associated with terminals. heads up though: implementations may omit session leaders from this list. 🙈
  • -A — write information for all processes. periodt.
  • -d — write information for all processes, except session leaders. so everyone's invited except the leader. 💀
  • -e — write information for all processes. (equivalent to -A.) twins fr fr.
  • -f — generate a full listing. (see the STDOUT section for the contents of a full listing.) she's extra and we respect it. ✨
  • -g grouplist — write information for processes whose session leaders are given in grouplist. the application shall ensure that the grouplist is a single argument in the form of a <blank> or <comma>-separated list. so like -g "1,2 3" energy.
  • -G grouplist — write information for processes whose real group ID numbers are given in grouplist. the application shall ensure that the grouplist is a single argument in the form of a <blank> or <comma>-separated list. note: real GID, not session leaders this time. different vibe, same list format. 💜
  • -l — generate a long listing. (see STDOUT for the contents of a long listing.) the long listing is the full-length mirror moment. 🪞
  • -n namelist — specify the name of an alternative system namelist file in place of the default. the name of the default file and the format of a namelist file are unspecified. so… mysterious. we don't know her. 🫥
  • -o format — write information according to the format specification given in format. this is fully described in the STDOUT section. multiple -o options can be specified; the format specification shall be interpreted as the <space>-separated concatenation of all the format option-arguments. yes bestie, you can stack them, they just get glued together with spaces. 🧚
  • -p proclist — write information for processes whose process ID numbers are given in proclist. the application shall ensure that the proclist is a single argument in the form of a <blank> or <comma>-separated list.
  • -t termlist — write information for processes associated with terminals given in termlist. the application shall ensure that the termlist is a single argument in the form of a <blank> or <comma>-separated list. terminal identifiers shall be given in an implementation-defined format. on XSI-conformant systems, they shall be given in one of two forms: the device's filename (for example, tty04) or, if the device's filename starts with tty, just the identifier following the characters tty (for example, "04"). so tty04 and "04" are the same girl, different outfits. 🎀
  • -u userlist — write information for processes whose user ID numbers or login names are given in userlist. the application shall ensure that the userlist is a single argument in the form of a <blank> or <comma>-separated list. in the listing, the numerical user ID shall be written unless the -f option is used, in which case the login name shall be written. so -f changes the fit she's wearing. 👗
  • -U userlist — write information for processes whose real user ID numbers or login names are given in userlist. the application shall ensure that the userlist is a single argument in the form of a <blank> or <comma>-separated list. yes, real UID. yes, it's different from -u. read it again. 👀

okay and this next part is the actual plot twist, so pay attention bestie:

with the exception of -f, -l, -n namelist, and -o format, all of the options shown are used to select processes. if any are specified, the default list shall be ignored and ps shall select the processes represented by the inclusive OR of all the selection-criteria options.

read that again, slowly: those four are the "how should it look" girlies, and everything else is a "who are we even talking about" filter. the second you add one of those filters, the default list is GONE, and everything you asked for gets OR'd together into one big inclusive list. inclusive OR, inclusive queen. 🌈👑

🌸 OPERANDS 🌸

None. nothing. zero. she takes no operands. that's the whole section. 💅

🌼 STDIN 🌼

Not used. she doesn't read from you, bestie. 🚫

💜 INPUT FILES 💜

None. she needs no files. self-sufficient icon behavior. ✨

🌟 ENVIRONMENT VARIABLES 🌟

the following environment variables shall affect the execution of ps:

  • COLUMNS — override the system-selected horizontal display line size, used to determine the number of text columns to display. see the Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment Variables for valid values and results when it is unset or null. basically: how wide is the fit. 📏
  • LANG — provide a default value for the internationalization variables that are unset or null. (see the Base Definitions volume of POSIX.1‐2017, Section 8.2, Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.)
  • LC_ALL — if set to a non-empty string value, override the values of all the other internationalization variables. she's the final boss of locale settings. 👑
  • LC_CTYPE — determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as opposed to multi-byte characters in arguments).
  • LC_MESSAGES — determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output.
  • LC_TIME — determine the format and contents of the date and time strings displayed. ⏰
  • NLSPATH — determine the location of message catalogs for the processing of LC_MESSAGES.
  • TZ — determine the timezone used to calculate date and time strings displayed. if TZ is unset or null, an unspecified default timezone shall be used. so set it or live in mystery. 🕰️

🎆 ASYNCHRONOUS EVENTS 🎆

Default. as in, nothing special, she handles it the normal way. iconic and unbothered. 💅

okay bestie that's the vibe so far — but we are not done, don't you dare close the tab, there's more of this page coming and the STDOUT section is where the real drama lives. stay with me. 💖

✨ STDOUT ✨

So here's the tea, bestie: if you don't pass -o, the standard output format is unspecified. Like, do whatever, it's a vibe, no promises. 🙈

On XSI-conformant systems though, the output format shall be as follows. The column headings and descriptions of the columns in a ps listing are given below — and heads up, the precise meanings of these fields are implementation-defined. The letters f and l (below) indicate the option (full or long) that shall cause the corresponding heading to appear; all means the heading always appears. And lowkey the most important bit: these two options determine only what information is provided for a process — they do not determine which processes are listed. Different question, different answer, iykyk. 💅

  • F (l) — Flags (octal and additive) associated with the process.
  • S (l) — The state of the process.
  • UID (f,l) — The user ID number of the process owner; the login name is printed under the -f option.
  • PID (all) — The process ID of the process; it is possible to kill a process if this datum is known. 👀
  • PPID (f,l) — The process ID of the parent process.
  • C (f,l) — Processor utilization for scheduling.
  • PRI (l) — The priority of the process; higher numbers mean lower priority.
  • NI (l) — Nice value; used in priority computation.
  • ADDR (l) — The address of the process.
  • SZ (l) — The size in blocks of the core image of the process.
  • WCHAN (l) — The event for which the process is waiting or sleeping; if blank, the process is running.
  • STIME (f) — Starting time of the process.
  • TTY (all) — The controlling terminal for the process.
  • TIME (all) — The cumulative execution time for the process.
  • CMD (all) — The command name; the full command name and its arguments are written under the -f option.

A process that has exited and has a parent, but has not yet been waited for by the parent, shall be marked defunct. 💀

Under the option -f, ps tries to determine the command name and arguments given when the process was created by examining memory or the swap area. Failing this, the command name, as it would appear without the option -f, is written in square brackets.

The -o option allows the output format to be specified under user control. 🎀

The application shall ensure that the format specification is a list of names presented as a single argument, <blank> or <comma>-separated. Each variable has a default header. The default header can be overridden by appending an <equals-sign> and the new text of the header. The rest of the characters in the argument shall be used as the header text. The fields specified shall be written in the order specified on the command line, and should be arranged in columns in the output. The field widths shall be selected by the system to be at least as wide as the header text (default or overridden value). If the header text is null, such as -o user=, the field width shall be at least as wide as the default header text. If all header text fields are null, no header line shall be written. 🫶

The following names are recognized in the POSIX locale:

  • ruser — The real user ID of the process. This shall be the textual user ID, if it can be obtained and the field width permits, or a decimal representation otherwise.
  • user — The effective user ID of the process. This shall be the textual user ID, if it can be obtained and the field width permits, or a decimal representation otherwise.
  • rgroup — The real group ID of the process. This shall be the textual group ID, if it can be obtained and the field width permits, or a decimal representation otherwise.
  • group — The effective group ID of the process. This shall be the textual group ID, if it can be obtained and the field width permits, or a decimal representation otherwise.
  • pid — The decimal value of the process ID.
  • ppid — The decimal value of the parent process ID.
  • pgid — The decimal value of the process group ID.
  • pcpu — The ratio of CPU time used recently to CPU time available in the same period, expressed as a percentage. The meaning of ``recently'' in this context is unspecified. The CPU time available is determined in an unspecified manner.
  • vsz — The size of the process in (virtual) memory in 1024 byte units as a decimal integer.
  • nice — The decimal value of the nice value of the process; see nice.
  • etime — In the POSIX locale, the elapsed time since the process was started, in the form:
[[dd-]hh:]mm:ss

where dd shall represent the number of days, hh the number of hours, mm the number of minutes, and ss the number of seconds. The dd field shall be a decimal integer. The hh, mm, and ss fields shall be two-digit decimal integers padded on the left with zeros.

  • time — In the POSIX locale, the cumulative CPU time of the process in the form:
[dd-]hh:mm:ss

The dd, hh, mm, and ss fields shall be as described in the etime specifier.

  • tty — The name of the controlling terminal of the process (if any) in the same format used by the who utility.
  • comm — The name of the command being executed (argv[0] value) as a string.
  • args — The command with all its arguments as a string. The implementation may truncate this value to the field width; it is implementation-defined whether any further truncation occurs. It is unspecified whether the string represented is a version of the argument list as it was passed to the command when it started, or is a version of the arguments as they may have been modified by the application. Applications cannot depend on being able to modify their argument list and having that modification be reflected in the output of ps.

Any field need not be meaningful in all implementations. In such a case a <hyphen-minus> ('-') should be output in place of the field value. 🍓

Only comm and args shall be allowed to contain <blank> characters; all others shall not. Any implementation-defined variables shall be specified in the system documentation along with the default header and indicating whether the field may contain <blank> characters.

The following table specifies the default header to be used in the POSIX locale corresponding to each format specifier. (It was a whole table in the original, we're serving it as a list because tables are so not the vibe here, but every single pairing is present, no cap. 💜)

Table: Variable Names and Default Headers in ps

  • args → COMMAND
  • comm → COMMAND
  • etime → ELAPSED
  • group → GROUP
  • nice → NI
  • pcpu → %CPU
  • pgid → PGID
  • pid → PID
  • ppid → PPID
  • rgroup → RGROUP
  • ruser → RUSER
  • time → TIME
  • tty → TT
  • user → USER
  • vsz → VSZ

🌸 STDERR 🌸

The standard error shall be used only for diagnostic messages. That's it, that's the whole job. 🎀

🦋 OUTPUT FILES 🦋

None.

💫 EXTENDED DESCRIPTION 💫

None.

👑 EXIT STATUS 👑

The following exit values shall be returned:

  • 0 — Successful completion. ✨
  • >0 — An error occurred. 😭

🌈 CONSEQUENCES OF ERRORS 🌈

Default.

The following sections are informative.

💅 APPLICATION USAGE 💅

Okay bestie, real talk: things can change while ps is running. The snapshot it gives is only true for an instant, and might not be accurate by the time it is displayed. It's giving ✨temporal✨, not gospel. 🙈

The args format specifier is allowed to produce a truncated version of the command arguments. In some implementations, this information is no longer available when the ps utility is executed. 😭

If the field width is too narrow to display a textual ID, the system may use a numeric version instead. Normally, the system would be expected to choose large enough field widths, but if a large number of fields were selected to write, it might squeeze fields to their minimum sizes to fit on one line. One way to ensure adequate width for the textual IDs is to override the default header for a field to make it larger than most or all user or group names. Big brain move, fr fr. 🧠✨

There is no special quoting mechanism for header text. The header text is the rest of the argument. If multiple header changes are needed, multiple -o options can be used, such as:

ps -o "user=User Name" -o pid=Process\ ID

On some implementations, especially multi-level secure systems, ps may be severely restricted and produce information only about child processes owned by the user. Not everything is visible to everyone, and that's by design. 💀

⭐ EXAMPLES ⭐

The command:

ps -o user,pid,ppid=MOM -o args

writes at least the following in the POSIX locale:

      USER   PID   MOM   COMMAND
    helene    34    12   ps -o uid,pid,ppid=MOM -o args

The contents of the COMMAND field need not be the same in all implementations, due to possible truncation. So don't @ me if your output looks a lil different, okay? 💖

✨ RATIONALE ✨

  • Okay so bestie, the tea is: there is very little commonality between BSD and System V implementations of ps. Many options conflict or have subtly different usages. The standard developers attempted to select a set of options for the base standard that were useful on a wide range of systems and selected options that either can be implemented on both BSD and System V-based systems without breaking the current implementations or where the options are sufficiently similar that any changes would not be unduly problematic for users or implementors.
  • It is recognized that on some implementations, especially multi-level secure systems, ps may be nearly useless. The default output has therefore been chosen such that it does not break historical implementations and also is likely to provide at least some useful information on most systems.
  • The major change is the addition of the format specification capability. The motivation for this invention is to provide a mechanism for users to access a wider range of system information, if the system permits it, in a portable manner. The fields chosen to appear in this volume of POSIX.1‐2017 were arrived at after considering what concepts were likely to be both reasonably useful to the “average” user and had a reasonable chance of being implemented on a wide range of systems. Again it is recognized that not all systems are able to provide all the information and, conversely, some may wish to provide more. It is hoped that the approach adopted will be sufficiently flexible and extensible to accommodate most systems. Implementations may be expected to introduce new format specifiers.
  • The default output should consist of a short listing containing the process ID, terminal name, cumulative execution time, and command name of each process.
  • The preference of the standard developers would have been to make the format specification an operand of the ps command. Unfortunately, BSD usage precluded this. 😭
  • At one time a format was included to display the environment array of the process. This was deleted because there is no portable way to display it. 🚫
  • The -A option is equivalent to the BSD -g and the SVID -e. Because the two systems differed, a mnemonic compromise was selected.
  • The -a option is described with some optional behavior because the SVID omits session leaders, but BSD does not.
  • In an early proposal, format specifiers appeared for priority and start time. The former was not defined adequately in this volume of POSIX.1‐2017 and was removed in deference to the defined nice value; the latter because elapsed time was considered to be more useful.
  • In a new BSD version of ps, a -O option can be used to write all of the default information, followed by additional format specifiers. This was not adopted because the default output is implementation-defined. Nevertheless, this is a useful option that should be reserved for that purpose. In the -o option for the POSIX Shell and Utilities ps, the format is the concatenation of each -o. Therefore, the user can have an alias or function that defines the beginning of their desired format and add more fields to the end of the output in certain cases where that would be useful.
  • The format of the terminal name is unspecified, but the descriptions of ps, talk, who, and write require that they all use the same format.
  • The pcpu field indicates that the CPU time available is determined in an unspecified manner. This is because it is difficult to express an algorithm that is useful across all possible machine architectures. Historical counterparts to this value have attempted to show percentage of use in the recent past, such as the preceding minute. Frequently, these values for all processes did not add up to 100%. Implementations are encouraged to provide data in this field to users that will help them identify processes currently affecting the performance of the system.

🌈 FUTURE DIRECTIONS 🌈

None. That's it. Nothing. Nada. None. 💀

👀 SEE ALSO 👀

  • kill, nice, renice
  • The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

And that's the whole vibe, bestie. This page is from IEEE/The Open Group, dated 2017, and it's the PS(1POSIX) manual page. Slay, read responsibly, and may your process list always be iconic. 💅✨

📦 where this page comes from