man pages section 1: User Commands

Exit Print View

Updated: July 2014

top (1)


top - cesses


top [ -CISTabcinqtuv ] [ -dcount ] [ -mmode ] [ -ofield ]  [
-stime ] [ -Uusername ] [ number ]


User Commands                                              TOP(1)

     top  - display and update information about the top cpu pro-

     top [ -CISTabcinqtuv ] [ -dcount ] [ -mmode ] [ -ofield ]  [
     -stime ] [ -Uusername ] [ number ]

     Top displays the top 30 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.

     -C, --color
          Turn off the use of color in the display.

     -I, --idle-procs
          Do not display idle processes.  By  default,  top  dis-
          plays both active and idle processes.

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

     -T, --tag-names
          List  all  available  color tags and the current set of
          tests used for color highlighting, then exit.

     -a, --all
          Show all processes for as long as  possible.   This  is
          shorthand  for "-d all all".  This option is especially
          handy in batch mode.

     -b, -n, --batch
          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.

SunOS 5.11              Last change: Local                      1

User Commands                                              TOP(1)

     -c, --full-commands
          Show the full command line for each process. Default is
          to show just the command name.  This option is not sup-
          ported on all platforms.

     -i, --interactive
          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-

     -q, --quick
          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 root.

     -t, --threads
          Show individual threads on separate lines.  By default,
          on systems which support  threading,  each  process  is
          shown  with  a  count  of  the  number of threads. This
          option shows each thread  on  a  separate  line.   This
          option is not supported on all platforms.

     -u, --uids
          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

     -v, --version
          Write  version  number  information to stderr then exit
          immediately.  No other processing takes place when this
          option  is  used.   To see current revision information
          while top is running, use the help command "?".

     -d count, --displays count
          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.  Any
          proper prefix of the words  "infinity",  "maximum",  or
          "all"  can  be  used  to indicate an infinite number of
          displays.  The default  for  intelligent  terminals  is
          infinity.  The default for dumb terminals is 1.

2                       Last change: Local             SunOS 5.11

User Commands                                              TOP(1)

     -m mode, --mode=mode
          Start the display in an alternate mode.  Some platforms
          support multiple process displays  to  show  additional
          process  information.  The value mode is a number indi-
          cating which mode to display.  The default  is  0.   On
          platforms  that do not have multiple display modes this
          option has no effect.

     -o field, --sort-order=field
          Sort the process display area on the  specified  field.
          The field name is the name of the column as seen in the
          output, but in lower case.  Likely  values  are  "cpu",
          "size",  "res",  and  "time", but may vary on different
          operating systems.  Note that not all operating systems
          support this option.

     -s time, --delay=time
          Set  the  delay between screen updates to time seconds.
          The default delay between updates is 5 seconds.

     -U username, --user=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",
     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 -C, -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.

     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
     the command was incorrect.  If a key is pressed while top is
     in  the  middle  of updating the display, it will finish the

SunOS 5.11              Last change: Local                      3

User Commands                                              TOP(1)

     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 rec-
     ognized, and a newline terminates the input.   Note  that  a
     control-L (^L) always redraws the current screen and a space
     forces an immediate update to the screen using new data.

     These commands are currently recognized:

     h or ?
          Display a summary of the commands (help screen).   Ver-
          sion information is included in this display.

     C    Toggle the use of color in the display.

     c    Display  only processes whose commands match the speci-
          fied string.  An empty string  will  display  all  pro-
          cesses.   This  command  is  not supported on all plat-

     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.

     f    Toggle the display of the full command line.

     H    Toggle  the  display  of threads on separate lines.  By
          default,  on  systems  which  support  threading,  each
          process is shown with a count of the number of threads.
          This command shows each  thread  on  a  separate  line.
          This command is not supported on all platforms.

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

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

     M    Sort display by memory usage.  Shorthand for "o  size".

     m    Change  to a different process display mode.  Some sys-
          tems provide multiple display  modes  for  the  process
          display  which  shows different information.  This com-
          mand toggles between the available modes.  This command
          is not supported on all platforms.

     N    Sort by process id.  Shorthand for "o pid".

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

