TOP(1)                                                                  TOP(1)




NAME

       top - display and update information about the top cpu processes


SYNOPSIS

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


DESCRIPTION

       Top displays the top  30  processes  on  the  system  and  periodically
       updates  this information.  Raw cpu percentage is used to rank the pro-
       cesses.  If number is given, then the top number processes will be dis-
       played instead of the default.

       Top  makes  a distinction between terminals that support advanced capa-
       bilities 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,  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  redi-
       rected to a file, it acts as if it were being run on a dumb terminal.


OPTIONS

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

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

       -S, --system-procs
              Show system processes in the  display.   Normally,  system  pro-
              cesses  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.

       -c, --full-commands
              Show the full command line for each process. Default is to  show
              just  the  command  name.   This  option is not supported 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  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.

       -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  possibil-
              ity of discovering the problem.  This option can only be used by
              root.

       -t, --threads
              Show individual threads on separate lines.  By default, on  sys-
              tems 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  execu-
              tion  time.  The uid numbers are displayed instead of the names.

       -v, --version
              Write version number information to  stderr  then  exit  immedi-
              ately.   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 considered to
              be one update of the screen.  This option  allows  the  user  to
              select  the  number of displays he wants to see before top auto-
              matically 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.

       -m mode, --mode=mode
              Start  the display in an alternate mode.  Some platforms support
              multiple process displays to show  additional  process  informa-
              tion.   The value mode is a number indicating which mode to dis-
              play.  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  cur-
              rently  only  accepts usernames and will not understand uid num-
              bers.

       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  envi-
       ronment variable TOP.  The options -C, -I, -S, and -u are actually tog-
       gles.  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 dis-
       plays; 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 update and then process the command.  Some commands
       require additional information, and the user will be  prompted  accord-
       ingly.   While  typing  this  information in, the user's erase and kill
       keys (as set up by the command stty) are recognized, and a newline ter-
       minates  the input.  Note that a control-L (^L) always redraws the cur-
       rent 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).  Version infor-
              mation is included in this display.

       C      Toggle the use of color in the display.

       c      Display  only  processes  whose  commands  match  the  specified
              string.   An empty string will display all processes.  This com-
              mand is not supported on all platforms.

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

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

       k      Send a signal ("kill" by default) to a list of processes.   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 systems pro-
              vide multiple display modes for the process display which  shows
              different  information.  This command toggles between the avail-
              able 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  num-
              ber).

       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  processes.   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 pro-
              cesses belonging to all users will be displayed.


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  particular  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 systems) 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 ker-
       nel-related activity (not available on all systems).  The numbers 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.

       The  remainder of the screen displays information about individual pro-
       cesses.  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.  Generally, the following  fields  are  dis-
       played:

       PID    The process id.

       USERNAME
              Username  of the process's owner (if -u is specified, a UID col-
              umn 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 kilo-
              bytes.

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

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

       COMMAND
              Name of the command that the process is currently running.


COLOR

       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 ter-
       minals that understand and process ANSI color escape sequences.

       The  environment  variable is a sequence of color specifications, sepa-
       rated 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 displayed in red. Color  attributes  can  be
       combined.   For  example,  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  installation  of
       top  with  the -T option.  This will also show the current set of tests
       used for color highligting, as specified in the environment.


AUTHOR

       William LeFebvre


ENVIRONMENT

       TOP       user-configurable  defaults  for  options.    TOPCOLORS color
       specification


BUGS

       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) @MAN_SUPPLEMENT@


DEC OSF/1 NOTES

       Original  author  was  Anthony  Baxter,  <anthony@aaii.oz.au>.  Derived
       originally from  m_ultrix,  by  David  S.  Comay  <dsc@seismo.css.gov>,
       although  by  now  there  is hardly any of the code from m_ultrix left.
       Helped a lot by having the source for syd(1), by Claus Kalle, and  from
       several  people at DEC who helped with providing information on some of
       the less-documented bits of the kernel interface.  Patches from  Rainer
       Orth <ro@TechFak.Uni-Bielefeld.DE>

       Theory  of  operation: Use Mach calls to build up a structure that con-
       tains all the sorts of stuff normally found in a struct proc in  a  BSD
       system.  Then  everything else uses this structure. This has major per-
       formance wins, and also should work for future versions of the O/S.


