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 list-process-table is a tool for listing process information. Its output is machine-parseable and suitable for console-flat-table-viewer1 with 1 header line and --format tabbed or awk1 with -F'\t'. It has a much simpler interface than the ps1 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 strftime3 library function. Linux pre-formats several time fields into human-readable form itself, and this option has no effect upon such fields. The output format is variable-length records terminated by LF containing TAB-separated fields. Fields are output as if passed through the BSD vis3 library function. They are thus unambiguously machine-parseable, because any whitespace in the field itself is encoded by vis3. After separating out an individual field, its contents can (for example) be decoded in shell script using the unvis1 utility (which is supplied by FreeBSD). The args field has light shell quoting applied before being vis3-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 sh1 could misinterpret as variable assignments. After decoding with unvis3 or similar, it is thus in a form usable by a shell. The envs field has different quoting applied before being vis3-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 unvis3 or similar, it is in a form usable by read-conf1 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. 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 ps1 command. The comm field name is replaced by COMM. This is a deviation from the Single Unix Specification and the FreeBSD ps1 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. There is an unavoidable race condition, on both FreeBSD with its sysctl3 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. Jonathan de Boyne Pollard