4                       Last change: Local             SunOS 5.11

User Commands                                              TOP(1)

     o    Change the order in which the display is sorted.   This
          command  is not available on all systems.  The sort key
          names vary fron system to system but  usually  include:
          "cpu", "res", "size", "time".  The default is cpu.

     P    Sort by CPU usage.  Shorthand for "o cpu".

     q    Quit top.

     r    Change  the  priority  (the  "nice")  of a list of pro-
          cesses.  This acts similarly to the command renice(8)).

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

     T    Sort by CPU time.  Shorthand for "o time".

     U    Toggle between displaying usernames and uids.

     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  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 par-
     ticular machine.  Differences are listed at the end of  this
     manual entry.

     The  top lines of the display show general information about
     the state of the system.  The first line shows (on some sys-
     tems)  the  last process id assigned to a process, the three
     load averages, the system uptime, and the current time.  The
     second  line displays the total number of processes followed
     by a breakdown of processes per state.  Examples  of  states
     common  to  Unix  systems  are  sleeping, running, starting,
     stopped, and zombie.  The next line displays a percentage of
     time  spent in each of the processor states (typically user,
     nice, system, idle, and iowait).  These percentages show the
     processor  activity  during  the time since the last update.
     For multi-processor systems, this information is a summation
     of  time across all processors.  The next line shows kernel-
     related activity (not available on all systems).   The  num-
     bers  shown  on this line are per-second rates sampled since
     the last update.  The  exact  information  displayed  varies
     between  systems,  but  some examples are: context switches,
     interrupts, traps, forks, and page faults.  The last one  or
     two lines show a summary of memory and swap activity.  These
     lines vary between systems.

SunOS 5.11              Last change: Local                      5

User Commands                                              TOP(1)

     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.  The columns displayed
     by top will differ slightly between operating systems.  Gen-
     erally, the following fields are displayed:

     PID  The process id.

          Username of the process's owner (if -u is specified,  a
          UID column will be substituted for USERNAME).

     THR  The number of threads in the processes (this column may
          also be labeled NLWP).

     PRI  Current priority of the process.

     NICE Nice amount in the range -20 to 20, as  established  by
          the use of the command nice.

     SIZE Total size of the process (text, data, and stack) given
          in kilobytes.

     RES  Resident memory: current amount of process memory  that
          resides in physical memory, given in kilobytes.

          Current  state (typically one of "sleep", "run", "idl",
          "zomb", or "stop").

     TIME Number of system and user cpu seconds that the  process
          has used.

     CPU  Percentage  of available cpu time used by this process.

          Name of the command that the process is currently  run-

     Top  supports  the  use  of  ANSI  color  in  its output. By
     default, color is available but not used.   The  environment
     variable  TOPCOLORS  specifies  colors to use and conditions
     for which they should be used.  At the  present  time,  only
     numbers  in  the  summay  display  area can be colored. In a
     future version it will be possible to highlight  numbers  in
     the  process display area as well.  The environment variable
     is the only way to specify color:  there  is  no  equivalent
     command  line  option.   Note  that the environment variable
     TOPCOLOURS is also understood. The  British  spelling  takes
     precedence.   The  use of color only works on terminals that
     understand and process ANSI color escape sequences.

6                       Last change: Local             SunOS 5.11