FreeBSD NOTES

       Priorities are shown the same as they exist in process data structures,
       ranging  from  0  to  255.  Note that this is not the same as the ps(1)
       "pri" column, which subtracts 84 from each number before displaying it.
       Priority numbers fall in to priority classes as follows:

       0 - 63         Interrupt threads

       64 - 127       Top half kernel threads

       128 - 159      Realtime user threads

       160 - 223      Time sharing user threads

       224 - 255      Idle user threads



FreeBSD THREADS

       Starting with FreeBSD 8.0 the display of individual threads can be tog-
       gled with the synonymous commands t and H.   Information  about  state,
       flags,  CPU  time and percent cpu are shown for each individual thread.
       Other information is identical for all threads in the same process.



FreeBSD ALTERNATE DISPLAY

       FreeBSD supports an alternate process display which shows i/o  informa-
       tion.   Since  this  information  is  tracked  per  process and not per
       thread, the per-thread display is not  supported  in  this  mode.   All
       fields  calculate  the  number  of  operations  observed since the last
       update and are displayed as a per-second rate.  The fields in this dis-
       play are as follows:

       VCSW   Voluntary context switches

       IVCSW  Involuntary context switches

       READ   Number of blocks read

       WRITE  Number of blocks written

       FAULT  Number of page faults

       TOTAL  Total number of i/o operations

       PERCENT
              Percentage  of  total i/o attributed to this process.  If no i/o
              occured then this field is 0 for all processes.



FreeBSD KERNEL SUMMARY

       All rates are shown per-second.

       Ctx    Number of context switches.

       Trap   Number of kernel traps.

       Intr   Number of device interrupts.

       Soft   Number of software interrupts.

       Fork   Number of forks, vforks, and rforks.

       Flt    Total number of page faults.

       Pgin   Number of pages paged or swapped in to physical memory.

       Pgout  Number of pages paged or swapped out from physical memory.

       Fr     Total number of pages freed.


FreeBSD MEMORY SUMMARY

       Memory: 10M Act 1208K Inact 3220K Wired 132K  Free  25%  Swap,  2924Kin
       2604Kout

       K:     Kilobyte

       M:     Megabyte

       G:     Gigabyte

       %:     1/100


       Act:   number of pages active

       Inact: number of pages inactive

       Wired: number of pages wired down

       Free:  number of pages free

       Swap:  swap usage

       Kin:   kilobytes swap pager pages paged in (last interval)

       Kout:  kilobytes swap pager pages paged out  (last interval)


       See /usr/include/sys/vmmeter.h and  /sys/vm/vm_meter.c.

       Contributors: Christos Zoulas, Steven Wallace, Wolfram Schneider, Monte
       Mitzelfelt.

       This module was retrofitted from FreeBSD 4.6.2 sources.


HPUX 9 INFORMATION

       Under HP/UX 9, the kernel symbol  _ccpu  was  eliminated.   The  author
       believe  that  _cexp  is a suitable substitute, but cannot be positive.
       This seems to be confirmed by the fact that information produced  using
       this  assumption  correlates well with that produced by HP's version of
       top.

       This port was adapted from the port for HP/UX  version  8  (written  by
       Christos  Zoulas).   The  adaptation  was  performed  by  Kevin Schmidt
       <kevin@mcl.ucsb.edu>.


