Top

Top is a system process monitor. The cool thing about top is that it can display stats in real-time, and is presented in an easy to read format.

Older versions will compile and run on 4.3 BSD, etc. and can still be found on FTP sites.

man page

TOP(1)              UNIX Programmer's Manual               TOP(1)

NAME
     top - display and update information about the top cpu
     processes

SYNOPSIS
     top [ -SbiInqu ] [ -dcount ] [ -stime ] [ -Uusername ] [
     number ]

DESCRIPTION
     Top displays the top 15 processes on the system and periodi-
     cally updates this information.  Raw cpu percentage is used
     to rank the processes.  If number is given, then the top
     number processes will be displayed instead of the default.

     Top makes a distinction between terminals that support
     advanced capabilities and those that do not.  This distinc-
     tion affects the choice of defaults for certain options.  In
     the remainder of this document, an "intelligent" terminal is
     one that supports cursor addressing, clear screen, and clear
     to end of line.  Conversely, a "dumb" terminal is one that
     does not support such features.  If the output of top is
     redirected to a file, it acts as if it were being run on a
     dumb terminal.

OPTIONS
     -S   Show system processes in the display.  Normally, system
          processes such as the pager and the swapper are not
          shown.  This option makes them visible.

     -b   Use "batch" mode.  In this mode, all input from the
          terminal is ignored.  Interrupt characters (such as ^C
          and ^\) still have an effect.  This is the default on a
          dumb terminal, or when the output is not a terminal.

     -i   Use "interactive" mode.  In this mode, any input is
          immediately read for processing.  See the section on
          "Interactive Mode" for an explanation of which keys
          perform what functions.  After the command is pro-
          cessed, the screen will immediately be updated, even if
          the command was not understood.  This mode is the
          default when standard output is an intelligent termi-
          nal.

     -I   Do not display idle processes.  By default, top
          displays both active and idle processes.

     -n   Use "non-interactive" mode.  This is indentical to
          "batch" mode.

     -q   Renice top to -20 so that it will run faster.  This can
          be used when the system is being very sluggish to
          improve the possibility of discovering the problem.

Printed 6/4/87                Local                             1

TOP(1)              UNIX Programmer's Manual               TOP(1)

          This option can only be used by root.

     -u   Do not take the time to map uid numbers to usernames.
          Normally, top will read as much of the file
          "/etc/passwd" as is necessary to map all the user id
          numbers it encounters into login names.  This option
          disables all that, while possibly decreasing execution
          time.  The uid numbers are displayed instead of the
          names.

     -dcount
          Show only count displays, then exit.     A display is con-
          sidered to be one update of the screen.  This option
          allows the user to select the number of displays he
          wants to see before top automatically exits.     For
          intelligent terminals, no upper limit is set.  The
          default is 1 for dumb terminals.

     -stime
          Set the delay between screen updates to time seconds.
          The default delay between updates is 2 seconds.

     -Uusername
          Show only those processes owned by username.     This
          option currently only accepts usernames and will not
          understand uid numbers.

     Both count and number fields can be specified as "infinite",
     indicating that they can stretch as far as possible.  This
     is accomplished by using any proper prefix of the keywords
     "infinity", "maximum", or "all".  The default for count on
     an intelligent terminal is, in fact, infinity.

     The environment variable TOP is examined for options before
     the command line is scanned.  This enables a user to set his
     or her own defaults.  The number of processes to display can
     also be specified in the environment variable TOP.  The
     options -I, -S, and -u are actually toggles.  A second
     specification of any of these options will negate the first.
     Thus a user who has the environment variable TOP set to "-I"
     may use the command "top -I" to see idle processes.

INTERACTIVE MODE
     When top is running in "interactive mode", it reads commands
     from the terminal and acts upon them accordingly.  In this
     mode, the terminal is put in "CBREAK", so that a character
     will be processed as soon as it is typed.  Almost always, a
     key will be pressed when top is between displays; that is,
     while it is waiting for time seconds to elapse.  If this is
     the case, the command will be processed and the display will
     be updated immediately thereafter (reflecting any changes
     that the command may have specified).  This happens even if

Printed 6/4/87                Local                             2

