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

FreeBSD Manual Pages


home | help
TOP(1)			      Linux User's Manual			TOP(1)

       top - display top CPU processes

       top [-] [d delay] [p pid] [q] [c] [C] [S] [s] [i] [n iter] [b]

       top  provides  an  ongoing look at processor activity in	real time.  It
       displays	a listing of the most CPU-intensive tasks on the  system,  and
       can  provide  an	 interactive interface for manipulating	processes.  It
       can sort	the tasks by CPU usage,	memory usage and runtime.  can be bet-
       ter  configured than the	standard top from the procps suite.  Most fea-
       tures can either	be selected by an interactive command or by specifying
       the  feature  in	 the  personal	or system-wide configuration file. See
       below for more information.

       d    Specifies the delay	between	screen updates.	 You can  change  this
	    with the s interactive command.

       p    Monitor  only  processes  with given process id.  This flag	can be
	    given up to	twenty times. This option is neither available	inter-
	    actively nor can it	be put into the	configuration file.

       q    This  causes  top  to refresh without any delay. If	the caller has
	    superuser privileges, top runs with	the highest possible priority.

       S    Specifies  cumulative  mode, where each process is listed with the
	    CPU	time that it as	well as	its dead children has spent.  This  is
	    like  the  -S  flag	 to  ps(1).  See the discussion	below of the S
	    interactive	command.

       s    Tells top to run in	secure mode.  This  disables  the  potentially
	    dangerous  of  the interactive commands (see below).  A secure top
	    is a nifty thing to	leave running on a spare terminal.

       i    Start top ignoring any idle	or zombie processes. See the  interac-
	    tive command i below.

       C    display  total  CPU	states instead of individual CPUs. This	option
	    only affects SMP systems.

       c    display command line instead of the	command	name only. The default
	    behavior has been changed as this seems to be more useful.

       H    Show all threads.

       n    Number  of iterations. Update the display this number of times and
	    then exit.

       b    Batch mode.	Useful for sending output from top to  other  programs
	    or	to  a  file.   In  this	mode, top will not accept command line
	    input.  It	runs  until  it	 produces  the	number	of  iterations
	    requested  with the	n option or until killed. Output is plain text
	    suitable for display on a dumb terminal.

       top displays a variety of information about the processor  state.   The
       display	is updated every 5 seconds by default, but you can change that
       with the	d command-line option or the s interactive command.

	    This line displays the time	the system has been up,	and the	 three
	    load  averages  for	the system.  The load averages are the average
	    number of process ready to run during the last 1, 5	 and  15  min-
	    utes.  This	line is	just like the output of	uptime(1).  The	uptime
	    display may	be toggled by the interactive l	command.

	    The	total number of	processes running at  the  time	 of  the  last
	    update.   This  is also broken down	into the number	of tasks which
	    are	running, sleeping,  stopped,  or  undead.  The	processes  and
	    states display may be toggled by the t interactive command.

       CPU states
	    Shows  the percentage of CPU time in user mode, system mode, niced
	    tasks, iowait and idle.  (Niced tasks are only  those  whose  nice
	    value  is  positive.)   Time  spent	 in  niced  tasks will also be
	    counted in system and user time, so	the total will	be  more  than
	    100%.   The	 processes  and	states display may be toggled by the t
	    interactive	command.

       Mem  Statistics on memory usage,	including total	available memory, free
	    memory,  used  memory, shared memory, and memory used for buffers.
	    The	display	of memory information may be toggled by	the m interac-
	    tive command.

       Swap Statistics	on  swap  space, including total swap space, available
	    swap space,	and used swap space.  This and Mem are just  like  the
	    output of free(1).

       PID  The	process	ID of each task.

       PPID The	parent process ID each task.

       UID  The	user ID	of the task's owner.

       USER The	user name of the task's	owner.

       PRI  The	priority of the	task.

       NI   The	 nice value of the task.  Negative nice	values are higher pri-

       SIZE The	size of	the task's code	plus data plus stack space,  in	 kilo-
	    bytes, is shown here.

	    The	 code  size  of	the task. This gives strange values for	kernel
	    processes and is broken for	ELF processes.

	    Data + Stack size. This is broken for ELF processes.

       TRS  Text resident size.

       SWAP Size of the	swapped	out part of the	task.

       D    Size of pages marked dirty.

       LC   Last used processor.  (That	this changes from time to time is  not
	    a  bug;  Linux intentionally uses weak affinity.  Also notice that
	    the	very act of running top	may break weak affinity	and cause more
	    processes  to  change  current CPU more often because of the extra
	    demand for CPU time.)

       RSS  The	total amount of	physical memory	used by	 the  task,  in	 kilo-
	    bytes,  is	shown  here.  For ELF processes	used library pages are
	    counted here, for a.out processes not.

	    The	amount of shared memory	used by	the task is shown in this col-

       STAT The	 state	of  the	 task is shown here. The state is either S for
	    sleeping, D	for uninterruptible sleep, R for running, Z  for  zom-
	    bies,  or  T  for  stopped or traced. These	states are modified by
	    trailing < for a process with negative nice	value, N for a process
	    with  positive  nice value,	W for a	swapped	out process (this does
	    not	work correctly for kernel processes).

	    depending on the availability of either  /boot/psdatabase  or  the
	    kernel  link  map  /boot/	 this shows the	address	or the
	    name of the	kernel function	the task currently is sleeping in.

       TIME Total CPU time the task has	used since it started.	If  cumulative
	    mode  is on, this also includes the	CPU time used by the process's
	    children which have	died.  You can set cumulative mode with	the  S
	    command  line  option or toggle it with the	interactive command S.
	    The	header line will then be changed to CTIME.

       %CPU The	task's share of	the CPU	time since  the	 last  screen  update,
	    expressed as a percentage of total CPU time	per processor.

       %MEM The	task's share of	the physical memory.

	    The	task's command name, which will	be truncated if	it is too long
	    to be displayed on one line.  Tasks	in memory  will	 have  a  full
	    command line, but swapped-out tasks	will only have the name	of the
	    program in parentheses (for	example, "(getty)").

       A , WP
	    these fields from the kmem top are not supported.

       Several single-key commands are recognized while	top is running.	  Some
       are disabled if the s option has	been given on the command line.

	    Immediately	updates	the display.

       ^L   Erases and redraws the screen.

       h or ?
	    Displays a help screen giving a brief summary of commands, and the
	    status of secure and cumulative modes.

       k    Kill a process.  You will be prompted for the PID of the task, and
	    the	signal to send to it.  For a normal kill, send signal 15.  For
	    a sure, but	rather abrupt, kill, send signal 9.  The default  sig-
	    nal,  as with kill(1), is 15, SIGTERM.  This command is not	avail-
	    able in secure mode.

       i    Ignore idle	and zombie processes.  This is a toggle	switch.

       I    Toggle between Solaris (CPU	percentage divided by total number  of
	    CPUs)  and	Irix  (CPU  percentage	calculated solely by amount of
	    time) views.  This is a toggle switch that affects only  SMP  sys-

       n or #
	    Change  the	 number	of processes to	show.  You will	be prompted to
	    enter the number.  This overrides automatic	determination  of  the
	    number  of	processes  to show, which is based on window size mea-
	    surement.  If 0 is specified, then top will	show as	many processes
	    as will fit	on the screen; this is the default.

       q    Quit.

       r    Re-nice  a process.	 You will be prompted for the PID of the task,
	    and	the value to nice it to.  Entering a positve value will	 cause
	    a  process	to be niced to negative	values,	and lose priority.  If
	    root is running top, a negative value can be  entered,  causing  a
	    process  to	get a higher than normal priority.  The	default	renice
	    value is 10.  This command is not available	in secure mode.

       S    This toggles cumulative mode, the equivalent of ps -S, i.e.,  that
	    CPU	 times	will  include  a process's defunct children.  For some
	    programs, such as compilers, which work by forking into many sepa-
	    rate  tasks, normal	mode will make them appear less	demanding than
	    they actually are.	For others, however, such as shells and	 init,
	    this behavior is correct.  In any case, try	cumulative mode	for an
	    alternative	view of	CPU use.

       s    Change the delay between updates.  You will	be prompted  to	 enter
	    the	 delay	time,  in seconds, between updates.  Fractional	values
	    are	recognized down	to microseconds.  Entering 0 causes continuous
	    updates.   The  default  value is 5	seconds.  Note that low	values
	    cause nearly unreadably fast displays, and greatly raise the load.
	    This command is not	available in secure mode.

       f or F
	    Add	fields to display or remove fields from	the display. See below
	    for	more information.

       o or O
	    Change order of displayed fields. See below	for more  information.

       l    toggle display of load average and uptime information.

       m    toggle display of memory information.

       t    toggle display of processes	and CPU	states information.

       c    toggle display of command name or full command line.

       N    sort tasks by pid (numerically).

       A    sort tasks by age (newest first).

       P    sort tasks by CPU usage (default).

       M    sort tasks by resident memory usage.

       T    sort tasks by time / cumulative time.

       W    Write  current  setup to ~/.toprc.	This is	the recommended	way to
	    write a top	configuration file.

