nps(1) nps(1)
NAME
nps - list processes
SYNOPSIS
nps [OPTIONS] [MATCHES|PIDS]
DESCRIPTION
nps writes a snapshot of information about processes running on the
system.
OPTIONS
All LIST options consists of elements separated by spaces or commas.
Selecting Processes
These options select which processes to display.
-a Select processes which have a controlling terminal.
-A, -e, --all
Select all processes.
--ancestor LIST
Select all the processes with an ancestor in LIST.
-C NAME, --command NAME
Select processes by name.
Equivalent to comm=:NAME (see MATCH EXPRESSIONS below).
-d Select all processes that are not session leaders.
-g LIST
Select all processes whose sessions are in LIST.
--group LIST
Select all processes whose effective group ID is in LIST (by
name or number).
-G LIST, --real-group LIST, --Group LIST
Select all processes whose real group ID is in LIST (by name or
number).
-p LIST, --pid LIST
Select all the processes in LIST.
--ppid LIST
Select all the processes in whose parent is in LIST.
-t LIST, --tty LIST
Select all the processes whose controlling terminals are in
LIST. Terminal names may be abbreviated by ommitting the ini‐
tial /dev.
-u LIST, --user LIST
Select all the processes whose effective user ID is in LIST (by
name or number).
-U LIST, --real-user LIST, --User LIST
Select all the processes whose real user ID is in LIST (by name
or number).
In addition, any non-option arguments are used to select processes.
See MATCH EXPRESSIONS below.
Process selection is cumulative, i.e. if multiple process selection
options are given then any process which is selected by at least one of
them is selected. If no selection options are given then only pro‐
cesses that share an effective UID and terminal with the current
process are selected.
Formatting
These options determine how the output is formatted.
--csv Set CSV format output. See CSV OUTPUT below.
-f, --full
Set the "full" output format.
-l, --long
Set the "long" output format.
-H, --forest
Hierarchical display.
-o FORMAT, -O FORMAT, --format FORMAT
Set a specific format. -o uses SUS syntax, the rest use NPS
syntax. If multiple options are given then they are cumulative.
See FORMATTING below.
-w Don't truncate output. Normally when writing to a terminal,
output is truncated at the terminal width. If the output is not
a terminal then it is never truncated.
Other Options
-L, --threads
Display threads instead of processes. If used twice, both
threads and processes are used.
-n ANYTHING
Ignored.
--poll SECONDS[:COUNT]
Repeat the output every SECONDS seconds. If a COUNT is speci‐
fied then only that many repetitions are performed.
To distinguish lines that describe the same process at different
times, use the localtime property.
--sort ORDER
Set the order in which processes are listed. See SORTING below.
--help Display a usage message.
--help-format
Displays help for the -o option.
--help-match
Displays help for match expressions.
--version
Display a version string.
MATCH EXPRESSIONS
Following the options may appear one or more match expressions. These
are general-purpose process selection options and come in several
forms.
As with other process selection options, the effect of match expres‐
sions is cumulative.
Display Match Expressions
These match expressions match the value exactly as displayed. For
numeric properties, this isn't usually very useful. For example,
rss=1048576 will never match, because it will always be 1M in that
case.
The first is PROPERTY=VALUE and matches only if the named property
exactly matches the given value. For instance, comm=kvm can be used to
match kvm processes only.
The second is PROPERTY~REGEXP and matches if the named property matches
the extended POSIX regexp. For instance args~dbus will match dbus-dae‐
mon, dbus-launch, etc.
Value Match Expressions
These match expressions match the value as represented internally, with
the following consequences:
· Numbers are given their exact value, rather than rounding to
kilobytes, megabytes, etc. For instance, rss==1048576 will
match processes with an RSS of exactly one megabyte.
· Terminal paths are not abbreviated.
· Times are represented as second counts.
The possible match expressions are PROPERTY<VALUE, PROPERTY<=VALUE,
PROPERTY>VALUE, PROPERTY>=VALUE for ordering comparisons, PROP‐
ERTY==VALUE to test for equality and PROPERTY<>VALUE or PROPERTY!=VALUE
to test for inequality.
In all cases, numbers are compared as numbers and strings are compared
lexicographically. Where the VALUE is a number, it may be represented
in hex (using a 0x prefix) or octal (using a 0 prefix) and suffixed
with K, M, G, T or P to represent kilobytes up to petabytes, or p to
represent pages. (This is possible even when it doesn't make a great
deal of sense, e.g. pid<1K.)
For example, to list processes with an RSS of at least one megabyte,
you might use:
nps -o user,pid,rss,tty,comm 'rss>=1M'
Quoting
Since value match expressions include shell metacharacters, some shell
quoting may be required.
In order to distinguish between (for instance) == and = where the first
character of the VALUE is an = sign, any match operator may be followed
by a single :. When the value is a shell variable it is advisable to
always include the colon, for example:
nps -o user,pid,rss,tty,comm "comm=:${COMMAND}"
FORMATTING
The -o, -O and --format options specify a list of process properties to
display, separated by spaces or commas. The available properties are:
addr The current instruction pointer (hex).
args Command line. If these cannot be determined then the value of
comm is used, in square brackets.
This corresponds to the argv array passed to main; for a script
the first element will be the name of the interpreter and the
second element the name of the script.
Requested widths are mandatory for args.
argsfull
Exactly the same as args but with the directory part of the com‐
mand included.
comm Program filename. This corresponds to the first argument to
execve(3); for a script it is the basename of the script, not
the name of the interpreter.
Requested widths are mandatory for comm.
etime Time elapsed since the process started. See Time Intervals
below for more information
flags Flags word from the kernel (octal). You will need a copy of the
kernel sources to be able to interpret this.
If an argument is supplied it should be o, x, X or d to for
octal, hex, hex (with upper case letters) or decimal.
fsgid Filesystem group ID (decimal)
fsgroup
Filesystem group ID as a string.
fsuid Filesystem user ID (decimal)
fsuser Filesystem user ID as a string.
gid Effective group ID (decimal).
group Effective group ID as a string. If the group name will not fit
into the requested width, the numeric ID will be used instead.
io IO rate. This is the sum of read and write. See Memory below
for argument syntax.
localtime
The time at which process information was gathered. This is
independent of the process; it is intended for use with --poll.
If an argument is supplied, it is passed to strftime(3) to for‐
mat the time.
locked Memory locked into RAM. See Memory below for argument syntax.
majflt Major fault rate. Major faults are page faults that require a
page to be read from disk. See Memory below for argument syn‐
tax.
mem The total memory (resident and swapped) used by the process.
Equivalent to rss+swap. See Memory below for argument syntax.
minflt Minor fault rate. Minor faults do not require a page to be read
from disk. See Memory below for argument syntax.
nice Nice value. Higher values mean lower priority ("nicer").
oom OOM score. Higher values mean the kernel is more likely to kill
the process when memory runs out.
pcomm Parent process filename. This is the same as comm but for the
parent process.
pcpu CPU usage, as a percentage. If an argument is supplied, it
gives the number of digits to print after the decimal point.
The default is 0.
pgrp Process group ID.
pid Process ID.
locked Pinned memory. See Memory below for argument syntax.
pmem The total memory (resident and swapped) used by the process,
scaled down to account for sharing with other processes. Equiv‐
alent to pss+swap. See Memory below for argument syntax.
ppid Parent process ID.
pri Priority.
pss Proportional resident set size. This the total RAM used by the
process, with each page's contribution divided by the number of
processes it is shared with.
Only root can read the pss of processes it doesn't own.
See Memory below for argument syntax.
read Read rate. See Memory below for argument syntax.
rgid Real group ID (decimal).
rgroup Real group ID as a string. If the group name will not fit into
the requested width, the numeric ID will be used instead.
rss Resident set size. This the total RAM used by the process. See
Memory below for argument syntax.
rsspk Peak resident set size. This is the highest value that rss has
reached in the lifetime of the process. See Memory below for
argument syntax.
rtprio Realtime scheduling priority. See sched_setscheduler(2).
ruid Real user ID (decimal).
ruser Real user ID as a string. If the user name will not fit into
the requested width, the numeric ID will be used instead.
sched Current scheduling policy. Possible values corresponds to
SCHED_... constants:
- Normal scheduling policy (SCHED_NORMAL).
FIFO (1)
First-in, first-out policy.
RR (2) Round-robin policy.
BATCH (3)
Batch execution.
IDLE (5)
Low-priority background jobs.
A trailing /- means that the priority will be reset to normal
when the process forks. See also sched_setscheduler(2) and Doc‐
umentation/sched-design-CFS.txt in the kernel source tree.
sgid Saved group ID (decimal)
sgroup Saved group ID as a string.
sid Session ID.
sigblocked
Blocked signals.
By default signals are listed by name. If there are many sig‐
nals this can make a very wide column. If this a problem,
request a maximum column size (see Column Width below); a
numeric format will be used, where necessary, instead.
sigcaught
Caught signals.
sigignored
Ignored signals.
sigpending
Pending signals.
stack The size of the stack. This only gives the main thread's stack.
See Memory below for argument syntax.
state Process state. The possible states are:
R Running.
S Sleeping.
D Disk wait.
Z Exited but not yet reaped (a "zombie" process).
T Traced or stopped due to a signal.
W Paging.
stime The time that the process started. If an argument is supplied,
it is passed to strftime(3) to format the time.
suid Saved used ID (decimal)
supgid Supplementary group IDs (decimal).
supgrp Supplementary group IDs as strings.
suser Saved user ID as a string.
swap Swap used. See Memory below for argument syntax.
Prior to kernel 2.6.34, only root can read the swap of processes
it doesn't own.
threads
The number of threads, or - a thread.
tid The thread ID, or - for a process.
time The cumulative CPU time used over the process's lifetime (user
and kernel). See Time Intervals below for more information
tpgid Foreground process group ID on controlling terminal.
tty Controlling terminal. The leading /dev/tty or /dev is stripped
for compactness.
uid Effective user ID (decimal).
user Effective user ID as a string. If the user name will not fit
into the requested width, the numeric ID will be used instead.
vsz Virtual memory size. This is the total address space used by
the process. See Memory below for argument syntax.
vszpk Peak virtual memory size. This is the highest value that vsz
has reached in the lifetime of the process. See Memory below
for argument syntax.
wchan Wait channel.
write Write rate. See Memory below for argument syntax.
Aliases
In addition the following aliases are supported:
%cpu Alias for pcpu.
cmd Alias for args.
command
Alias for args.
cputime
Alias for time.
egid Alias for gid.
egroup Alias for group.
euid Alias for uid.
euser Alias for user.
f Alias for flags.
flag Alias for flags.
lwp An alias for thread.
nlwp An alias for threads.
ni Alias for 0
pgrp Alias for pgid.
rssize Alias for rss.
rsz Alias for rss.
sess Alias for sid.
session
Alias for sid.
thcount
Alias for threads.
tname Alias for tty.
tt Alias for tty.
vsize Alias for vsz.
Column Width
By default, every column is made wide enough for every value that
appears in it.
To request a particular width for a column, use the syntax PROP‐
ERTY:WIDTH. For most properties, requested widths are only advisory;
if necessary columns will be made wider to fit. However if possible an
alternative representation will be used to fit within the requested
width. For certain properties such as args requested widths are manda‐
tory.
Headings
To give a property a different heading, use the syntax PROPERTY=HEAD‐
ING. In SUS syntax (-o) this only works on the last property in a sin‐
gle argument. Use multiple -o options to work around this. In NPS
syntax (-O and all other contexts) this can be used on any or all of
the properties within an argument. If the heading contains spaces or
quotes then it must be quoted.
Arguments
To supply an argument to a property, use the syntax PROPERTY/ARGUMENT.
If the argument contains spaces or quotes then it must be quoted.
Widths always come first; then headings; then arguments.
Time Intervals
Time intervals (such as etime) are represented as [[DD-]HH:]MM:SS, with
DD representing the number of days, HH the number of hours, MM the num‐
ber of minutes and SS the number of seconds.
If a column width is requested then more compact forms may be used:
DdHH for a multi-day time, HHhMM for a multi-hour time or MMmSS for
sub-hours times.
These columns can also take a format string as an argument, overriding
the above. The format string consists of ordinary characters and for‐
mat specifications starting with %. Within the format specification
any of the following may appear, in order, the following modifiers:
· A minimum field width, as a decimal integer. If this starts
with a 0 then the field will be padded with zeroes; otherwise
with spaces. The default minimum field width is 0.
· A . followed by a minimum digit count, as a decimal integer.
The default minimum digit count is 1.
· A ? indicating that the entire format specification is to be
skipped if the value is 0.
· A + followed by a single character, which will appear after the
converted result (provided it is not skipped due to a ?).
At the end of the format specification is a single-character conversion
specifier:
d The total number of days.
h The total number of hours.
H The number of hours disregarding any complete days.
m The total number of minutes.
M The number of minutes disregarding any complete hours.
s The total number of seconds.
S The number of seconds disregarding any complete minutes.
% Writes a single %. All modifiers are ignored in this case.
Timestamps
Timestamps (such as stime) are represented as YYYY-MM-DD for times out‐
side than the current day and HH:MM:SS for times during the current
day. They are always given in the local timezone.
If a column width is requested then more compact forms may be used:
HH:MM for a time in this day or MM-DD for a date in this year.
If an argument is supplied, it is passed to strftime(3) to format the
time.
Memory
rss is the resident set size of a process, i.e. the amount physical RAM
it is currently using. However, some of that RAM may be shared with
other processes, for instance because it is used for the code of a
widely used shared library. Therefore it can be more useful to look at
the pss figure, the proportional resident set size, in which every
page's contribution is divided by the number of users.
If you think you are running out of RAM and want a process to blame,
look for high pss figures.
vsz represents the total virtual memory used by the process. This
includes RAM, swap, files and anonymous mappings. Since the dynamic
linker and some other libraries like to make inaccessible anonymous
mappings, this figure can be quite misleading as a measure of resource
consumption.
swap represents the amount of swap space used by the process. This
includes both swapped out pages from anonymous mappings and copy-on-
write duplicates of pages mapped from files. It does not include pages
mapped from files that happen not to be in RAM at the moment.
mem is the sum of rss and swap. The same caveats apply regarding
shared pages, so pmem, which is the sum of pss and swap, is likely to
be more useful.
The memory properties (rss etc) all support the following arguments:
K Display in kilobytes.
M Display in megabytes.
G Display in gigabytes.
T Display in terabytes.
P Display in petabytes.
p Display in pages.
CUTOFF Display in bytes up to CUTOFF kilobytes, in kilobytes up to CUT‐
OFF megabytes and so on up to petabytes.
With no argument, units are selected as if CUTOFF was 1.
The same applies to I/O rates, except that they are kilobytes per sec‐
onds, etc.
The kernel support for gathering pss was added in Linux 2.6.25 and for
swap in 2.6.26, so if your kernel is older than that you will not get
the correct figures.
Defaults
If no formatting options at all are specified then the default is
equivalent to:
-Opid,tty=TTY,time,comm=CMD
The -f option is equivalent to:
-Ouser=UID,pid,ppid,pcpu=C,stime,tty=TTY,time,comm=CMD
The -l option is equivalent to:
-Oflags,state,uid,pid,ppid,pcpu=C,pri,nice,addr,vsz="SZ"/K,
wchan,tty=TTY,time,args=CMD
In all cases, if -L is used, tid is added after pid.
CSV OUTPUT
The --csv option modifies the output in the following ways:
· Padding is suppressed and columns are separated with a comma.
· Numeric properties are always represented in decimal, without
quotes.
· Text properties are always quoted.
· Memory and IO rate properties are always given in bytes.
· With --poll, only the first line contains column headings.
Timestamps are text properties, and the usual argument rules apply.
Time intervals are numeric properties are always displayed as a count
of seconds.
The intent is that the output can easily be imported into a spread‐
sheet.
SORTING
The --sort option specifies the properties which control the order in
which processes are displayed, separate by spaces or commas. The
available properties are listed above in FORMATTING.
If more than one property is specified the second and subsequent are
only considered when ordering processes which cannot be distinguished
by the first (and so on).
Each property name may be prefix with + to specify descending order
(the default) and - to specify ascending order.
Defaults
If no ordering option is specified then processes are listed in the
order chosen by the kernel.
CONFIGURATION
On startup defaults are read from the file $HOME/.npsrc, if it exists.
Each line has a KEY=VALUE format, with ps recognizing the following
keys:
ps_format
The default format.
ps_f_format
The format to use if -f is specified.
ps_l_format
The format to use if -l is specified.
All three use NPS syntax (see FORMATTING above).
ENVIRONMENT
COLUMNS
The maximum line length. If COLUMNS is not set then window
width is used when writing to a terminal, and no truncation
takes place when writing to any other kind of output.
BUGS
The meaning of flags is not very clear.
STANDARDS
Intended to follow SUS v4. The SUS syntax for headings is rather
inflexible, hence NPS syntax everywhere that isn't defined by SUS.
CSV output follows RFC 4180.
AUTHOR
Richard Kettlewell <rjk@greenend.org.uk>
nps(1)