ps 1 user commands nosh
ps process listing tool
`ps` -A -a -x -p process-id(s) -7 -d -e -O name(s) -o name(s) -f -j -l -u -w

## Note

This is generally only accessible as a subcommand of system-control 1, to eliminate conflicts with the standard command by this name. It is referred to without qualification in this manual for simplicity.

## Description

`ps` is a tool for listing process information. It is a shim for the list-process-table 1 command, that provides a more familiar interface (that of the BSD ps 8 command) to that command, whilst yielding that command's table-format output. Its output is therefore machine-parseable and suitable for console-flat-table-viewer 1 with 1 header line and --format tabbed.

It has just two selection modes. The complex selectors of the BSD ps 8 command are not supported.

- With the -A, or (both) the -a and -x, command-line options, list-process-table 1 is told to display the entire process table.

- With the -p command-line option, list-process-table 1 is told to display just the process table entries for process-id(s) which is a comma-separated list of process IDs.

More complex selection and sorting can be done with a normal Unix filter. Because the output is machine-parseable it can be reliably processed by tools such as awk 1 and sort 1 without the problems that would be caused by the whitespace in time, argument, environment, and tree fields. See list-process-table 1 for the output encoding details.

The -7 command-line option is transformed into the --7-bit option.

The -H command-line option is transformed into the --threads option.

The -w command-line option is present for compatibility and does nothing. The output of list-process-table 1 is designed for a table-viewer, or processing by another utility, and is not constrained by terminal width.

The -o command-line option is transformed into a sequence of --field options, one for each of the fields in name(s), which is a comma-separated list. The use of this option nullifies the effects of all other format options, including -O.

If the -o command-line option is not used:

- The -f, -j, -l, and -u command-line options are transformed into sequences of --field options specifying the (hardwired) fields for "full", "jobs", "long", and "user" formats, respectively. If none of these options are set, a "default" set of fields is employed.

  These options are accumulative rather than exclusive. If multiple options are used, all of the fields from all sets will be included.

- The -O command-line option is transformed into a sequence of --field options, one for each of the fields in name(s), which is a comma-separated list. This sequence is inserted into the "default"/"full"/"jobs"/"long"/"user" list after the `pid` column.

  No deduplication of fields is done, so list-process-table 1 will receive any repetitions exactly as they are.

If an output column is either command or args, the -d command-line option is transformed into --field tree preceding it and the -e command-line option is transformed into --field envs following it. Otherwise they have no effect.

## Examples

This command uses `ps` to display the process tree for the current user, selecting rows using awk 1. Even though the process tree diagram and argument strings contain whitespace, they are in an encoded form when awk 1 processes them and there is no ambiguity about field boundaries, which are exactly 1 TAB.

    $ ps -A -d -o "pid,uid,args" |
    > awk -F'\t' -v UID="$(id -u)" \
    >     '($2 == UID) { printf "%8u %s %s\n",$1,$3,$4 }' |
    > unvis

This command uses `ps` to display all processes run by the current user whose (accounting) names are "chrome". Again, the field matching by awk 1 has no ambiguity, and does not accidentally match the wrong columns or partial strings. (It is Chrome itself that incorrectly rewrites its argument strings into one single long argument, by the way.)

    $ ps -A -o "pid,uid,comm,args" |
    > awk -F'\t' -v UID="$(id -u)" \
    >     '($2 == UID && "chrome" == $3) { printf "%8u %s\n",$1,$4 }' |
    > unvis

This command uses `ps` in a loop to feed console-flat-table-viewer 1, producing a continually updated display akin to top 1, with Form Feeds to clear the table display at each iteration.

    $ while ps -a -x | sed -e $'1i\\\n\\\f'
    > do
    >     sleep 1
    > done |
    > console-flat-table-viewer --header-count 1 --format tabbed

Using sed 1 to insert the Form Feed rather than printing it separately with printf 1 reduces flicker. (The standard output buffering in sed 1 causes the write to be a single system call, causing console-flat-table-viewer 1 to receive the Form Feed plus replacement data in a single lump, causing it not to redraw a blank intermediate screen.)

## Compatibility

This `ps` is modelled on the FreeBSD ps 8 tool, providing a subset of its functionality; with the -A and -f command-line options taken from the the Single Unix Specification, and the -O command-line option taken from the NetBSD and OpenBSD ps 8. It provides the actual command-line option syntax that the BSDs have employed and documented for 29 years, at the time of writing this manual.

It differs from the Single Unix Specification in the same ways that the BSD ps 8 differs from the Single Unix Specification, namely in the -d, -e, -g, -n, and -u command-line options. There are three exceptions:

- It implements the Single Unix Specification´s -A and -f command-line options. The former is already in most of the BSD ps 8 commands, except for FreeBSD's. The latter has a widely employed standard meaning and only has another meaning at all in the FreeBSD ps 8 command.

- It uses the Single Unix Specification's `stime` instead of the FreeBSD ps 8's `start`.

- It does not implement the -G, -t, and -U command-line options, which are implemented by BSD ps 8 and specified in the Single Unix Specification.

### History

The ps 8 tool from the procps toolset (as sometimes used on Linux operating systems) has an exceedingly complex command-line interface. One of the claims made in its documentation is that this complex command-line interface provides the command-line interface of the BSD `ps`, where options are not preceded by minus signs. Michael K. Johnson's conversion from "kmem-ps" to "procps" of the Linux `ps` command as modified by Albert D. Cahalan originated the claim that that `ps` command was providing an "extended BSD" command-line interface, a claim that has stood ever since.

This is not, and was not, true at all.

In fact, the BSD `ps` has not worked that way since the days of 4.3BSD in the 1980s, Marc Teitelbaum having switched it to using the getopt 3 library function on 1990-04-02. It had, in other words, not worked that way for 2 years prior to the creation of Branko Lankester's original Linux "kmem-ps" `ps`, in 1992.

The BSD (and later FreeBSD and NetBSD) `ps` has used getopt 3 ever since. This has been the only documented command-line syntax in its manual for all of that time, too. This decades-long-standing BSD command syntax is the model here.

The -O command-line option to the BSD ps 8 tool originally operated somewhat differently, adding the fields specified in the option argument plus the "default" set of fields to the desired set of fields. This was deemed not particularly useful by NetBSD developers in 2006, as it resulted in a lot of pointless column duplication, and was revised. This revised behaviour made its way from NetBSD into the OpenBSD ps 8. It has not yet made it into the FreeBSD flavour of the tool as of the time of writing this manual, hence the aforegiven ascription of -O to NetBSD and OpenBSD, rather than to the BSDs in general.

## Author

Jonathan de Boyne Pollard