TOP(1)                 Linux User's Manual                 TOP(1)

NAME
       top - display top CPU processes

SYNOPSIS
       top [-] [d delay] [q] [c] [S] [s] [i] [n] [b]

DESCRIPTION
       top provides an ongoing look at processor activity in real
       time.  It displays a listing  of  the  most  CPU-intensive
       tasks on the system, and can provide an interactive inter-
       face for manipulating processes.  It can sort the tasks by
       CPU  usage,  memory usage and runtime.  can be better con-
       figured than the standard top from the procps suite.  Most
       features  can either be selected by an interactive command
       or by specifying the feature in the  personal  or  system-
       wide configuration file. See below for more information.

COMMAND-LINE OPTIONS
       d    Specifies  the delay between screen updates.  You can
            change this with the s interactive command.

       q    This causes top to refresh without any delay. If  the
            caller  has  superuser priviledges, top runs with the
            highest possible priority.

       S    Specifies cumulative  mode,  where  each  process  is
            listed  with the CPU time that it as well as its dead
            children has spent.  This is  like  the  -S  flag  to
            ps(1).  See the discussion below of the S interactive
            command.

       s    Tells top to run in secure mode.  This  disables  the
            potentially  dangerous  of  the  interactive commands
            (see below).  A secure top is a nifty thing to  leave
            running on a spare terminal.

       i    Start  top ignoring any idle or zombie processes. See
            the interactive command i below.

       c    display command line  instead  of  the  command  name
            only.  The default behaviour has been changed as this
            seems to be more useful.

       n    Number of iterations. Update the display this  number
            of times and then exit.

       b    Batch  mode.  Useful  for  sending output from top to
            other programs or to a file.  In this mode, top  will
            not  accept command line input. It runs until it pro-
            duces the number of iterations requested with  the  n
            option or until killed. Output is plain text suitable
            for display on a dumb terminal.

FIELD DESCRIPTIONS
       top displays a variety of information about the  processor
       state.  The display is updated every 5 seconds by default,
       but you can change that with the d command-line option  or
       the s interactive command.

       uptime
            This  line  displays the time the system has been up,
            and the three load averages for the system.  The load
            averages  are  the average number of process ready to
            run during the last 1, 5 and 15 minutes.   This  line
            is  just  like  the  output of uptime(1).  The uptime
            display may be toggled by the interactive l  command.

       processes
            The  total number of processes running at the time of
            the last update.  This is also broken down  into  the
            number of tasks which are running, sleeping, stopped,
            or undead. The processes and states  display  may  be
            toggled by the t interactive command.

       CPU states
            Shows the percentage of CPU time in user mode, system
            mode, niced tasks, and idle.  (Niced tasks  are  only
            those  whose  nice value is negative.)  Time spent in
            niced tasks will also be counted in system  and  user
            time,  so the total will be more than 100%.  The pro-
            cesses and states display may be  toggled  by  the  t
            interactive command.

       Mem  Statistics on memory usage, including total available
            memory, free memory, used memory, shared memory,  and
            memory used for buffers. The display of memory infor-
            mation may be toggled by the m interactive command.

       Swap Statistics on swap space, including total swap space,
            available  swap space, and used swap space.  This and
            Mem are just like the output of free(1).

       PID  The process ID of each task.

       PPID The parent process ID each task.

       UID  The user ID of the task's owner.

       USER The user name of the task's owner.

       PRI  The priority of the task.

       NI   The nice value of the task.  Negative nice values are
            lower priority.

       SIZE The  size  of  the  task's  code plus data plus stack
            space, in kilobytes, is shown here.

       TSIZE
            The code size of the task. This gives strange  values
            for kernel processes and is broken for ELF processes.

       DSIZE
            Data + Stack size. This is broken for ELF  processes.

       TRS  Text resident size.

       SWAP Size of the swapped out part of the task.

       D    Size of pages marked dirty.

       LIB  Size of use library pages. This does not work for ELF
            processes.

       RSS  The total amount of physical memory used by the task,
            in  kilobytes,  is shown here. For ELF processes used
            library pages are counted here, for  a.out  processes
            not.

       SHARE
            The amount of shared memory used by the task is shown
            in this column.

       STAT The state of the task is shown  here.  The  state  is
            either S for sleeping, D for uninterruptible sleep, R
            for running, Z for  zombies,  or  T  for  stopped  or
            traced.  These staes are modified by trailing < for a
            process with negative nice value,  N  for  a  process
            with positive nice value, W for a swapped out process
            (this does not work correctly for kernel  processes).

       WCHAN
            depending    on    the    availablity    of    either
            /boot/psdatabase or the kernel  link  map  /boot/Sys-
            tem.map  this  shows  the  address or the name of the
            kernel function the task currently is sleeping in.

       TIME Total CPU time the task has used  since  it  started.
            If  cumulative mode is on, this also includes the CPU
            time used by the process's children which have  died.
            You  can  set cumulative mode with the S command line
            option or toggle it with the interactive  command  S.
            The header line will then be changed to CTIME.

       %CPU The  task's  share  of  the  CPU  time since the last
            screen update, expressed as a percentage of total CPU
            time.

       %MEM The task's share of the physical memory.

       COMMAND
            The  task's  command name, which will be truncated if
            it is too long to be displayed on one line.  Tasks in
            memory will have a full command line, but swapped-out
            tasks will only have  the  name  of  the  program  in
            parentheses (for example, "(getty)").

       A , WP
            these fields from the kmem top are not supported.

