On Unix-like operating systems, the top program provides a dynamic real-time view of a running system. It can display system summary information, and a list of processes or threads currently being managed by the kernel. The types of system summary information shown and the types, order and size of information displayed for tasks are all user-configurable.

This page covers the Linux version of top.

Syntax

top -hv | -bcHisS -d delay -n limit -u|U user | -p pid -w [cols]

Options

Summary display

Each of the following areas are individually controlled through interactive commands.

  • Syntax
  • Options
  • Summary display
  • Fields / columns
  • Interactive commands
  • Summary area commands
  • Task area commands
  • Alternate-display provisions: Microsoft Windows
  • Commands for windows
  • Scrolling a window
  • Searching in a window
  • Files
  • Tips and tricks
  • Related commands
  • Linux commands help

The often mandatory switches (’-’) and even whitespace are completely optional.

Uptime and Load Averages

This section consists of a single line displaying the following:

  • program or window name, depending on display mode
  • current time and length of time since last boot
  • total number of users
  • system load avg over the last 1, 5 and 15 minutes

Task and CPU States

This section consists of a minimum of two lines. In an SMP environment, additional lines can reflect individual CPU state percentages.

  • Line 1 shows total tasks or threads, depending on the state of the Threads-mode toggle. That total is further classified as: running; sleeping; stopped; zombie
  • Line 2 shows CPU state percentages based on the interval since the last refresh. Where two labels are shown below, those for more recent kernel versions are shown first:us, user : time running un-niced user processessy, system : time running kernel processesni, nice : time running niced user processeswa, IO-wait : time waiting for I/O completionhi : time spent servicing hardware interruptssi : time spent servicing software interruptsst : time stolen from this vm by the hypervisor

Memory Usage

This portion consists of two lines which may express values in kibibytes (KiB), mebibytes (MiB) or gibibytes (GiB) depending on the amount of physical memory.

  • Line 1 reflects physical memory, classified as: total, used, free, buffers
  • Line 2 reflects virtual memory, classified as: total, used, free, cached

Fields / columns

Listed below are top’s available process fields (columns). They are shown in alphabetical order. You may customize their position and whether or not they are displayable with the ‘f’ or ‘F’ (Fields Management) interactive commands.

Any field is selectable as the sort field, and you control whether they are sorted high-to-low or low-to-high.

CGROUPS – Control Groups

The names of the control group(s) that a process belongs to, or ‘-’ if not applicable for that process.

Control Groups provide for allocating resources (cpu, memory, network bandwidth, etc.) among installation-defined groups of processes. They enable fine-grained control over allocating, denying, prioritizing, managing and monitoring those resources.

