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)