Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
TOP(1)							   TOP(1)

       top  -  display	and  update information about the top cpu

       top [ -SbiInqut ] [ -dcount ] [ -stime ]  [  -ofield  ]	[
       -Uusername ] [ number ]

       Top  displays the top 10 processes on the system and peri­
       odically 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

       Top  makes  a  distinction  between terminals that support
       advanced capabilities and those that do	not.   This  dis­
       tinction  affects  the  choice  of  defaults  for  certain
       options.  In the remainder of this document, an	"intelli­
       gent"  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 fea­
       tures.  If the output of top is redirected to a	file,  it
       acts as if it were being run on a dumb terminal.

       -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
	      processed,  the screen will immediately be updated,
	      even if the command was not understood.  This  mode
	      is  the default when standard output is an intelli­
	      gent terminal.

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

       -t     Do not display the top process.

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

       -q     Renice top to -20 so that it will run faster.  This

			      Local				1

TOP(1)							   TOP(1)

	      can  be used when the system is being very sluggish
	      to improve the possibility of discovering the prob­
	      lem.  This option can only be used by root.

       -u     Do  not  take  the time to map uid numbers to user­
	      names.  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.

	      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 dis­
	      plays 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  sec­
	      onds.   The default delay between updates is 2 sec­

	      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 val­
	      ues  are	"cpu", "size", "res", and "time", but may
	      vary on different operating systems.  Note that not
	      all operating systems support this option.

	      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 "infi­
       nite", indicating that they can stretch as far  as  possi­
       ble.   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, infin­

       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 vari­
       able TOP.  The options -I, -S, -u,  and	-t  are  actually
       toggles.   A  second specification of any of these options
       will negate the first.  Thus a user who has  the  environ­
       ment variable TOP set to "-I" may use the command "top -I"
       to see idle processes.

2			      Local

TOP(1)							   TOP(1)

       When top is running in "interactive mode", it  reads  com­
       mands  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  pro­
       cessed  and the display will be updated immediately there­
       after (reflecting any changes that the  command	may  have
       specified).   This  happens even if the command was incor­
       rect.  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 con­

       ^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 dis­
	      plays (prompt for new number).

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

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

       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.

			      Local				3

TOP(1)							   TOP(1)

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

       t      Toggle the display of the top process.

       The actual display varies depending on the specific  vari­
       ant 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 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 pro­
       cesses, 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 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  pro­
       cess  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  process is swapped out, this
       column is marked "<swapped>").

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

       William LeFebvre, EECS Department, Northwestern University

       TOP  user-configurable defaults for options.

       /dev/kmem      kernel memory

4			      Local

TOP(1)							   TOP(1)

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

       Don't  shoot  me,  but the default for -I has changed once
       again.  So many people were confused by the fact that  top
       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  ver­
       sion 3.0 had need only set the environment variable TOP to

       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.

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

       Mem: 9220K Active, 1032K Inact, 3284K Wired, 1MB Cache, 2M
       Buf, 1320K Free Swap:   91M Total, 79M  Free,  13%  Inuse,
       80K In, 104 K Out

       K: Kilobyte

       M:     Megabyte

       %:     1/100

	      number of pages active

       Inact: number of pages inactive

       Wired: number  of  pages wired down, including cached file
	      data pages

       Cache: number of pages used for VM-level disk caching

       Buf:   number of pages used for BIO-level disk caching

       Free:  number of pages free

       Total: total available swap usage

			      Local				5

TOP(1)							   TOP(1)

       Free:  total free swap usage

       Inuse: swap usage

       In:    pages paged in from swap devices (last interval)

       Out:   pages paged out to swap devices (last interval)

6			      Local


Want to link to this manual page? Use this URL:

home | help