Many different hierarchies of “cgroups” can exist simultaneously on a system and each hierarchy is attached to one or more subsystems. A subsystem represents a single resource.

  • CODE – Code Size (KiB). The amount of physical memory devoted to executable code, also known as the ’text resident set’ size or TRS.
  • COMMAND – Command Name or Command Line. Display the command line used to start a task or the name of the associated program. You toggle between command line and name with ‘c’, which is both a command-line option and an interactive command. When you’ve chosen to display command lines, processes without a command line (like kernel threads) are shown with only the program name in brackets (for example: “[ mrecoveryd ]”). 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 screen width. This field may also be impacted by the ‘forest view’ display mode. See the ‘V’ interactive command for additional information regarding that mode. Note: The ‘COMMAND’ field, unlike most columns, is not fixed-width. When displayed, it and any other variable width columns are allocated all remaining screen width (up to the maximum 512 characters).
  • %CPU – CPU Usage. The task’s share of the elapsed CPU time since the last screen update, expressed as a percentage of total CPU time. In a true SMP environment, if ‘IRIX mode’ is Off, top operates in ‘Solaris mode’ where a task’s cpu usage is divided by the total number of CPUs. You toggle ‘IRIX/Solaris’ modes with the ‘I’ interactive command.
  • DATA – Data + Stack Size (KiB). The amount of physical memory devoted to other than executable code, also known as the ‘data resident set’ size or DRS.
  • Flags – Task Flags. This column represents the task’s current scheduling flags that are expressed in hexadecimal notation and with zeros suppressed. These flags are officially documented in <linux/sched.h>.
  • GID – Group Id. The effective group ID.
  • GROUP – Group Name. The effective group name.
  • %MEM – Memory Usage (RES). A task’s currently used share of available physical memory.
  • NI – Nice Value. The nice value of the task. A negative nice value means higher priority, whereas a positive nice value means lower priority. Zero in this field means priority is not adjusted in determining a task’s dispatchability.
  • nDRT – Dirty Pages Count. The number of pages that were modified since they were last written to auxiliary storage. Dirty pages must be written to auxiliary storage before the corresponding physical memory location can be used for some other virtual page.
  • nMaj – Major Page Fault Count. The number of major page faults that have occurred for a task. A page fault occurs when a process attempts to read from or write to a virtual page that is not currently present in its address space. A major page fault is when auxiliary storage access is involved in making that page available.
  • nMin – Minor Page Fault count. The number of minor page faults that have occurred for a task. A page fault occurs when a process attempts to read from or write to a virtual page that is not currently present in its address space. A minor page fault does not involve auxiliary storage access in making that page available.
  • nTH – Number of Threads. The number of threads associated with a process.
  • P – Last used CPU (SMP). A number representing the last used processor. In a true SMP environment, this likely changes frequently since the kernel intentionally uses weak affinity. Also, the very act of running top may break this weak affinity and cause more processes to change CPUs more often (because of the extra demand for cpu time).
  • PGRP – Process Group Id. Every process is member of a unique process group that is used for distribution of signals and by terminals to arbitrate requests for their input and output. When a process is created (forked), it becomes a member of the process group of its parent. By convention, this value equals the process ID (see PID) of the first member of a process group, called the process group leader.
  • PID – Process Id. The task’s unique process ID, which periodically wraps, though never restarting at zero. In kernel terms, it is a dispatchable entity defined by a ’task_struct’. This value may also be used as: a process group ID (see PGRP); a session ID for the session leader (see SID); a thread group ID for the thread group leader (see TGID); and a TTY process group ID for the process group leader (see TPGID).
  • PPID – Parent Process Id. The process ID (pid) of a task’s parent.
  • PR – Priority. The scheduling priority of the task. If you see ‘rt’ in this field, it means the task is running under ‘real time’ scheduling priority. Under linux, real time priority is somewhat misleading since traditionally the operating itself was not preemptable. And while the 2.6 kernel can be made mostly preemptable, it is not always so.
  • RES – Resident Memory Size (KiB). The non-swapped physical memory a task has used.
  • RUID – Real User Id.
  • RUSER – Real Username.
  • S – Process Status. The status of the task which can be one of: ‘D’ = uninterruptible sleep ‘R’ = running ‘S’ = sleeping ‘T’ = traced or stopped ‘Z’ = zombie Tasks shown as running should be more properly thought of as ‘ready to run’ – their task_struct is 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.
  • SHR – Shared Memory Size (KiB). The amount of shared memory available to a task, that often is not all resident. It reflects memory that could be potentially shared with other processes.
  • SID – Session Id. A session is a collection of process groups (see PGRP), usually established by the login shell. A newly forked process joins the session of its creator. By convention, this value equals the process ID (see PID) of the first member of the session, called the session leader, which is usually the login shell.
  • SUID – Saved User Id. The saved user ID.
  • SUPGIDS – Supplementary Group IDs. The IDs of any supplementary group(s) established at login or inherited from a task’s parent. They are displayed in a comma delimited list. Note: The ‘SUPGIDS’ field, unlike most columns, is not fixed-width. When displayed, it and any other variable width columns are allocated all remaining screen width (up to the maximum 512 characters).
  • SUPGRPS – Supplementary Group Names. The names of any supplementary group(s) established at login or inherited from a task’s parent. They are displayed in a comma delimited list. Note: The ‘SUPGRPS’ field, unlike most columns, is not fixed-width. When displayed, it and any other variable width columns are allocated all remaining screen width (up to the maximum 512 characters).
  • SUSER – Saved Username. The saved username.
  • SWAP – Swapped Size (KiB). The non-resident portion of a task’s address space.
  • TGID – Thread Group Id. The ID of the thread group that a task belongs. It is the PID of the thread group leader. In kernel terms, it represents those tasks that share an ‘mm_struct’.
  • TIME – CPU Time. Total CPU time the task has used since it started. When ‘Cumulative mode’ is On, each process is listed with the cpu time that it and its dead children have used. You toggle ‘Cumulative mode’ with ‘S’, which is both a command-line option and an interactive command. See the ‘S’ interactive command for additional information regarding this mode.
  • TIME+ – CPU Time (hundredths). The same as ‘TIME’, but reflecting more granularity through hundredths of a second.
  • TPGID – Tty Process Group Id. The process group ID of the foreground process for the connected tty, or -1 if a process is not connected to a terminal. By convention, this value equals the process ID (see PID) of the process group leader (see PGRP).
  • TTY – Controlling Tty. The name of the controlling terminal. The TTY is usually the device (serial port, pty, etc.) from which the process was started, and which it uses for input or output. However, a task need not be associated with a terminal, in which case you’ll see ‘?’ displayed.
  • UID – User Id. The effective user ID of the task’s owner.
  • USER – Username. The effective username of the task’s owner.
  • VIRT – Virtual Memory Size (KiB). The total amount of virtual memory used by the task. It includes all code, data and shared libraries plus pages that were swapped out and pages that were mapped but not used.
  • WCHAN – Sleeping in Function. Depending on the availability of the kernel link map (‘System.map’), this field shows the name or the address of the kernel function in which the task is currently sleeping. Running tasks displays a dash (’-’) in this column. By displaying this field, top’s own working set could be increased by over 700 Kb, depending on the kernel version. Should that occur, your only means of reducing that overhead is to stop and restart top. Note: The ‘WCHAN’ field, unlike most columns, is not fixed-width. When displayed, it and any other variable width columns are allocated all remaining screen width (up to the maximum 512 characters).

