*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> top (1)              



NAME    [Toc]    [Back]

     top - display and update information about the top CPU  processes

SYNOPSIS    [Toc]    [Back]

     top [-biInqSu] [-d count] [-o field] [-s time] [-U username]

DESCRIPTION    [Toc]    [Back]

     top displays the top processes on the system and periodically updates
     this information.  If standard output is an intelligent terminal (see below)
 then as many processes as  will  fit  on  the  terminal
screen are displayed
  by  default.   Otherwise,  a good number of them are
shown (around
     20).  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 distinction affects the
choice of defaults
 for certain options.  In the remainder of this  document, an
     intelligent terminal is one that supports cursor addressing,
     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.

     The options are as follows:

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

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

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

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

     -n      Use non-interactive  mode.   This  is  identical  to
batch mode.

     -o field
             Sort  the  process  display area using the specified
field as the
             primary key.  The field name is the name of the column as seen in
             the  output, but in lower case.  The OpenBSD version
of top supports
 cpu, size, res, time, and pri.

     -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.  This option can only be
used by

     -s time
             Set  the  delay  between screen updates to time seconds.  The value
             may be fractional, to permit delays of less  than  1
second.  The
             default delay between updates is 5 seconds.

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

     -u       Do  not  take  the time to map UID numbers to usernames.  Normally,
             top will read as much of the password database as is
necessary to
             map all the user ID numbers it encounters into login
names.  This
             option disables all that, while possibly  decreasing
             time.   The UID numbers are displayed instead of the

     -U username
             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,
     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
     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
     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    [Toc]    [Back]

     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
     This happens even if the command was incorrect.  If a key is
     while top is in the middle of updating the display, it  will
finish the
     update  and then process the command.  Some commands require
     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(1)) 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.

     The following commands may not be available with  overstrike

     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.

     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.

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

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

     o        Change  the  sorting order of the processes (prompt
for order).
             Values are the same as for the -o flag, as  detailed

     r       Change the priority (the nice) of a list of processes.  This acts
             similarly to the command renice(8).

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

     S       Toggle the display of system processes.

     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.

THE DISPLAY    [Toc]    [Back]

     The  top  few  lines of the display show general information
about the state
     of the system, including the three load average numbers, the
     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 physical  and
virtual memory
  allocation.  The load average numbers give the number of
jobs in the
     run queue averaged over 1, 5 and 15 minutes.

     The remainder of the screen displays information about individual 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
 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 process is swapped
     out, this column is marked <swapped>).

NOTES    [Toc]    [Back]

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

ENVIRONMENT    [Toc]    [Back]

     TOP     User-configurable defaults for options.

FILES    [Toc]    [Back]

     /dev/kmem  kernel memory
     /dev/mem   physical memory
     /bsd       kernel image

SEE ALSO    [Toc]    [Back]

     kill(1), ps(1), stty(1), systat(1), mem(4), renice(8)

AUTHORS    [Toc]    [Back]

     William LeFebvre, EECS Department, Northwestern University

BUGS    [Toc]    [Back]

     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.

OpenBSD     3.6                         August      14,      1997
[ Back ]
 Similar pages
Name OS Title
top HP-UX display and update information about the top processes on the system
top Linux display top CPU processes
pstree Linux display a tree of processes
gr_top IRIX display processes having highest CPU usage in a window
swjob HP-UX display and monitor job information and create and remove jobs; invoke graphical user interface to display and
sd HP-UX display and monitor job information and create and remove jobs; invoke graphical user interface to display and
pwconv IRIX install and update /etc/shadow with information from /etc/p
ypbind Tru64 Network Information Service (NIS) server and binder processes
ypserv Tru64 Network Information Service (NIS) server and binder processes
ypxfrd HP-UX Network Information Service (NIS) server, binder, and transfer processes
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service