s6-linux-utils: the s6-ps program
Keywords: s6 linux administration root utilities ps proc procps process list

s6-linux-utils
Software
skarnet.org

# The `s6-ps` program

`s6-ps` shows a list of processes on the system.

## Interface

         s6-ps [ -H ] [ -w spacing ] [ -W chanfile ] [ -l | -o field,field,... ]

- s6-ps assumes the proc filesystem is mounted on `/proc`. It scans `/proc` for a list of all processes on the system.
- It prints a header line, then information about the processes it has found, one process per line. Then it exits 0.
- If s6-ps is not allowed to read a field, it will print `*` (a star) instead of the field's content. `-` (a dash) means the field is unapplicable here, for instance the "tty" field for a process that has no controlling terminal.

## Options

- `-H` : tree. s6-ps will display he process list as a tree, as `ps f` does. It will print kernel processes first, then user processes. By default, the processes are simply ordered by increasing pid number, without care for the process hierarchy.
- `-w spacing` : leave at least spacing space characters between two adjacent fields. Minimum is 1, default is 2, maximum is 256.
- `-W wchanfile` : force wchanfile as the file listing kernel addresses for WCHAN fields. By default, s6-ps tries to use `/proc/kallsyms`, `/boot/System.map-`uname -r``, and `/boot/System.map`, in that order.
- `-l` : long. Equivalent to `-o user,pid,cpcpu,pmem,vsize,rss,tty,s,start,cttime,args`.
- `-o fieldlist` : list of fields to print. fieldlist must be a comma-separated list of fields, without spaces. Fields cannot be duplicated. They will be printed in the given order. The valid field names are listed below. The default field list is `user,pid,tty,s,start,args`.

## Fields

The `-o` option makes it possible to customize s6-ps's output. Here are the recognized field keywords and the corresponding information they display.

- `pid` : the process id number.
- `comm` : the command name as known by the kernel.
- `s` : the one-character state of the process, then `s` if the process is a session leader or `+` if it is a foreground process group leader, then `N` if the process is niced or `<` if it is anti-niced. Unlike ps, s6-ps cannot tell whether a process has locked memory pages or not.
- `ppid` : the parent process' pid.
- `pgrp` : the process group number.
- `sess` : the session leader's pid.
- `tty` : the name of the process's controlling terminal.
- `tpgid` : the pid of the foreground process group.
- `minflt` : the number of minor page fault the process has encountered.
- `cminflt` : the cumulative number of minor page fault the process and its dead children have encountered.
- `majflt` : the number of major page fault the process has encountered.
- `cmajflt` : the cumulative number of major page fault the process and its dead children have encountered.
- `utime` : the time the process spent in user mode.
- `stime` : the time the process spent in kernel mode.
- `cutime` : the time spent in user mode by the process and all its dead children.
- `cstime` : the time spent in kernel mode by the process and all its dead children.
- `prio` : the process' priority as computed by the kernel.
- `nice` : the process' nice value.
- `thcount` : the number of threads in the process.
- `start` : the start time of the process.
- `vsize` : the virtual memory size of the process.
- `rss` : the resident set size of the process.
- `rsslimit` : the maximum rss allowed for the process.
- `psr` : the number of the CPU the process is running on.
- `rtprio` : the real-time priority of the process.
- `policy` : the real-time policy of the process - a symbolic name.
- `user` : the user the process is running as.
- `group` : the group the process is running as.
- `pmem` : the percentage of the available virtual memory the process is using. Be aware that it is a very rough estimate: determining exactly how much memory a process is using is a complex task.
- `wchan` : the name or address of the kernel function where the proces is sleeping. It is actually very rare that a kernel is configured to properly export that value, because it incurs a small performance cost.
- `args` : the command line of the process.
- `env` : the process environment. s6-ps can normally only print the environment for processes running as the same user, or if it is run as root. Be aware that the environment is usually quite large, and will create very long lines, likely to mess up the display on a standard terminal.
- `pcpu` : the percentage of CPU used by the process (total cpu time divided by total running time). It is a mean value and does not reflect current CPU usage.
- `ttime` : total CPU time used by the process (user + kernel mode).
- `cttime` : total CPU time used by the process and all its dead children (user + kernel mode).
- `tstart` : the start time of the process as a TAI64N value.
- `cpcpu` : the percentage of CPU used by the process and its dead children (total cpu time divided by total running time). It is a mean value and does not reflect current CPU usage.