TOP(1)              UNIX Programmer's Manual               TOP(1)

     the command was incorrect.  If a key is pressed while top is
     in the middle of updating the display, it will finish the
     update and then process the command.  Some commands require
     additional information, and the user will be prompted
     accordingly.  While typing this information in, the user's
     erase and kill keys (as set up by the command stty) are
     recognized, and a newline terminates the input.

     These commands are currently recognized (^L refers to
     control-L):

     ^L   Redraw the screen.

     h or ?
          Display a summary of the commands (help screen).

     q    Quit top.

     d    Change the number of displays to show (prompt for new
          number).  Remember that the next display counts as one,
          so typing d1 will make top show one final display and
          then immediately exit.

     n or #
          Change the number of processes to display (prompt for
          new number).

     s    Change the number of seconds to delay between displays
          (prompt for new number).

     k    Send a signal ("kill" by default) to a list of
          processes.  This acts similarly to the command
          kill(1)).

     r    Change the priority (the "nice") of a list of
          processes.  This acts similarly to the command ren-
          ice(8)).

     u    Display only processes owned by a specific username
          (prompt for username).  If the username specified is
          simply "+", then processes belonging to all users will
          be displayed.

     e    Display a list of system errors (if any) generated by
          the last kill or renice command.

     i    (or I) Toggle the display of idle processes.

THE DISPLAY
     The actual display varies depending on the specific variant
     of Unix that the machine is running.  This description may
     not exactly match what is seen by top running on this

Printed 6/4/87                Local                             3

TOP(1)              UNIX Programmer's Manual               TOP(1)

     particular machine.  Differences are listed at the end of
     this manual entry.

     The top few lines of the display show general information
     about the state of the system, including the last process id
     assigned to a process (on most systems), the three load
     averages, the current time, the number of existing
     processes, the number of processes in each state (sleeping,
     running, starting, zombies, and stopped), and a percentage
     of time spent in each of the processor states (user, nice,
     system, and idle).  It also includes information about phy-
     sial and virtual memory allocation.

     The remainder of the screen displays information about indi-
     vidual processes.  This display is similar in spirit to
     ps(1) but it is not exactly the same.  PID is the process
     id, USERNAME is the name of the process's owner (if -u is
     specified, a UID column will be substituted for USERNAME),
     PRI is the current priority of the process, NICE is the nice
     amount (in the range -20 to 20), SIZE is the total size of
     the process (text, data, and stack), RES is the current
     amount of resident memory (both SIZE and RES are given in
     kilobytes), STATE is the current state (one of "sleep",
     "WAIT", "run", "idl", "zomb", or "stop"), TIME is the number
     of system and user cpu seconds that the process has used,
     WCPU, when displayed, is the weighted cpu percentage (this
     is the same value that ps(1) displays as CPU), CPU is the
     raw percentage and is the field that is sorted to determine
     the order of the processes, and COMMAND is the name of the
     command that the process is currently running (if the pro-
     cess is swapped out, this column is marked "<swapped>").

NOTES
     The "ABANDONED" state (known in the kernel as "SWAIT") was
     abandoned, thus the name.  A process should never end up in
     this state.

AUTHOR
     William LeFebvre, EECS Department, Northwestern University

ENVIRONMENT
     TOP  user-configurable defaults for options.

FILES
     /dev/kmem      kernel memory
     /dev/mem       physical memory
     /etc/passwd         used to map uid numbers to user names
     /vmunix        system image

BUGS
     Don't shoot me, but the default for -I has changed once
     again.  So many people were confused by the fact that top

Printed 6/4/87                Local                             4

TOP(1)              UNIX Programmer's Manual               TOP(1)

     wasn't showing them all the processes that I have decided to
     make the default behavior show idle processes, just like it
     did in version 2.  But to appease folks who can't stand that
     behavior, I have added the ability to set "default" options
     in the environment variable TOP (see the OPTIONS section).
     Those who want the behavior that version 3.0 had need only
     set the environment variable TOP to "-I".

     The command name for swapped processes should be tracked
     down, but this would make the program run slower.

     As with ps(1), things can change while top is collecting
     information for an update.  The picture it gives is only a
     close approximation to reality.

SEE ALSO
     kill(1), ps(1), stty(1), mem(4), renice(8)

Printed 6/4/87                Local                             5