User Commands                                              TOP(1)

     The environment variable is a sequence of  color  specifica-
     tions,  separated  by  colons.  Each specification takes the
     form tag=min,max#code where tag is the name of the value  to
     check,  min  and max specify a range for the value, and code
     is an ANSI color code.  Multiple color codes can  be  listed
     and  separated  with semi-colons.  A missing min implies the
     lowest possible value (usually 0) and a missing max  implies
     infinity.  The comma must always be present. When specifying
     numbers for load averages, they should be multiplied by 100.
     For  example,  the  specification 1min=500,1000#31 indicates
     that a 1 minute load average between 5 and 10 should be dis-
     played  in red. Color attributes can be combined.  For exam-
     ple, the specification 5min=1000,#37;41 indicates that  a  5
     minute  load average higher than 10 should be displayed with
     white characters on a red background. A  special  tag  named
     header  is  used  to  control  the  color  of the header for
     process display.  It should be specified with no  lower  and
     upper  limits,  specifically  header=,# followed by the ANSI
     color code.

     You can see a list of color codes recognized by this instal-
     lation  of  top with the -T option.  This will also show the
     current set of tests used for color highligting,  as  speci-
     fied in the environment.

     William LeFebvre

     TOP       user-configurable  defaults  for options.  TOPCOL-
     ORS color specification

     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  attributes(5)  for  descriptions   of   the   following

     |Availability   | diagnostic/top   |
     |Stability      | Uncommitted      |
     kill(1), ps(1), stty(1), mem(4), renice(8)

SunOS 5.11              Last change: Local                      7

User Commands                                              TOP(1)

     CPU  percentage  is calculated as a fraction of total avail-
     able computing resources.  Hence on a multiprocessor machine
     a  single  threaded  process  can  never consume cpu time in
     excess of 1 divided by the number of processors.  For  exam-
     ple,  on  a  4  processor machine, a single threaded process
     will never show a cpu percentage higher than 25%.   The  CPU
     percentage  column  will  always  total  approximately  100,
     regardless of the number of processors.

     The kernel summary line shows the following information, all
     displayed as a per-second rate:

     ctxsw    Context switches.

     trap     Number of traps.

     intr     Number of interrupts.

     syscall  Number of system calls.

     fork     Number of forks and vforks.

     flt      Number of page faults.

     pgin     Number of kilobytes paged in to physical memory.

     pgout    Number of kilobytes paged out from physical memory.

     The memory summary line displays the following:

     phys mem      Total amount of physical memory  that  can  be
                   allocated  for  use  by processes (it does not
                   include memory reserved for the kernel's use).

     free mem      The amount of unallocated physical memory.

     total swap    The  total  amount  of  swap area allocated on

     free swap     The amount of swap area on disk that is  still

     Unlike  previous versions of top, the swap figures will dif-
     fer from the summary output of  swap(1M)  since  the  latter
     includes physical memory as well.

     The  column  NLWP  indicates  the number of lightweight pro-
     cesses in a process.  This usually corresponds to the number
     of threads in that process.

8                       Last change: Local             SunOS 5.11

User Commands                                              TOP(1)

     The  display  of  individual threads can be toggled with the
     synonymous commands t and H.  Information about state,  pri-
     ority,  CPU time and percent CPU are shown for each individ-
     ual thread.  Other information is identical for all  threads
     in  the  same  process.   In  this  display  the  column LWP
     replaces NLWP and shows the  lightweight  process  id.   The
     column names LWP and NLWP are consistent with ps(1).

     In  BSD Unix, process priority was represented internally as
     a signed offset from a zero value with  an  unsigned  value.
     The "zero" value was usually something like 20, allowing for
     a range of priorities from -20 to  20.   As  implemented  on
     SunOS  5,  older  versions  of  top  continued  to interpret
     process priority in this  manner,  even  though  it  was  no
     longer  correct.   Starting  with  top version 3.5, this was
     changed to agree with the rest of the system.

     Long options are not currently available in Solaris.

     The SunOS 5 (Solaris  2)  port  was  originally  written  by
     Torsten   Kasch,  <>.   Many
     contributions   have   been   provided   by    Casper    Dik
     <>.  Support for multi-cpu, calculation of
     CPU%  and  memory   stats   provided   by   Robert   Boucher
     <>,   Marc  Cohen  <>,  Charles
     Hedrick <>, and William  L.  Jones

     Copyright  (C)  1984-2007  William  LeFebvre. For additional
     licensing information, see

     This  software  was   built   from   source   available   at    The  original
     community  source  was  downloaded  from    http://www.unix-

     Further  information about this software can be found on the
     open source community website at

SunOS 5.11              Last change: Local                      9