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

FreeBSD Manual Pages

  
 
  

home | help
TOP(1)			FreeBSD	General	Commands Manual			TOP(1)

NAME
     top -- display and	update information about the top CPU processes

SYNOPSIS
     top [-1bCHIinqStu]	[-d count] [-g string] [-o [-]field] [-p pid]
	 [-s time] [-T [-]rtable] [-U [-]user] [number]

DESCRIPTION
     top displays the top processes on the system and periodically updates
     this information.	If standard output is an intelligent terminal (see be-
     low) then as many processes as will fit on	the terminal screen are	dis-
     played 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 de-
     fault.

     top makes a distinction between terminals that support advanced capabili-
     ties and those that do not.  This distinction affects the choice of de-
     faults 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.

     The options are as	follows:

     -1	     Display combined CPU statistics for all processors	on a single
	     line instead of one line per CPU.	If there are more than 8 CPUs
	     detected in the system this option	is automatically enabled.

     -b	     Use batch mode.  In this mode, all	input from the terminal	is ig-
	     nored.  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	     Show command line arguments as well as the	process	itself.

     -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 se-
	     lect the number of	displays to be shown before top	automatically
	     exits.  For intelligent terminals,	no upper limit is set.	The
	     default is	1 for dumb terminals.

     -g	string
	     Display only processes that contain string	in their command name.
	     If	displaying of arguments	is enabled, the	arguments are searched
	     too.

     -H	     Show process threads in the display.  Normally, only the main
	     process is	shown.	This option makes all threads visible.

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

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

     -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 `-' prefix reverses the or-
	     der.  The OpenBSD version of top supports cpu, size, res, time,
	     pri, pid, and command.

     -p	pid  Show only the process pid.

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

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

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

     -T	[-]rtable
	     Display only processes associated with the	specified routing ta-
	     ble rtable.  `T+' shows processes associated with all routing ta-
	     bles.  The	`-' prefix hides processes associated with a single
	     routing table.

     -t	     Display routing tables.  By default, routing tables are not
	     shown.

     -U	[-]user
	     Show only those processes owned by	username or UID	user.  The
	     prefix `-'	hides processes	owned by that user.

     -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 execution
	     time.  The	UID numbers are	displayed instead of the names.

     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 environ-
     ment variable TOP.

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

INTERACTIVE MODE
     When top is running in interactive	mode, it reads commands	from the ter-
     minal 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
     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(1)) are recognized, and a newline terminates the input.

     These commands are	currently recognized (^L refers	to control-L):

     h | ?   Display a summary of the commands (help screen).

     ^L	     Redraw the	screen.

     <space>
	     Update the	screen.

     q	     Quit top.

     +	     Reset any filters put in place by the `g',	`p', and `u' interac-
	     tive commands, or their command line equivalents, or any process
	     highlighting put in place by the `P' interactive command.

     1	     Toggle the	display	of per CPU or combined CPU statistics.

     9 | 0   Scroll up/down the	process	list by	one line.

     ( | )   Scroll up/down the	process	list by	screen half.

     C	     Toggle the	display	of process command line	arguments.

     d count
	     Show only count displays, then exit.

     e	     Display a list of system errors (if any) generated	by the last
	     kill or renice command.

     g|/ string
	     Display only processes that contain string	in their command name.
	     If	displaying of arguments	is enabled, the	arguments are searched
	     too.  `g+'	or `/+'	shows all processes.

     H	     Toggle the	display	of process threads.

     I | i   Toggle the	display	of idle	processes.

     k [-sig] pid
	     Send signal -sig (TERM by default)	to process pid.	 This acts
	     similarly to the command kill(1).

     n|# count
	     Show count	processes.

     o [-]field
	     Sort the process display area using the specified field as	the
	     primary key.  The `-' prefix reverses the order.  Values are the
	     same as for the -o	flag, as detailed above.

     P pid   Highlight a specific process, selected by pid.  `P+' removes
	     process highlighting.

     p pid   Show only the process pid.	 `p+' shows all	processes.

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

     S	     Toggle the	display	of system processes.

     s time  Set the delay between screen updates to time seconds.

     T [-]rtable
	     Display only processes associated with the	specified routing ta-
	     ble rtable.  `T+' shows processes associated with all routing ta-
	     bles.  The	`-' prefix hides processes associated with a single
	     routing table.

     t	     Toggle the	display	of routing tables.

     u [-]user
	     Show only those processes owned by	username or UID	user.  `u+'
	     shows processes belonging to all users.  The `-' prefix hides
	     processes belonging to a single user.

THE DISPLAY
     The top few lines of the display show general information about the state
     of	the system, including the three	load average numbers, the hostname,
     the current time, the number of existing processes, the number of pro-
     cesses in each state (starting, running, idle, stopped, zombie, dead, and
     on	processor), and	a percentage of	time spent in each of the processor
     states (user, nice, system, spinning, interrupt, and idle).  It also in-
     cludes 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 pro-
     cesses.  This display is similar in spirit	to ps(1) but it	is not exactly
     the same.	The following fields are displayed:

	   PID	     The process ID.

	   USERNAME  The name of the process's owner.

	   TID	     The thread	ID, used instead of USERNAME if	-H is speci-
		     fied.

	   UID	     Used instead of USERNAME if -u is specified.

	   PRI	     The current priority of the process.

	   NICE	     The nice amount (in the range -20 to 20).

	   SIZE	     The total size of the process (the	text, data, and	stack
		     segments).

	   RES	     The current amount	of resident memory.

	   STATE     The current state (one of start, run, sleep, stop,	idle,
		     zomb, dead, or onproc).  On multiprocessor	systems, this
		     is	followed by a slash and	the CPU	number on which	the
		     process is	bound.

	   WAIT	     A description of the wait channel the process is sleeping
		     on	if it's	asleep.

	   RTABLE    The routing table,	used instead of	WAIT if	-t is speci-
		     fied.

	   TIME	     The number	of system and user CPU seconds that the
		     process has used.

	   CPU	     The raw percentage	of CPU usage and the default field on
		     which the display is sorted.

	   COMMAND   The name (and arguments if	-C is specified) of the	com-
		     mand that the process is currently	running.

ENVIRONMENT
     TOP	      User-configurable	defaults for options.

FILES
     /dev/kmem	     kernel memory
     /dev/mem	     physical memory
     /etc/passwd     used to map user ID to user
     /bsd	     kernel image

SEE ALSO
     fstat(1), kill(1),	netstat(1), ps(1), stty(1), systat(1), mem(4),
     iostat(8),	pstat(8), renice(8), vmstat(8)

AUTHORS
     William LeFebvre, EECS Department,	Northwestern University

CAVEATS
     As	with ps(1), top	only provides snapshots	of a constantly	changing sys-
     tem.

FreeBSD	13.0			March 12, 2021			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | INTERACTIVE MODE | THE DISPLAY | ENVIRONMENT | FILES | SEE ALSO | AUTHORS | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=top&sektion=1&manpath=OpenBSD+6.9>

home | help