INTERACTIVE COMMANDS
       Several  single-key  commands  are recognized while top is
       running.  Some are disabled if the s option has been given
       on the command line.

       space
            Immediately updates the display.

       ^L   Erases and redraws the screen.

       h or ?
            Displays a help screen giving a brief summary of com-
            mands, and the status of secure and cumulative modes.

       k    Kill  a process.  You will be prompted for the PID of
            the task, and the signal to send to it.  For a normal
            kill, send signal 15.  For a sure, but rather abrupt,
            kill, send signal 9.  The  default  signal,  as  with
            kill(1),  is 15, SIGTERM.  This command is not avail-
            able in secure mode.

       i    Ignore idle and zombie processes.  This is  a  toggle
            switch.

       n or #
            Change  the number of processes to show.  You will be
            prompted to enter the number.  This  overrides  auto-
            matic  determination  of  the  number of processes to
            show, which is based on window size measurement.   If
            0  is specified, then top will show as many processes
            as will fit on the screen; this is the default.

       q    Quit.

       r    Re-nice a process.  You will be prompted for the  PID
            of the task, and the value to nice it to.  Entering a
            positve value will cause a process  to  be  niced  to
            negative  values, and lose priority.  If root is run-
            ning top, a negative value can be entered, causing  a
            process  to  get  a higher than normal priority.  The
            default renice value is  10.   This  command  is  not
            available in secure mode.

       S    This  toggles  cumulative  mode, the equivalent of ps
            -S, i.e., that CPU times  will  include  a  process's
            defunct children.  For some programs, such as compil-
            ers, which work by forking into many seperate  tasks,
            normal mode will make them appear less demanding than
            they actually are.   For  others,  however,  such  as
            shells  and  init,  this behavior is correct.  In any
            case, try cumulative mode for an alternative view  of
            CPU use.

       s    Change  the  delay  between  updates.   You  will  be
            prompted to enter the delay time, in seconds, between
            updates.   Fractional  values  are recognized down to
            microseconds.  Entering 0 causes continuous  updates.
            The default value is 5 seconds.  Note that low values
            cause nearly unreadably fast  displays,  and  greatly
            raise  the  load.   This  command is not available in
            secure mode.

       f or F
            Add fields to display or remove fields from the  dis-
            play. See below for more information.

       o or O
            Change  order of displayed fields. See below for more
            information.

       l    toggle display of load average  and  uptime  informa-
            tion.

       m    toggle display of memory information.

       t    toggle  display  of processes and CPU states informa-
            tion.

       c    toggle display of command name or full command  line.

       M    sort tasks by resident memory usage.

       P    sort tasks by CPU usage (default).

       T    sort tasks by time / cumulative time.

       W    Write  current setup to ~/.toprc.  This is the recom-
            mended way to write a top configuration file.

