procstat 1 administrator commands nosh
procstat process listing tool
`procstat` -b -c -e -i -k -s -S -t -H -a process-id(s)

## Description

`procstat` 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 FreeBSD procstat 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.

- With the -a command-line option, list-process-table 1 is told to display the entire process table.

- With a list of process-id(s), list-process-table 1 is told to display just the process table entries for process-id(s) (one process ID per argument).

### Options

Command-line options are translated into options for list-process-table 1 as follows:

-H

  Pass the --threads command-line option.

-b

  Request the pid, comm, osrel, emul, and command fields with the --field command-line option.

-c

  Request the pid, comm, args fields with the --field command-line option.

-e

  Request the pid, comm, and envs fields with the --field command-line option.

-i

  Request the pid, comm, siglist, sigmask, sigignore, and sigcatch fields with the --field command-line option.

-k

  Request the pid, tid, comm, tdname, and kstack fields with the --field command-line option.

-s

  Request the pid, comm, euid, ruid, svuid, egid, rgid, svgid, umask, crflags, and groups fields with the --field command-line option.

-S

  Request the pid, tid, comm, tdname, oncpu, lastcpu, csid, lastcpu, and csmask fields with the --field command-line option.

-t

  Request the pid, tid, comm, tdname, oncpu, lastcpu, pri, state, mwchan, and wchan fields with the --field command-line option.

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

## Examples

### Viewing information of a single process

This command uses `procstat` to display environment information for a shell process.

    $ procstat -e $$ |
    > unvis

unvis 1 decodes the environment column from the machine-parseable form that is output to a more human-readable form for display to a user.

### Simulating top 1

This command uses `procstat` in a loop to feed console-flat-table-viewer 1, producing a continually updated display akin to top 1 with its -I option.

    $ while procstat -a -t | awk -F'\t' '{ if (NR < 2 || match($8,"R") > 0) print $0; }' | sed -e '1s/^/^L/'
    > do
    >     sleep 1
    > done |
    > console-flat-table-viewer --header-count 1

The Form Feeds before the table cause console-flat-table-viewer 1 to clear the table display at each iteration. console-flat-table-viewer 1 itself decodes the machine-parseable table into a human-readable form for display.

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, in turn causing it not to redraw a blank intermediate screen.)

The use of awk 1 demonstrates the machine-parseable nature of the table output and how to retain headers and select rows based upon field values. Because the output of list-process-table 1 is machine-parseable, with exactly 1 TAB between fields, there are no problems with empty fields or command names that contain spaces, and `$8` is always the correct field number to test for the running process state. The test for `NR < 2` allows the header row through.

The sed 1 processing could be done in the awk 1 script. They are separated in the preceding example for simplicity of exposition, with sed 1 handling the table separation and awk 1 handling the row selection. Combining requires `printf`:

    $ while procstat -a -t | awk -F'\t' '{ if (NR < 2) printf "\f%s\n",$0; else if (match($8,"R") > 0) print; }'
    > do
    >     sleep 1
    > done |
    > console-flat-table-viewer --header-count 1

## Compatibility and history

This `procstat` is modelled on the FreeBSD procstat 8 tool, providing a subset of its functionality.

Several command-line options of the FreeBSD procstat 8 command are not supported, because they do not translate into list-process-table 1 mechanims. Also, several fields are not meaningful outwith FreeBSD.

The -w mode of the FreeBSD procstat 8 command is not supported. See the examples for a better way to repeatedly print output.

## Author

Jonathan de Boyne Pollard