Managing fields

After pressing the interactive command ‘f’ or ‘F’ (Fields Management), you are presented with a screen showing: 1) the current window name; 2) the designated sort field; 3) all fields in their current order with descriptions. Entries marked with an asterisk are the currently displayed fields, screen width permitting.

The ‘CGROUPS’ field, unlike most columns, is not fixed-width. When displayed, it and any other variable width columns are allocated all remaining screen width (up to the maximum 512 characters).

  • As the on-screen instructions indicate, you navigate among the fields with the Up and Down arrow keys. The PgUp, PgDn, Home and End keys can also be used to quickly reach the first or last available field.
  • The Right arrow key selects a field for repositioning and the Left arrow key or the key commits that field’s placement.
  • The ’d’ key or the bar toggles a field’s display status, and thus the presence or absence of the asterisk.
  • The ’s’ key designates a field as the sort field. See topic 4c. TASK AREA Commands, SORTING for additional information regarding your selection of a sort field.
  • The ‘a’ and ‘w’ keys can cycle through all available windows and the ‘q’ or keys exit Fields Management.

The Fields Management 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 was pressed is made current as you return to the top display. See topic 5. ALTERNATE-DISPLAY Provisions and the ‘g’ interactive command for insight into current windows and field groups.

Interactive commands

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.

Any window that was scrolled horizontally is reset if any field changes are made via the Fields Management screen. Any vertical scrolled position, however, is not affected. See topic 5c. SCROLLING a Window for additional information regarding vertical and horizontal scrolling.

Global commands

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 want to know in advance whether or not your top was secured, ask for help and view the system summary on the second line.

  • The commands shown with an asterisk (*) are not available in ‘Secure mode’, nor are they shown on the level-1 help screen.

Summary area commands

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 determine the position of messages and prompts.

These commands always only impact the current window/field group. See topic 5. ALTERNATE-DISPLAY Provisions and the ‘g’ interactive command for insight into current windows and field groups.

Task area commands

The task area interactive commands are always available in full-screen mode.

If the entire summary area is toggled off for any window, you are left with the message line. In that way, you have maximized available task rows, but (temporarily) sacrifice the program name in full-screen mode or the current window name when in alternate-display mode.

