top(1)

NAME

top - display top CPU processes

SYNOPSIS

top [ - ] [ d delay ] [ q ] [ S ] [ s ] [ i ] [ -V ]

DESCRIPTION

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.

COMMAND-LINE OPTIONS

d

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

q

This causes top to refresh without any delay. If the caller has superuser priviledges, 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 interactive command i below.

V

Display version information.

FIELD DESCRIPTIONS

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.

uptime

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 minutes. This line is just like the output of uptime (1).

processes

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.

CPU states

Shows the percentage of CPU time in user mode, system mode, niced tasks, and idle. (Niced tasks are only those whose nice value is negative.) Time spent in niced tasks will also be counted in system and user time, so the total will be more than 100%.

Mem

Statistics on memory usage, including total available memory, free memory, used memory, shared memory, and memory used for buffers.

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.

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

SIZE

The size of the task's code plus data plus stack space, in kilobytes, is shown here.

RSS

The total amount of physical memory used by the task, in kilobytes, is shown here.

SHRD

The amount of shared memory used by the task is shown in this column.

ST

The state of the task is shown here. The state is either S for sleeping, D for uninterruptible sleep, R for running, Z for zombies, or T for stopped or traced.

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 .

%CPU

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

%MEM

The task's share of the physical memory.

COMMAND

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

INTERACTIVE COMMANDS

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

^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 signal, as with kill (1), is 15, SIGTERM . This command is not available in secure mode.

i

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

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

NOTES

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 expensive, possibly prohibitively so. In any case, that would make top 's behavior incompatible with ps .

SEE ALSO

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

BUGS If the window is less than about 70x7, top will not format information correctly.

AUTHOR

top was originally written by Roger Binns, based on Branko Lankester's (lankeste@fwi.uva.nl) ps program. Robert Nation (nation@rocket.sanders.lockheed.com) re-wrote it significantly to use the proc filesystem, based on Michael K Johnson's (johnsonm@sunsite.unc.edu) proc-based ps program. Many changes were made, including secure and cumulative modes and a general cleanup, by Michael Shields (mjshield@nyx.cs.du.edu).