ps(1)

NAME

ps - report process status

SYNOPSIS

ps [-] [lujsvmaxScewhrnu] [txx] \ [O[+|-]k1[[+|-]k2...]] \ [pids]
there are also three long options:
--sortX [ + | - ] key [,[ + | - ] key [, ... ]]
--help
--version
More long options are on the way...

"ps " gives a snapshot of the current processes. If you want a repetitive update of this status, use top . This man page documents the /proc -based version of ps , or tries to.

COMMAND-LINE OPTIONS

Command line arguments may optionally be preceeded by a '-', but there is no need for it. There are also some "long options" in GNU style; see below for those.

l

long format

u

user format: gives user name and start time

j

jobs format: pgid sid

s

signal format

v

vm format

m

displays memory info (combine with p flag to get number of pages).

f

"forest" family tree format for command line

a

show processes of other users too

x

show processes without controlling terminal

S

add child cpu time and page faults

c

command name from task_struct

e

show environment after command line and ` + '

w

wide output: don't truncate command lines to fit on one line. To be exact, every w that is specified will add another possible line to the output. If the space isn't needed it isn't used. You may up to 100 w 's.

h

no header

r

running procs only

n

numeric output for USER and WCHAN .

t xx

only procs with controlling tty xx; for xx you may use either the name of a device file under "/dev" or that name with either tty " or " cu sliced off. This is the reverse heuristic that ps uses to print out the abbreviated tty name in the TT field, e.g. "ps -t1" .

O [ + | - ] k1 [,[ + | - ] k2 [, ... ]]

Order the process listing according to the multi-level sort specified by the sequence of short keys from SORT KEYS, k1, k2, ... Default order specifications exist for each of the various formats of ps. These are over-ridden by a user specified ordering. The `+' is quite optional, merely re-iterating the default direction on a key. `-' reverses direction only on the key it precedes. As with t and pids, the O option must be the last option in a single command argument, but specifications in successive arguments are catenated.

pids

List only the specified processes; they are comma-delimited. The list must be given immediately after the last option in a single command-line argument, with no intervening space, e.g. "ps -j1,4,5" . Lists specified in subsequent arguments are catenated, e.g. ps -l 1,2 3,4 5 6 will list all of the processes 1-6 in long format. If pids are given, they are listed no matter what. If a tty is given matching processes are listed no matter what. These two features override the 'a' and 'x' flags.

LONG COMMAND-LINE OPTIONS

These options are preceeded by a double-hyphen.

--sortX [ + | - ] key [,[ + | - ] key [, ... ]]

Choose a multi-letter key from the SORT KEYS section. X may be any convenient separator character. To be GNU-ish use `='. The `+' is really optional since default direction is increasing numerical or lexicographic order. E.g.: ps -jax --sort=uid,-ppid,+pid

--help

Get a help message that summarizes the usage and gives a list of supported sort keys. This list may be more up to date than this man page.

--version

Display version and source of this program.

SORT KEYS

Note that the values used in sorting are the internal values ps uses and not the `cooked' values used in some of the output format fields. If someone wants to volunteer to write special comparison functions for the cooked values, ... ;-)

 SHORT   LONG            DESCRIPTION
 c       cmd             simple name of executable
 C       cmdline         full command line
 f       flags           flags as in long format F field
 g       pgrp            process group ID
 G       tpgid           controlling tty process group ID
 j       cutime          cumulative user time
 J       cstime          cumulative system time
 k       utime           user time
 K       stime           system time
 m       min_flt         number of minor page faults
 M       maj_flt         number of major page faults
 n       cmin_flt        cumulative minor page faults
 N       cmaj_flt        cumulative major page faults
 o       session         session ID
 p       pid             process ID
 P       ppid            parent process ID
 r       rss             resident set size
 R       resident        resident pages
 s       size            memory size in kilobytes
 S       share           amount of shared pages
 t       tty             the minor device number of tty
 T       start_time      time process was started
 U       uid             user ID number
 u       user            user name
 v       vsize           total VM size in bytes
 y       priority        kernel scheduling priority

FIELD DESCRIPTIONS

PRI

This is the counter field in the task struct. It is the time in HZ of the process's possible timeslice.

NI

Standard unix nice value; a positive value means less cpu time.

SIZE

Virtual image size; size of text+data+stack.

RSS

Resident set size; kilobytes of program in memory.

WCHAN

Name of the kernel function where the process is sleeping, with the ` sys_ ' stripped from the function name. If /etc/psdatabase does not exist, it is just a hex number instead.

STAT

Information about the status of the process. The first field is R for runnable, S for sleeping, D for uninterruptible sleep, T for stopped or traced, or Z for a zombie process. The second field contains W if the process has no resident pages. The third field is N if the process has a positive nice value ( NI field).

TT

Controlling tty.

PAGEIN

Number of major page faults (page faults that cause pages to be read from disk, including pages read from the buffer cache).

TRS

Text resident size.

SWAP

Kilobytes (or pages if -p is used) on swap device.

SHARE

Shared memory.

UPDATING

This proc -based ps works by reading the files in the proc filesystem, mounted on /proc . This ps does not need to be suid kmem or have any privileges to run. "Do not give this ps any special permissions."

You will need to update the /etc/psdatabase file by running /etc/psupdate to get meaningful information from the WCHAN field. This should be done every time you compile a new kernel.

NOTES

The member used_math of task_struct is not shown, since crt0.s checks to see if math is present. This causes the math flag to be set for all processes, and so it is worthless.

Programs swapped out to disk will be shown without command line arguments, and unless the c option is given, in parentheses.

%CPU shows the cputime/realtime percentage. It will not add up to 100% unless you are lucky. It is time used divided by the time the process has been running.

The SIZE and RSS fields don't count the page tables and the task_struct of a proc; this is at least 12k of memory that is always resident. SIZE is the virtual size of the proc (code+data+stack).

To perform the device number to name mapping ps maintains a file called "/etc/psdevtab" (updated whenever "/dev" becomes newer and permissions allow update). If permissions do not allow update, every invokation of ps requires a stat(2) of every file in the "/dev" directory. If "/dev" changes often on your system you should run ps as root often. ;-) I may add a fallback file under $HOME under force of popular demand.

AUTHOR

ps was originally written by Branko Lankester (lankeste@fwi.uva.nl) Michael K. Johnson (johnsonm@sunsite.unc.edu) re-wrote it significantly to use the proc filesystem, changing a few things in the process. Michael Shields (mjshield@nyx.cs.du.edu) added the pid-list feature. Charles Blake(cblake@bbn.com) added multi-level sorting, the dirent-style library, the device name-to-number mmaped database, and many code and documentation cleanups and is the current maintainer of the proc-ps suite.