The Field and Order Screens
       After pressing f, F, o or O you will  be  shown  a  screen
       specifying  the  field  order  on  the  top line and short
       descriptions of the field contents. The field order string
       uses  the  following  syntax:  If  the letter in the filed
       string corresponding to a  field is upper case, the  field
       will  be  displayed.   This is furthermore indicated by an
       asterisk in front of the field description.  The order  of
       the  fields corresponds to the order of the letters in the
       string.
        From the field select screen you can toggle  the  display
       of a field by pressing the corresponding letter.
        From the order screen you may move a field to the left by
       pressing the corresponding upper case letter resp. to  the
       right by pressing the lower case one.

Configuration Files
       Top  reads  it's  default  configuration  from  two files,
       /etc/toprc and ~/.toprc.  The  global  configuration  file
       may  be  used  to  restrict the usage of top to the secure
       mode for non-priviledged users. If this  is  desired,  the
       file  should  contain  a  's' to specify secure mode and a
       digit d (2<=d<=9) for the default delay (in seconds) on  a
       single line.  The personal configuration file contains two
       lines. The first line contains lower and upper letters  to
       specify  which  fields  in what order are to be displayed.
       The letters correspond to the letters  in  the  Fields  or
       Order  screens  from top. As this is not very instructive,
       it is recommended to select fields and order in a  running
       top  process and to save this using the W interactive com-
       mand.  The second line is  more  interesting  (and  impor-
       tant).  It contains information on the other options. Most
       important, if you have saved  a  configuration  in  secure
       mode,  you  will  not get an insecure top without removing
       the lower 's' from the second line of  your  ~/.toprc.   A
       digit  specifies the delay time between updates, a capital
       'S' cumulative mode, a  lower  'i'  no-idle  mode.  As  in
       interactive mode, a lower 'm', 'l', and 't' suppresses the
       display of memory, uptime resp.   process  and  CPU  state
       information.  Currently changing the default sorting order
       (by CPU usage) is not supported.

NOTES
       This proc-based top works by reading the files in the proc
       filesystem,  mounted  on  /proc.  If /proc is not mounted,
       top will not work.

       %CPU shows the cputime/realtime percentage in  the  period
       of  time  between  updates.  For the first update, a short
       delay is used, and top itself  dominates  the  CPU  usage.
       After  that, top will drop back, and a more reliable esti-
       mate of CPU usage is available.

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

       Keep  in  mind  that a process must die for its time to be
       recorded on its parent by cumulative mode.   Perhaps  more
       useful  behavior  would be to follow each process upwards,
       adding time, but that would be  more  expensive,  possibly
       prohibitively  so.   In  any  case,  that would make top's
       behavior incompatible with ps.

FILES
       /etc/toprc The global configuration  file.   ~/.toprc  The
       personal configuration file.

SEE ALSO
       ps(1), free(1), uptime(1), kill(1), renice(1).

BUGS
       If the window is less than about 70x7, top will not format
       information correctly.
        Many fields still have problems with ELF processes.
        the help screens are not yet optimized for  windows  with
       less than 25 lines

AUTHOR
       top was originally written by Roger Binns, based on Branko
       Lankester's  <lankeste@fwi.uva.nl>  ps  program.    Robert
       Nation  <nation@rocket.sanders.lockheed.com>  re-wrote  it
       significantly to use the proc filesystem, based on Michael
       K.  Johnson's <johnsonm@redhat.com> proc-based ps program.
       Michael   Shields   <mjshield@nyx.cs.du.edu>   made   many
       changes,  including secure and cumulative modes and a gen-
       eral cleanup.

       Helmut Geyer <Helmut.Geyer@iwr.uni-heidelberg.de>  Heavily
       changed  it to include support for configurable fields and
       other new options, and did further cleanup and use of  the
       new readproc interface.

       The  "b"  and  "n"  options  contributed  by George Bonser
       <george@captech.com> for CapTech IT Services.

       Michael K. Johnson <johnsonm@redhat.com> is now the  main-
       tainer.

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

Linux                       Feb 1 1993                          1