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)