top – display Linux tasks
top -hv | -abcHimMsS -d delay -n
iterations -p pid [, pid ...]
The traditional switches ‘-‘ and whitespace are optional.
The top program provides a dynamic real-time view of a running system.
It can display system summary information as well as a list of
tasks currently being managed by the Linux kernel.
The types of system summary information shown and the types, order and
size of information displayed for tasks are all user configurable and
that configuration can be made persistent across restarts.
The program provides a limited interactive interface for process
manipulation as well as a much more extensive interface for personal
configuration – encompassing every aspect of its operation.
And while top is referred to throughout this document, you are free
to name the program anything you wish.
That new name, possibly an alias, will then be reflected on top’s display
and used when reading and writing a configuration file.
The remaining Table of Contents
1. COMMAND-LINE Options
2. FIELDS / Columns
a. DESCRIPTIONS of Fields
b. SELECTING and ORDERING Columns
3. INTERACTIVE Commands
a. GLOBAL Commands
b. SUMMARY Area Commands
c. TASK Area Commands
d. COLOR Mapping
4. ALTERNATE-DISPLAY Mode
a. WINDOWS Overview
b. COMMANDS for Windows
a. SYSTEM Configuration File
b. PERSONAL Configuration File
6. STUPID TRICKS Sampler
a. Kernel Magic
b. Bouncing Windows
c. The Big Bird Window
7. BUGS, 8. HISTORY Former top, 9. AUTHOR, 10. SEE ALSO
When operating top, the two most important keys are help (‘h’ or ‘?’) and
quit (‘q’) key.
Alternatively, you could simply use the traditional interrupt key (‘^C’)
when you’re done.
When you start top for the first time, you’ll be presented with the
traditional screen elements: 1) Summary Area; 2) Message/Prompt Line;
3) Columns Header; 4) Task Area.
There will, however, be some differences when compared to the former top.
There is no highlighting for load/uptime and only values are highlighted for
Tasks running (or ready to run) will be highlighted, and bold is only one way
of emphasizing such processes.
The program name is shown, perhaps a symlink or alias.
The Cpu(s) state label hints at other possibilities.
The memory stats use a lower case ‘k’.
Will show a new field and some changed labels.
More new fields will be found as you customize your top.
Note: the width of top’s display will be limited to 512 positions.
Displaying all fields requires a minimum of 160 characters.
The remaining width could be used for the ‘Command’ column.
The following startup defaults assume no configuration file, thus no user customizations.
Even so, items shown with an asterisk (‘*’) could be overridden through the
‘A’ – Alt display Off (full-screen)
* ‘d’ – Delay time 3.0 seconds
‘I’ – Irix mode On (no, ‘solaris’ smp)
* ‘p’ – PID monitoring Off
* ‘s’ – Secure mode Off (unsecured)
‘B’ – Bold disable Off
‘l’ – Load Avg/Uptime On (thus program name)
‘t’ – Task/Cpu states On (1+1 lines, see ‘1’)
‘m’ – Mem/Swap usage On (2 lines worth)
‘1’ – Single Cpu On (thus 1 line if smp)
‘b’ – Bold hilite On (not ‘reverse’)
* ‘c’ – Command line Off (name, not cmdline)
* ‘H’ – Threads Off (show all threads)
* ‘i’ – Idle tasks On (show all tasks)
‘R’ – Reverse sort On (pids high-to-low)
* ‘S’ – Cumulative time Off (no, dead children)
‘x’ – Column hilite Off (no, sort field)
‘y’ – Row hilite On (yes, running tasks)
‘z’ – color/mono Off (no, colors)
The command-line syntax for top consists of:
-hv | -abcHimMsS -d delay -n iterations -p pid [,pid...]
The typically mandatory switches (‘-‘) and even whitespace are completely
Fractional seconds are honored, but a negative number is not allowed.
In all cases, however, such changes are prohibited if top is running
in ‘Secure mode’, except for root (unless the ‘s’ command-line option was used).
For additional information on ‘Secure mode’ see topic 5a. SYSTEM Configuration File.
This is a command-line option only.
And should you wish to return to normal operation, it is not necessary
to quit and and restart top – just issue the ‘=’ interactive command.
Listed below are top’s available fields.
They are always associated with the letter shown, regardless of the position
you may have established for them with the ‘o’ (Order fields) interactive command.
Any field is selectable as the sort field, and you control whether they
are sorted high-to-low or low-to-high.
For additional information on sort provisions see topic 3c. TASK Area Commands.
RES = CODE + DATA.
Tasks shown as running should be more properly thought of as ‘ready to run’
– their task_struct is simply represented on the Linux run-queue.
Even without a true SMP machine, you may see numerous tasks in this state
depending on top’s delay interval and nice value.
When you’ve chosen to display command lines, processes without a command
line (like kernel threads) will be shown with only the program name in
parentheses, as in this example:
( mdrecoveryd )
Either form of display is subject to potential truncation if it’s too long to
fit in this field’s current width.
That width depends upon other fields selected, their order and the current
Note: The ‘Command’ field/column is unique, in that it is not fixed-width.
When displayed, this column will be allocated all remaining screen width (up
to the maximum 512 characters) to provide for the potential growth of program
names into command lines.
Note: By displaying this field, top’s own working set will be increased by
Your only means of reducing that overhead will be to stop and restart top.
After pressing the interactive commands ‘f’ (Fields select) or ‘o’ (Order fields) you will
be shown a screen containing the current fields string followed by names
and descriptions for all fields.
Here is a sample fields string from one of top’s four windows/field
groups and an explanation of the conventions used:
Sample fields string:
The order of displayed fields corresponds to the order of the letters
in that string.
If the letter is upper case the corresponding field itself will
then be shown as part of the task display (screen width permitting).
This will also be indicated by a leading asterisk (‘*’), as in this excerpt:
* K: %CPU = CPU usage
l: TIME = CPU Time
m: TIME+ = CPU Time, hundredths
* N: %MEM = Memory usage (RES)
* O: VIRT = Virtual Image (kb)
The summary area fields describing CPU statistics are abbreviated. They provide
information about times spent in:
us = user mode
sy = system mode
ni = low priority user mode (nice)
id = idle task
wa = I/O waiting
hi = servicing IRQs
si = servicing soft IRQs
st = steal (time given to other DomU instances)
Listed below is a brief index of commands within categories.
Some commands appear more than once – their meaning or scope may vary
depending on the context in which they are issued.
<Ret/Sp> ?, =, A, B, d, G, h, I, k, q, r, s, W, Z
l, m, t, 1
Appearance: b, x, y, z
Content: c, f, H, o, S, u
Size: #, i, n
Sorting: <, >, F, O, R
<Ret>, a, B, b, H, M, q, S, T, w, z, 0 – 7
-, _, =, +, A, a, G, g, w
The global interactive commands are always available in both full-screen mode and alternate-display mode.
However, some of these interactive commands are not available when running
in ‘Secure mode’.
If you wish to know in advance whether or not your top has been secured,
simply ask for help and view the system summary on the second line.
Use either of these keys if you have a large delay interval and wish to
see current status,
Typing ‘h’ or ‘?’ on that help screen will take you to help for those interactive commands
applicable to alternate-display mode.
When operating in alternate-display mode this command has a slightly broader meaning.
Note: When this toggle is On and top is operating in monochrome mode,
the entire display will appear as normal text.
Thus, unless the ‘x’ and/or ‘y’ toggles are using reverse for emphasis,
there will be no visual confirmation that they are even on.
Fractional seconds are honored, but a negative number is not allowed.
Entering 0 causes (nearly) continuous updates, with an unsatisfactory
display as the system and tty driver try to keep up with top’s demands.
The delay value is inversely proportional to system loading,
so set it with care.
If at any time you wish to know the current delay time, simply ask for help
and view the system summary on the second line.
If you wish to abort the kill process, do one of the following
depending on your progress:
1) at the pid prompt, just press <Enter>
2) at the signal prompt, type 0
The summary area interactive commands are always available in both full-screen mode and alternate-display mode.
They affect the beginning lines of your display and will determine the position
of messages and prompts.
These commands always impact just the ‘current’ window/field group.
See topic 4. ALTERNATE-DISPLAY Mode and the ‘G’ interactive command for insight into
‘current’ windows and field groups.
When you see ‘Cpu(s):’ in the summary area, the ‘1’ toggle is On and all
cpu information is gathered in a single line.
Otherwise, each cpu is displayed separately as: ‘Cpu0, Cpu1, …’
Note: If the entire summary area has been toggled Off for any window, you would be left
with just the message line.
In that way, you will have maximized available task rows but (temporarily)
sacrificed the program name in full-screen mode or the ‘current’ window name when in alternate-display mode.
The task area interactive commands are always available in full-screen mode.
The task area interactive commands are never available in alternate-display mode if the ‘current’ window’s
task display has been toggled Off (see topic 4. ALTERNATE-DISPLAY Mode).
APPEARANCE of task window
The following commands will also be influenced by the state of the
global ‘B’ (bold disable) toggle.
If you forget which field is being sorted this command can serve as a quick
Use of this provision provides important insight into your system’s health.
The only costs will be a few additional tty escape sequences.
CONTENT of task window
When Off, programs that fork into many separate tasks will appear
For programs like ‘init’ or a shell this is appropriate but for others,
like compilers, perhaps not.
Experiment with two task windows sharing the same sort field but with different ‘S’
states and see which representation you prefer.
After issuing this command, you’ll be informed of the new state of this toggle.
If you wish to know in advance whether or not ‘Cumulative mode’ is in
effect, simply ask for help and view the window summary on the second line.
Later, if you wish to monitor all tasks again, re-issue this command but
just press <Enter> at the prompt, without providing a name.
SIZE of task window
If this command is applied to the last task display when in alternate-display mode, then it will not
affect the window’s size, as all prior task displays will have already been painted.
When used in alternate-display mode, this is the command that gives you precise control over
the size of each currently visible task display, except for the very last.
It will not affect the last window’s size, as all prior task displays will have
already been painted.
Note: If you wish to increase the size of the last visible task display when in alternate-display mode,
simply decrease the size of the task display(s) above it.
SORTING of task window
For compatibility, this top supports most of the former top sort keys.
Since this is primarily a service to former top users, these commands do
not appear on any help screen.
command sorted field supported
A start time (non-display) No
M %MEM Yes
N PID Yes
P %CPU Yes
T TIME+ Yes
Before using any of the following sort provisions, top suggests that you
temporarily turn on column highlighting using the ‘x’ interactive command.
That will help ensure that the actual sort environment matches your intent.
The following interactive commands will only be honored when the
current sort field is visible.
The sort field might not be visible because:
1) there is insufficient Screen Width
2) the ‘f’ interactive command turned it Off
The following interactive commands will always be honored whether or not
the current sort field is visible.
If a field is selected which was not previously being displayed, it will
be forced On when you return to the top display.
However, depending upon your screen width and the order of your fields,
this sort field may not be displayable.
This interactive command can be a convenient way to simply verify the current sort field,
when running top with column highlighting turned Off.
Note: Field sorting uses internal values, not those in column display.
Thus, the TTY and WCHAN fields will violate strict ASCII collating sequence.
When you issue the ‘Z’ interactive command, you will be presented with a separate screen.
That screen can be used to change the colors in just the ‘current’ window or
in all four windows before returning to the top display.
Available interactive commands
4 upper case letters to select a target
8 numbers to select a color
normal toggles available
‘B’ :bold disable/enable
‘b’ :running tasks "bold"/reverse
other commands available
‘a’/’w’ :apply, then go to next/prior
<Enter> :apply and exit
‘q’ :abandon current changes and exit
If your use ‘a’ or ‘w’ to cycle the targeted window, you will
have applied the color scheme that was displayed when you left that window.
You can, of course, easily return to any window and reapply different
colors or turn colors Off completely with the ‘z’ toggle.
The Color Mapping screen can also be used to change the ‘current’ window/field group
in either full-screen mode or alternate-display mode.
Whatever was targeted when ‘q’ or <Enter> was pressed will be made current
as you return to the top display.
In full-screen mode there is a single window represented by the entire screen.
That single window can still be changed to display 1 of 4 different field
groups (see the ‘G’ interactive command, repeated below).
Each of the 4 field groups has a unique separately configurable summary area
and its own configurable task area.
In alternate-display mode, those 4 underlying field groups can now be made visible
simultaneously, or can be turned Off individually at your command.
The summary area will always exist, even if it’s only the message line.
At any given time only one summary area can be displayed.
However, depending on your commands, there could be from zero
to four separate task displays currently showing on the screen.
The ‘current’ window is the window associated with the summary area and the window to which
task related commands are always directed.
Since in alternate-display mode you can toggle the task display Off, some commands might be
restricted for the ‘current’ window.
A further complication arises when you have toggled the first summary area
With the loss of the window name (the ‘l’ toggled line), you’ll not easily
know what window is the ‘current’ window.
The ‘_’ key does the same for all task displays.
In other words, it switches between the currently visible task display(s) and any
task display(s) you had toggled Off.
If all 4 task displays are currently visible, this interactive command will leave the summary area
as the only display element.
The ‘+’ key does the same for all windows.
The four task displays will reappear, evenly balanced.
They will also have retained any customizations you had previously applied,
except for the ‘i’ (idle tasks) and ‘n’ (max tasks) commands.
The first time you issue this command, all four task displays will be shown.
Thereafter when you switch modes, you will see only the task display(s) you’ve
chosen to make visible.
Assuming the window name is visible (you have not toggled ‘l’ Off),
whenever the ‘current’ window name loses its emphasis/color, that’s a reminder
the task display is Off and many commands will be restricted.
In full-screen mode, this command is necessary to alter the ‘current’ window.
In alternate-display mode, it is simply a less convenient alternative to the ‘a’ and ‘w’
The presence of this file will influence which version of the ‘help’ screen
is shown to an ordinary user.
More importantly, it will limit what ordinary users are allowed
to do when top is running.
They will not be able to issue the following commands.
k Kill a task
r Renice a task
d or s Change delay/sleep interval
The system configuration file is not created by top.
Rather, you create this file manually and place it in the /etc
Its name must be ‘toprc’ and must have no leading ‘.’ (period).
It must have only two lines.
Here is an example of the contents of /etc/toprc:
s # line 1: ‘secure’ mode switch
5.0 # line 2: ‘delay’ interval in seconds
This file is written as ‘$HOME/.your-name-4-top’ + ‘rc’.
Use the ‘W’ interactive command to create it or update it.
Here is the general layout:
global # line 1: the program name/alias notation
" # line 2: id,altscr,irixps,delay,curwin
per ea # line a: winname,fieldscur
window # line b: winflags,sortindx,maxtasks
" # line c: summclr,msgsclr,headclr,taskclr
If the $HOME variable is not present, top will try to write the
personal configuration file to the current directory, subject to permissions.
Many of these ‘tricks’ work best when you give top a scheduling boost.
So plan on starting him with a nice value of -10, assuming you’ve got
For these stupid tricks, top needs full-screen mode.
The user interface, through prompts and help, intentionally implies
that the delay interval is limited to tenths of a second.
However, you’re free to set any desired delay.
If you want to see Linux at his scheduling best, try a delay of .09
seconds or less.
For this experiment, under x-windows open an xterm and maximize it.
Then do the following:
. provide a scheduling boost and tiny delay via:
nice -n -10 top -d.09
. keep sorted column highlighting Off to minimize
. turn On reverse row highlighting for emphasis
. try various sort columns (TIME/MEM work well),
and normal or reverse sorts to bring the most
active processes into view
What you’ll see is a very busy Linux doing what he’s always done for you,
but there was no program available to illustrate this.
Under an xterm using ‘white-on-black’ colors, try setting top’s task color
to black and be sure that task highlighting is set to bold, not reverse.
Then set the delay interval to around .3 seconds.
After bringing the most active processes into view, what you’ll see are
the ghostly images of just the currently running tasks.
Delete the existing rcfile, or create a new symlink.
Start this new version then type ‘T’ (a secret key, see topic 3c. TASK Area
Commands, Sorting) followed by ‘W’ and ‘q’.
Finally, restart the program with -d0 (zero delay).
Your display will be refreshed at three times the rate of the former top,
a 300% speed advantage.
As top climbs the TIME ladder, be as patient as you can while speculating
on whether or not top will ever reach the top.
For these stupid tricks, top needs alternate-display mode.
With 3 or 4 task displays visible, pick any window other than the last
and turn idle processes Off.
Depending on where you applied ‘i’, sometimes several task displays are bouncing and
sometimes it’s like an accordion, as top tries his best to allocate space.
Set each window’s summary lines differently: one with no memory; another with
no states; maybe one with nothing at all, just the message line.
Then hold down ‘a’ or ‘w’ and watch a variation on bouncing windows –
Display all 4 windows and for each, in turn, set idle processes to Off.
You’ve just entered the "extreme bounce" zone.
This stupid trick also requires alternate-display mode.
Display all 4 windows and make sure that 1:Def is the ‘current’ window.
Then, keep increasing window size until the all the other task displays
are "pushed out of the nest".
When they’ve all been displaced, toggle between all visible/invisible windows.
Then ponder this:
is top fibbing or telling honestly your imposed truth?
Send bug reports to:
Albert D. Cahalan, <[email protected]>
The top command calculates Cpu(s) by looking at the change in CPU time values
between samples. When you first run it, it has no previous sample to compare
to, so these initial values are the percentages since boot. It means you need
at least two loops or you have to ignore summary output from the first loop.
This is problem for example for batch mode. There is a possible workaround if
you define the CPULOOP=1 environment variable. The top command will be run one
extra hidden loop for CPU data before standard output.
The original top was written by Roger Binns,
based on Branko Lankester’s <[email protected]> ps program.
Robert Nation <[email protected]>
adapted it for the proc file system.
Helmut Geyer <[email protected]>
added support for configurable fields.
Plus many other individuals contributed over the years.
This entirely new and enhanced replacement was written by:
Jim / James C. Warner, <[email protected]>