5 .TH TOP 1 "December 20, 2009"
7 top \- display and update information about the top cpu processes
26 .\" This defines appropriate quote strings for nroff and troff
31 .\" Just in case these number registers aren't set yet...
37 processes on the system and periodically updates this information.
40 If standard output is an intelligent terminal (see below) then
41 as many processes as will fit on the terminal screen are displayed
42 by default. Otherwise, a good number of them are shown (around 20).
44 Raw cpu percentage is used to rank the processes. If
46 is given, then the top
48 processes will be displayed instead of the default.
51 makes a distinction between terminals that support advanced capabilities
52 and those that do not. This
53 distinction affects the choice of defaults for certain options. In the
54 remainder of this document, an \*(lqintelligent\*(rq terminal is one that
55 supports cursor addressing, clear screen, and clear to end of line.
56 Conversely, a \*(lqdumb\*(rq terminal is one that does not support such
57 features. If the output of
59 is redirected to a file, it acts as if it were being run on a dumb
62 .if \nL==0 Long options are not available on this system.
65 Turn off the use of color in the display.
67 .B "\-I, \-\-idle-procs"
68 Do not display idle processes.
69 By default, top displays both active and idle processes.
72 Enable multi-CPU display.
74 .B "\-S, \-\-system-procs"
75 Show system processes in the display. Normally, system processes such as
76 the pager and the swapper are not shown. This option makes them visible.
78 .B "\-T, \-\-tag-names"
79 List all available color tags and the current set of tests used for
80 color highlighting, then exit.
83 Show all processes for as long as possible. This is shorthand for
84 \*(lq-d all all\*(rq. This option is especially handy in batch mode.
86 .B "\-b, \-n, \-\-batch"
87 Use \*(lqbatch\*(rq mode. In this mode, all input from the terminal is
88 ignored. Interrupt characters (such as ^C and ^\e) still have an effect.
89 This is the default on a dumb terminal, or when the output is not a terminal.
91 .B "\-c, \-\-full-commands"
92 Show the full command line for each process. Default is to show just the
93 command name. This option is not supported on all platforms.
95 .B "\-i, \-\-interactive"
96 Use \*(lqinteractive\*(rq mode. In this mode, any input is immediately
97 read for processing. See the section on \*(lqInteractive Mode\*(rq
99 which keys perform what functions. After the command is processed, the
100 screen will immediately be updated, even if the command was not
101 understood. This mode is the default when standard output is an
102 intelligent terminal.
107 to -20 so that it will run faster. This can be used when the system is
108 being very sluggish to improve the possibility of discovering the problem.
109 This option can only be used by root.
111 .B "\-t, \-\-threads"
112 Show individual threads on separate lines. By default, on systems
113 which support threading, each process is shown with a count of the number
114 of threads. This option shows each thread on a separate line. This option
115 is not supported on all platforms.
118 Do not take the time to map uid numbers to usernames. Normally,
120 will read as much of the file \*(lq/etc/passwd\*(rq as is necessary to map
121 all the user id numbers it encounters into login names. This option
122 disables all that, while possibly decreasing execution time. The uid
123 numbers are displayed instead of the names.
125 .B "\-v, \-\-version"
126 Write version number information to stderr then exit immediately.
127 No other processing takes place when this option is used. To see current
128 revision information while top is running, use the help command \*(lq?\*(rq.
130 .B "\-d \fIcount\fP, \-\-displays \fIcount\fP"
133 displays, then exit. A display is considered to be one update of the
134 screen. This option allows the user to select the number of displays he
137 automatically exits. Any proper prefix of the words \*(lqinfinity\*(rq,
140 \*(lqall\*(rq can be used to indicate an infinite number of displays.
141 The default for intelligent terminals is infinity.
142 The default for dumb terminals is 1.
144 .B "\-m \fImode\fP, \-\-mode=\fImode\fP"
145 Start the display in an alternate mode. Some platforms support multiple
146 process displays to show additional process information. The value
147 \fImode\fP is a number indicating which mode to display. The default is
148 0. On platforms that do not have multiple display modes this option has
151 .B "\-o \fIfield\fP, \-\-sort-order=\fIfield\fP"
152 Sort the process display area on the specified field. The field name is
153 the name of the column as seen in the output, but in lower case. Likely
154 values are \*(lqcpu\*(rq, \*(lqsize\*(rq, \*(lqres\*(rq, and \*(lqtime\*(rq,
155 but may vary on different operating systems. Note that
156 not all operating systems support this option.
158 .B "\-s \fItime\fP, \-\-delay=\fItime\fP"
159 Set the delay between screen updates to
161 seconds. The default delay between updates is \nD seconds.
163 .B "\-U \fIusername\fP, \-\-user=\fIusername\fP"
164 Show only those processes owned by
166 This option currently only accepts usernames and will not understand
173 fields can be specified as \*(lqinfinite\*(rq, indicating that they can
174 stretch as far as possible. This is accomplished by using any proper
175 prefix of the keywords
182 on an intelligent terminal is, in fact,
185 The environment variable
187 is examined for options before the command line is scanned. This enables
188 a user to set his or her own defaults. The number of processes to display
189 can also be specified in the environment variable
197 are actually toggles. A second specification of any of these options
198 will negate the first. Thus a user who has the environment variable
200 set to \*(lq\-I\*(rq may use the command \*(lqtop \-I\*(rq to see idle processes.
201 .SH "INTERACTIVE MODE"
204 is running in \*(lqinteractive mode\*(rq, it reads commands from the
205 terminal and acts upon them accordingly. In this mode, the terminal is
206 put in \*(lqCBREAK\*(rq, so that a character will be
207 processed as soon as it is typed. Almost always, a key will be
210 is between displays; that is, while it is waiting for
212 seconds to elapse. If this is the case, the command will be
213 processed and the display will be updated immediately thereafter
214 (reflecting any changes that the command may have specified). This
215 happens even if the command was incorrect. If a key is pressed while
217 is in the middle of updating the display, it will finish the update and
218 then process the command. Some commands require additional information,
219 and the user will be prompted accordingly. While typing this information
220 in, the user's erase and kill keys (as set up by the command
222 are recognized, and a newline terminates the input. Note that a control-L
223 (^L) always redraws the current screen and a space forces an immediate
224 update to the screen using new data.
226 These commands are currently recognized:
228 .I "\fBh\fP\ or\ \fB?\fP"
229 Display a summary of the commands (help screen). Version information
230 is included in this display.
233 Toggle the use of color in the display.
236 Display only processes whose commands match the specified string. An empty
237 string will display all processes. This command is not supported on all
241 Change the number of displays to show (prompt for new number).
242 Remember that the next display counts as one, so typing
246 show one final display and then immediately exit.
249 Toggle the display of the full command line.
252 Toggle the display of threads on separate lines. By default, on systems
253 which support threading, each process is shown with a count of the number
254 of threads. This command shows each thread on a separate line. This command
255 is not supported on all platforms.
260 Toggle the display of idle processes.
264 Send a signal (\*(lqkill\*(rq by default) to a list of processes. This
265 acts similarly to the command
270 Sort display by memory usage. Shorthand for \*(lqo size\*(rq.
273 Change to a different process display mode. Some systems provide multiple
274 display modes for the process display which shows different information.
275 This command toggles between the available modes. This command is not
276 supported on all platforms.
279 Sort by process id. Shorthand for \*(lqo pid\*(rq.
282 Change the number of processes to display (prompt for new number).
285 Change the order in which the display is sorted. This command is not
286 available on all systems. The sort key names vary fron system to system
287 but usually include: \*(lqcpu\*(rq, \*(lqres\*(rq, \*(lqsize\*(rq,
288 \*(lqtime\*(rq. The default is cpu.
291 Sort by CPU usage. Shorthand for \*(lqo cpu\*(rq.
299 Change the priority (the \*(lqnice\*(rq) of a list of processes.
300 This acts similarly to the command
305 Change the number of seconds to delay between displays
306 (prompt for new number).
309 Sort by CPU time. Shorthand for \*(lqo time\*(rq.
312 Toggle between displaying usernames and uids.
315 Display only processes owned by a specific username (prompt for username).
316 If the username specified is simply \*(lq+\*(rq, then processes belonging
317 to all users will be displayed.
319 The actual display varies depending on the specific variant of Unix
320 that the machine is running. This description may not exactly match
321 what is seen by top running on this particular machine. Differences
322 are listed at the end of this manual entry.
324 The top lines of the display show general information
325 about the state of the system. The first line shows
326 (on some systems) the last process id assigned to a process,
327 the three load averages,
328 the system uptime, and the current time.
329 The second line displays the total number of processes followed
330 by a breakdown of processes per state. Examples of states common
331 to Unix systems are sleeping, running, starting, stopped, and zombie.
332 The next line displays a percentage of time spent in each of the
333 processor states (typically user, nice, system, idle, and iowait).
334 These percentages show the processor activity during the time since
335 the last update. For multi-processor systems, this information is
336 a summation of time across all processors. The next line shows
337 kernel-related activity (not available on all systems). The numbers
338 shown on this line are per-second rates sampled since the last update.
340 information displayed varies between systems, but some examples are:
341 context switches, interrupts, traps, forks, and page faults.
344 two lines show a summary of memory and swap activity. The fields are
348 number of pages active
351 number of pages inactive
354 number of pages wired down, including cached file data pages
357 number of pages used for VM-level disk caching
360 number of pages used for BIO-level disk caching
366 total available swap usage
369 total free swap usage
375 pages paged in from swap devices (last interval)
378 pages paged out to swap devices (last interval)
389 The remainder of the screen displays information about individual
390 processes. This display is similar in spirit to
392 but it is not exactly the same. The columns displayed by top will
393 differ slightly between operating systems. Generally, the following
394 fields are displayed:
400 Username of the process's owner (if
402 is specified, a UID column will be substituted for USERNAME).
405 The number of threads in the processes (this column may also
409 Current priority of the process.
412 Nice amount in the range \-20 to 20, as established by the use of
417 Total size of the process (text, data, and stack) given in kilobytes.
420 Resident memory: current amount of process memory that resides in physical
421 memory, given in kilobytes.
424 Current state (typically one of \*(lqsleep\*(rq,
425 \*(lqrun\*(rq, \*(lqidl\*(rq, \*(lqzomb\*(rq, or \*(lqstop\*(rq).
428 Number of CPU the process is currently running on (only on multi-CPU machines).
431 Number of system and user cpu seconds that the process has used.
434 The cumulated CPU time of the process and its exited children. This value
437 displays as CPU time when run with the
442 Percentage of available cpu time used by this process.
445 Name of the command that the process is currently running.
447 Top supports the use of ANSI color in its output. By default, color is
448 available but not used. The environment variable
450 specifies colors to use and conditions for which they should be used.
451 At the present time, only numbers in the summay display area can be
452 colored. In a future version it will be possible to highlight numbers
453 in the process display area as well. The environment variable is the
454 only way to specify color: there is no equivalent command line option.
455 Note that the environment variable
457 is also understood. The British spelling takes precedence. The use of
458 color only works on terminals that understand and process ANSI color
461 The environment variable is a sequence of color specifications, separated
462 by colons. Each specification takes the form tag=min,max#code where
464 is the name of the value to check,
468 specify a range for the value, and
470 is an ANSI color code. Multiple color codes can be listed and separated
471 with semi-colons. A missing
473 implies the lowest possible value (usually 0)
476 implies infinity. The comma must always be present. When specifying numbers
477 for load averages, they should be multiplied by 100.
478 For example, the specification
480 indicates that a 1 minute load average between
481 5 and 10 should be displayed in red. Color attributes can be combined.
482 For example, the specification
484 indicates that a 5 minute load average higher than 10 should be displayed
485 with white characters on a red background. A special tag named
487 is used to control the color of the header for process display. It should
488 be specified with no lower and upper limits, specifically
490 followed by the ANSI color code.
492 You can see a list of color codes recognized by this installation of top
495 option. This will also show the current set of tests used for
496 color highligting, as specified in the environment.
501 TOP user-configurable defaults for options.
502 TOPCOLORS color specification
506 things can change while
508 is collecting information for an update. The picture it gives is only a
509 close approximation to reality.
517 Copyright (C) 1984-2007 William LeFebvre. For additional licensing
518 information, see http://www.unixtop.org/license/