nps-top(1) nps-top(1)
NAME
nps-top - constantly display process information
SYNOPSIS
nps-top [OPTIONS]
DESCRIPTION
nps-top displays a constantly-updating snapshot of information about
processes running on the system.
OPTIONS
-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.
-d SECONDS, --delay SECONDS
Set the time between updates. The default is 1 second.
-i, --idle
Display only non-idle processes.
-j, --sysinfo SYSINFO
Sets the system information format. See SYSTEM INFORMATION
below.
-L, --threads
Display threads instead of processes. If used twice, both
threads and processes are used.
-s ORDER, --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 and -s options.
--help-sysinfo
Displays help for the -j option.
--version
Display a version string.
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:
-Ouser,pid,nice,rss,pcpu,read,write,tty=TTY,args=CMD
If the calling user is not root then read and write are omitted.
SORTING
The -s 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 the default is equivalent to:
-s +pcpu,+io,+rss,+pmem
SYSTEM INFORMATION
The -j option specifies which whole-system properties should be dis‐
played, separated by spaces or commas.
The available system properties are:
cpu CPU usage information. The fields are:
user The percentage of time spent running all user code. This
includes nice and guest.
nice The percentage of time spent running niced code.
guest The percentage of time spent running guest operating sys‐
tems in a virtual machine.
sys The percentage of time spent in the kernel.
io The percentage of time spent blocked on I/O.
If an argument is supplied, it controls the number of digits
shown after the decimal point.
cpus A line equivalent to cpu for each individual CPU.
idletime
The cumulative time the system has spent idle.
On a multi-CPU system this will reflect the cumulative time
across all CPUs.
load The system load averages. These three figures are the number of
tasks either runnable or blocked on disk IO averaged over 1, 5
and 15 minutes.
If an argument is supplied, it controls the number of digits
shown after the decimal point. The default is 1.
mem Memory information. The fields are:
tot Total usable memory. This will be slightly less than the
physical memory fitted, as the kernel and some reserved
memory are not included in this figure.
used Memory currently in use for any purpose. As above, the
kernel is excluded.
free Memory not in use for any purpose.
buf Cached blocks.
cache Cached files.
The same argument syntax described in Memory above can be used
to control the units used.
processes
The current number of processes.
swap Swap information. The fields are:
tot Total usable swap space.
used Swap in use.
free Swap not in use.
cache Memory both in RAM and in swap. It can be used or
swapped out without IO being required.
The same argument syntax described in Memory above can be used
to control the units used.
threads
The current number of threads. Each process consists of at
least one thread.
time The current time (using the local timezone). If an argument is
supplied, it is passed to strftime(3) to format the time.
uptime The amount of time since the system booted.
System properties are sampled at the same time as collecting process
information, so the -d value defines how out of date they may be. The
exception is time which always reflects the current time.
Parameters
System properties may have their heading ("Time", etc) overridden,
using the syntax PROPERTY=HEADING. If HEADING contains spaces or
quotes then it must be quoted.
System properties may have an argument supplied, using the syntax PROP‐
ERTY/ARGUMENT. If ARGUMENT contains spaces or quotes then it must be
quoted.
Both a heading and an argument can be set at once. In that case the
heading must come first, and it must be quoted. For example, to change
both the heading and format of the current time:
time="When"/%H:%M:%S
Headings are always followed by a colon and a space, unless they are
empty. If heading ends with one or more spaces, they are moved to
after the colon.
The memory system properties (mem and swap) support the same arguments
as the memory process properties (rss etc); see above for details.
Defaults
If -j is not specified then the default is equivalent to:
-j time,uptime,processes,load,cpu,mem,swap
KEYBOARD
Scrolling
If the terminal is too narrow, the process table can be panned left and
right with the following keys:
right arrow, ^F
Moves the viewport to the right by one character, i.e. moves the
columns to the left.
page down
Moves the viewport to the right by eight characters.
left arrow, ^B
Moves the viewport to the left by one character, i.e. moves the
columns to the right.
page up
Moves the viewport to the left by eight characters.
home, ^A
Moves the viewport all the way to the left.
Commands
The following keyboard commands can also be used:
^L Redisplay the screen.
d Changes the update interval. Equivalent to the -d option.
h Displays on-screen help. Press multiple times to cycle through
the help pages and dismiss them.
i Toggles display of idle processes. Equivalent to the -i option.
j Changes the list of whole-system properties. Equivalent to the
-j option.
o Changes the list of properties to display. Equivalent to the -O
option. Column headings may be quoted (and must be quoted, if
they contain a space, comma or quotes).
s Changes the order specification. Equivalent to the -s option.
t Switch between display of processes, threads and both.
q Quits immediately.
Input
When editing a value (for instance after pressing d) the following keys
can be used:
home, ^A
Move the cursor to the start of the line.
left arrow, ^B
Move the cursor left.
ALT-left arrow, ALT-B
Move the cursor left one word.
end, ^E
Move the cursor to the end of the line.
right arrow, ^F
Move the cursor right.
ALT-right arrow, ALT-F
Move the cursor right one word.
^L Redisplay the screen.
^U Delete all the input.
escape, ^X
Cancel the operation. Note that ^X will usually be more respon‐
sive than escape.
backspace
Delete the character to the left of the cursor.
ALT-backspace
Delete the word to the left of the cursor.
delete, ^D
Delete the character under the cursor.
ALT-delete, ALT-D
Delete the word to the right of the cursor.
return Commit the operation. This will only have any effect if the
current input is valid.
up arrow, ^P
Scroll the help up by one line.
page up
Scroll the help up by one page.
down arrow, ^N
Scroll the help down by one line.
page down
Scroll the help down by one page.
CONFIGURATION
On startup defaults are read from the file $HOME/.npsrc, if it exists.
Each line has a KEY=VALUE format, with top recognizing the following
keys:
top_delay
The default update interval in seocnds (overridden with the -d
option).
top_format
The default format (overridden with the -O option). Uses NPS
syntax (see FORMATTING above).
top_order
The default order (overridden with the -s option).
top_sysinfo
The default system information (overridden with the -j option).
BUGS
The meaning of flags is not very clear.
AUTHOR
Richard Kettlewell <rjk@greenend.org.uk>
nps-top(1)