HPUX 10 INFORMATION

       The process information layout has changed slightly since previous ver-
       sions.   The  CPU  percentage column reports weighted cpu as calculated
       directly by the kernel.  The WCPU column is no longer  present  in  the
       output  and  a  TTY  column  has been added to indicate the name of the
       process's controlling terminal.  The definition of an idle process  has
       been  relaxed  to  include  those processes that have only just gone to
       sleep.

       This version of top does not display a per-cpu breakdown  of  processor
       state.  Perhaps a later version will add this sophistication across all
       platforms.

       The HP/UX 10 port has greatly benefitted from the diligent  efforts  of
       the  following  individuals:  John Haxby <john_haxby@hp.com>, Rich Hol-
       land <holland@synopsys.com>, and <kevin@mcl.ucsb.edu>.



LINUX NOTES

       The Linux port was written by Richard  Henderson  <rth@tamu.edu>.   The
       CPU% calculation was brazenly stolen from the Solaris 2 port and should
       be attributed to one of the many names listed in its man page.

       The order support was stolen  from  SUNOS  5  port  by  Alexey  Klimkin
       <kad@klon.tme.mcst.ru>

       Made to work under 2.4 by William LeFebvre.


NetBSD NOTES

       This  module  has been tested on NetBSD 1.6, NetBSD 2.0 and NetBSD 3.0.
       It should also work on NetBSD 1.5, and probably any newer  releases  of
       NetBSD with little or no changes.


SUNOS 4 DIFFERENCES

       On  multiprocessor machines, the amount of time the processors spend in
       a spin lock is displayed along with the other processor state  percent-
       ages.   The  percentages shown for processor states are averages across
       all processors.  A process in run state also has its current  processor
       displayed in the STATE column, for example "run/2" indicates running on
       processor 2.  There is an extra column in the process display  indicat-
       ing  which  processor each running process is assigned to.  Information
       about physical memory is displayed  on  the  memory  status  line,  but
       information about virtual memory is not available.

       Due  to  incompatabilities  in kernel data structures, a top executable
       compiled on a Sun 4 multiprocessor architecture  machine  (sun4m)  will
       not  run  correctly  on a uniprocessor architecture machine (sun4), and
       vice versa.  You will have to compile and maintain separate executables
       for these architectures.  Yeah, I don't like it either.

       Some processes may show up with a resident set size (RES column) larger
       than total virtual memory size (SIZE column).  This seems odd at first,
       but  is a consequence of shared libraries:  shared memory is counted as
       resident but is not counted in total size.

       The SunOS 4 port was written by William LeFebvre.


SUNOS 5 NOTES

       CPU percentage is calculated as a fraction of total available 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 pro-
       cessors.   For  example,  on  a  4 processor machine, a single threaded
       process will never show a cpu percentage higher than 25%.  The CPU per-
       centage  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 disk.

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

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

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

       The display of individual threads can be toggled  with  the  synonymous
       commands t and H.  Information about state, priority, CPU time and per-
       cent CPU are shown for each individual 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,
       <torsten@techfak.uni-bielefeld.de>.  Many contributions have been  pro-
       vided  by Casper Dik <Casper.Dik@sun.com>.  Support for multi-cpu, cal-
       culation  of  CPU%  and  memory  stats  provided  by   Robert   Boucher
       <boucher@sofkin.ca>,   Marc   Cohen   <marc@aai.com>,  Charles  Hedrick
       <hedrick@geneva.rutgers.edu>, and William L. Jones <jones@chpc>.


SVR4 CREDITS

       The SVR4 port was initially written by Andrew Herbert.  He  was  guided
       by  a  SVR4  port  of  top  version  2.1  which  was done by Andy Crump
       (andyc@bucky.intel.com).  Robert Boucher (boucher@sofkin.ca) adapted it
       to top version 3.1.  Ported to System 3000 Release 2.03 by Jeff Janvrin
       (jeff.janvrinColumbiaSC.NCR.COM)


SVR5 CREDITS

       The SVR5 port was generated by Mike Hopkirk  from  the  SVR42  port  by
       David Cutter with lots of help from Kurt Gollhardt and Doug Souders



COPYRIGHT

       Copyright  (C)  1984-2007  William  LeFebvre.  For additional licensing
       information, see http://www.unixtop.org/license/



4th Berkeley Distribution            Local                              TOP(1)