PS(1)                  Linux User's Manual                  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...

DESCRIPTION
       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
       The command-line  options  for  this  version  of  ps  are
       derived  from the BSD version of ps, not the System V ver-
       sion.

       The command-line arguments should not be  preceeded  by  a
       `-'  character,  because in the future, a `-' will be used
       to indicate Unix98-standard command-line arguments,  while
       no `-' will indicate the current ``extended BSD'' style of
       command line arguments.

       For now, ps will give you a warning if you use a `-' for a
       short  option,  but it will still work.  If you have shell
       scripts which use BSD-style arguments to ps, take heed  of
       the  warning  and fix them, or else your scripts will fail
       to function correctly at some point in the future.  If you
       want  to turn off the warnings, set the I_WANT_A_BROKEN_PS
       environment variable.

       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 num-
            ber 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.

       txx  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 specifica-
            tions  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  over-
            ride 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  lexico-
            graphic 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 val-
       ues 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  val-
       ues, ... ;-)

       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 put in place the appropriate System.map
       file when you install a new kernel in order to  get  mean-
       ingful  information  from the WCHAN field.  This should be
       done every time you compile a new kernel.  You should also
       run 'ps' as root once and then any time the tty devices in
       the "/dev" directory change.

       As of procps-1.00, ps/top read System.map directly  if  it
       is  available.  The search path for kernel address-to-sym-
       bol resolution is:
                   $PS_SYSTEM_MAP
                   /boot/System.map-`uname -r`
                   /boot/System.map
                   /lib/modules/`uname -r`/System.map
                   /etc/psdatabase
                   /boot/psdatabase-`uname -r`
                   /boot/psdatabase,
                   /lib/modules/`uname -r`/psdatabase

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 worth-
       less.

       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).

AUTHOR
       ps   was   originally   written   by   Branko    Lankester
       <lankeste@fwi.uva.nl>.  Michael K.  Johnson <johnsonm@red-
       hat.com>  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  fea-
       ture.   Charles  Blake  <cblake@bbn.com> added multi-level
       sorting, the dirent-style library, the device name-to-num-
       ber   mmaped   database,  the  approximate  binary  search
       directly on System.map, and many  code  and  documentation
       cleanups.   David  Mossberger-Tang  wrote  the generic BFD
       support for psupdate.  Michael K.  Johnson  <johnsonm@red-
       hat.com> is the current maintainer.

       Please send bug reports to <procps-bugs@redhat.com>

Cohesive Systems            3 Sep 1997                          1