list-process-table 1 administrator commands nosh
list-process-table process listing tool
`list-process-table` --field name --threads --tui-level level --time-format formatstring PIDs

## Description

`list-process-table` is a tool for listing process information. Its output is machine-parseable and suitable for console-flat-table-viewer 1 with 1 header line and --format tabbed or awk 1 with -F'\t'.

It has a much simpler interface than the ps 1 command. In fact that latter command (in this toolset) is a shim around `list-process-table`, turning its more complex interface into a plain list of output field names and processs IDs.

The PID command-line arguments are a filter set that is matched against the process IDs, enabling the selection of individual process records. If there are no PID arguments, the entire list is output, unfiltered. It is not an error for a filter item not to match a process ID.

The --threads command-line option controls whether `list-process-table` asks the operating system for a list of all individual threads, or simply all processes.

The --field command-line option specifies a list of fields by name. What exactly the fields are varies from operating system to operating system. There is a basic common set: pid, ppid, pgid, flags, state, uid, sid, pcpu, pri, nice, vsz, rss, wchan, stime, tty, time, comm, args, envs, and tree.

The --time-format command-line option specifies an alternative display format to be employed for all time fields, formatstring, in the form employed by the strftime 3 library function.

Linux pre-formats several time fields into human-readable form itself, and this option has no effect upon such fields.

## Output

The output format is variable-length records terminated by LF containing TAB-separated fields. Fields are output as if passed through the BSD `vis` 3 library function. They are thus unambiguously machine-parseable, because any whitespace in the field itself is encoded by `vis` 3. After separating out an individual field, its contents can (for example) be decoded in shell script using the `unvis` 1 utility (which is supplied by FreeBSD).

The args field has light shell quoting applied before being `vis` 3-encoded. This quoting is weighted towards encapsulating whole arguments, where quoting is needed, as one whole quoted string; and does not produce things that a conformant `sh` 1 could misinterpret as variable assignments. After decoding with `unvis` 3 or similar, it is thus in a form usable by a shell.

The envs field has different quoting applied before being `vis` 3-encoded. This quoting prefers unquoted forms more than the light shell quoting does, at the expense of more quote and escape characters. After decoding with `unvis` 3 or similar, it is in a form usable by `read-conf` 1 and similar utilities.

The tree field is calculated from the process ID and parent process ID information in the process table. Output records are always sorted into tree-display order (in ascending order of process ID for the children beneath any given parent) whether or not the field is actually selected for output. Selection of records by process ID happens after the tree has been generated, and may cause the tree to look odd.

The --tui-level command-line option constrains the use of MouseText or Unicode block graphics and line drawing characters in the tree field.

### Header row

The field names are transformed to uppercase for the initial header record. For compatibility with traditional tools, per the Single Unix Specification several field names are altered into different names for the header names. In addition to the list of such replacements that is documented in the Single Unix Specification in the section for the `ps` utility:

- The flags, state, address, and size field names are replaced by `F`, `S`, `ADDR`, and `SZ`. This is implied by but not actually stated in the Single Unix Specification.

- The logname field name is replaced by `LOGIN`. This is not a field defined by the Single Unix Specification, but is part of the information available about a process on FreeBSD. Its replacement is in line with the FreeBSD ps 1 command.

- The comm field name is replaced by `COMM`. This is a deviation from the Single Unix Specification and the FreeBSD ps 1 command. It agrees, rather, with Laurent Berot's `s6-ps`.

  It eliminates confusion with the `COMMAND` field heading that the Single Unix Specification engenders, albeit that the Single Unix Specification's comm field is not what real `ps` tools on Linux and the BSDs actually do. comm is supposed to be just the first string in args according to the Single Unix Specification. Hence why `COMMAND` can be the header for both fields. Actual `ps` commands on Linux and the BSDs instead display an "accounting name" for the process in this field, and not its argument strings at all.

## Race conditions

There is an unavoidable race condition, on both FreeBSD with its `sysctl` 3 API and Linux with its lots-of-pseudo-files API, between reading the main information for a process from the process table and reading its argument and environment strings. There is a window between the two within which a process may terminate and be reaped from the process table, resulting in argument and environment strings not being read, and their columns in the resultant output being empty.

## Author

Jonathan de Boyne Pollard