The task area interactive commands are never available in alternate-display mode if the current window’s task display is toggled Off (see topic 5. ALTERNATE-DISPLAY Provisions).

Appearance of task window

The following commands are also influenced by the state of the global ‘B’ (bold enable) toggle.

Content of task window

Size of task window

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.

Typing any key affecting the sort order exits forest view mode in the current window. See topic 4c. TASK AREA Commands, SORTING for information on those keys.

If you want to increase the size of the last visible task display when in alternate-display mode, decrease the size of the task display(s) above it.

Before using any of the following sort provisions, top suggests you temporarily turn on column highlighting using the ‘x’ interactive command. That helps ensure that the actual sort environment matches your intent.

The following interactive commands are only 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 are always honored whether or not the current sort field is visible.

Alternate-display provisions: Microsoft Windows

Field groups/windows

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.

Field sorting uses internal values, not those in column display. Thus, the TTY and WCHAN fields violate strict ASCII collating sequence.

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 always exists, 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.

Current window

The current window is the window associated with the summary area and the window that 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 line Off. With the loss of the window name (the ’l’ toggled line), you do not easily know what window is the current window.

Commands for windows

  • The interactive commands shown with an asterisk (*) have use beyond alternate-display mode.

‘=’, ‘A’, ‘g’ are always available.’

‘a’, ‘w’ act the same with color mapping and fields management.

Scrolling a window

A task window is often a partial view into a systems’s total tasks/threads which shows only some of the available fields/columns. With these scrolling keys, you can move that view vertically or horizontally to reveal any desired task or column.

The interactive commands above are always available in full-screen mode, but never available in alternate-display mode if the current window’s task display is toggled Off.

Searching in a window

You can use these interactive commands to locate a task row containing a particular value.

Files

System configuration file

The presence of this file influences which version of the ‘help’ screen is shown to an ordinary user. More importantly, it limits what ordinary users are allowed to do when top is running. They are not able to issue the following commands.

Whenever a search key is typed, top forces idle tasks On and user filtering Off to ensure that every task is encountered. See the ‘i’ and ‘u/U’ interactive commands for additional information on how displayed tasks might be filtered.

The system configuration file is not created by top. Rather, you create this file manually and place it in the /etc directory. 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

Personal configuration file

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 global # line 2: id,altscr,irixps,delay,curwin per ea # line a: winname,fieldscur window # line b: winflags,sortindx,maxtasks window # line c: summclr,msgsclr,headclr,taskclr

If the $HOME variable is not present, top tries to write the personal configuration file to the current directory, subject to permissions.

Tips and tricks

Many of these ’tricks’ work best when you give top a scheduling boost. So plan on starting it with a nice value of -10, assuming you’ve got the authority.

Kernel magic

For these 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 are 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: 1. Provide a scheduling boost and tiny delay via:nice -n -10 top -d.09. 2. Keep sorted column highlighting Off so as to minimize path length. 3. Turn On reverse row highlighting for emphasis. 4. Try various sort columns (TIME/MEM work well), and normal or reverse sorts to bring the most active processes into view. What you see is a very busy Linux doing what it’s always done for you, but there was no program available to illustrate this.
  • Under an xterm using ‘white-on-black’ colors, on top’s Color Mapping screen set the 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 see are the ghostly images of only 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 4c. Task Area Commands, SORTING) followed by ‘W’ and ‘q’. Finally, restart the program with -d0 (zero delay). Your display is 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 ever reaches the top.

Bouncing windows

For these 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 using the ‘i’ command toggle. 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 (’m’); another with no states (’t’); maybe one with nothing at all, only the message line. Then hold down ‘a’ or ‘w’ and watch a variation on bouncing windows – hopping windows.
  • Display all 4 windows and for each, in turn, set idle processes to Off using the ‘i’ command toggle. You have entered the “extreme bounce” zone.

The big bird window

This 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 with the ’n’ interactive command until all the other task displays are “pushed out of the nest.” When they all are displaced, toggle between all visible/invisible windows using the ‘_’ command toggle. It’s a truly mind-bending experience.

free — Display the amount of free and used memory.ps — Report the status of a process or processes.pstree — Display processes in a tree format.uptime — Displays running time information for the system.