The Field and Order Screens
       After pressing f, F, o or O you will be shown a screen  specifying  the
       field  order  on	 the top line and short	descriptions of	the field con-
       tents. The field	order string uses the following	syntax:	If the	letter
       in  the filed string corresponding to a	field is upper case, the field
       will be displayed.  This	is furthermore indicated  by  an  asterisk  in
       front of	the field description.	The order of the fields	corresponds to
       the order of the	letters	in the string.
	From the field select screen you can toggle the	display	of a field  by
       pressing	the corresponding letter.
	From the order screen you may move a field to the left by pressing the
       corresponding upper case	letter resp. to	 the  right  by	 pressing  the
       lower case one.

Configuration Files
       Top  reads  it's	 default  configuration	from two files,	/etc/toprc and
       ~/.toprc.  The global configuration file	may be used  to	 restrict  the
       usage  of  top to the secure mode for non-non-privileged	users. If this
       is desired, the file should contain a 's' to specify secure mode	and  a
       digit  d	(2<=d<=9) for the default delay	(in seconds) on	a single line.
       The personal configuration file contains	two lines. The first line con-
       tains lower and upper letters to	specify	which fields in	what order are
       to be displayed.	The letters correspond to the letters in the Fields or
       Order  screens  from top. As this is not	very instructive, it is	recom-
       mended to select	fields and order in a running top process and to  save
       this  using  the	W interactive command.	The second line	is more	inter-
       esting (and important). It contains information on the  other  options.
       Most  important,	 if you	have saved a configuration in secure mode, you
       will not	get an insecure	top without removing the lower	's'  from  the
       second line of your ~/.toprc.  A	digit specifies	the delay time between
       updates,	a capital 'S' cumulative mode, a lower	'i'  no-idle  mode,  a
       capital	'I'  Irix  view. As in interactive mode, a lower 'm', 'l', and
       't' suppresses the display of memory,  uptime  resp.  process  and  CPU
       state  information.   Currently	changing the default sorting order (by
       CPU usage) is not supported.

       This proc-based top works by reading the	files in the proc  filesystem,
       mounted on /proc.  If /proc is not mounted, top will not	work.

       %CPU  shows  the	 cputime/realtime  percentage  in  the	period of time
       between updates.	 For the first update, a short delay is	used, and  top
       itself  dominates the CPU usage.	 After that, top will drop back, and a
       more reliable estimate of CPU usage is available.

       The SIZE	and RSS	fields don't count the page tables and the task_struct
       of  a  process; this is at least	12K of memory that is always resident.
       SIZE is the virtual size	of the process (code+data+stack).

       Keep in mind that a process must	die for	its time to be recorded	on its
       parent  by  cumulative  mode.  Perhaps more useful behavior would be to
       follow each process upwards, adding time, but that would	be more	expen-
       sive,  possibly	prohibitively  so.  In any case, that would make top's
       behavior	incompatible with ps.

       /etc/toprc The global configuration file.  ~/.toprc The	personal  con-
       figuration file.

       ps(1), free(1), uptime(1), kill(1), renice(1).

       If  the window is less than about 70x7, top will	not format information
	Many fields still have problems	with ELF processes.
	the help screens are not yet optimized for windows with	less  than  25

       top  was	originally written by Roger Binns, based on Branko Lankester's
       <>	  ps	   program.	   Robert	Nation
       <>  re-wrote  it significantly	to use
       the proc	filesystem,  based  on	Michael	 K.  Johnson's	<johnsonm@red->	     proc-based	     ps	     program.	   Michael     Shields
       <>	made many changes, including secure and	 cumu-
       lative modes and	a general cleanup.  Tim	Janik <> added age
       sorting and the ability to monitor  specific  processes	through	 their

       Helmut Geyer <> Heavily changed it to
       include support for configurable	fields and other new options, and  did
       further cleanup and use of the new readproc interface.

       The    "b"    and    "n"	  options   contributed	  by   George	Bonser
       <> for	CapTech	IT Services.

       Michael K. Johnson <>	is now the maintainer.

       Please send bug reports to <>

Linux				  Feb 1	1993				TOP(1)


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

home | help