| blob | 4cf3bcc476e51372f0e5aae04f48687da05e3e48 |
1 .Dd August 21, 2013
2 .Dt TOP 1
3 .Os
4 .Sh NAME
5 .Nm top
6 .Nd display and update information about the top cpu processes
7 .Sh SYNOPSIS
8 .Nm
9 .Op Fl CIMSTabcinqtuv
10 .Op Fl d Ar count
11 .Op Fl m Ar mode
12 .Op Fl o Ar field
13 .Op Fl s Ar time
14 .Op Fl U Ar username
15 .Op Ar number
16 .Sh DESCRIPTION
17 .Nm
18 displays the top
19 processes on the system and periodically updates this information.
20 Raw cpu percentage is used to rank the processes.
21 .Pp
22 .Nm
23 makes a distinction between terminals that support advanced capabilities
24 and those that do not.
25 This distinction affects the choice of defaults for certain options.
26 In the remainder of this document, an
27 .Dq intelligent
28 terminal is one that
29 supports cursor addressing, clear screen, and clear to end of line.
30 Conversely, a
31 .Dq dumb
32 terminal is one that does not support such features.
33 If the output of
34 .Nm
35 is redirected to a file, it acts as if it were being run on a dumb
36 terminal.
37 .Ss OPTIONS
38 .Bl -tag -width "-U username" -offset indent
39 .It Fl C
40 Turn off the use of color in the display.
41 .It Fl I
42 Do not display idle processes.
43 By default, top displays both active and idle processes.
44 .It Fl M
45 Enable multi-CPU display.
46 .It Fl S
47 Show system processes in the display.
48 Normally, system processes such as the pager and the swapper are not shown.
49 This option makes them visible.
50 .It Fl T
51 List all available color tags and the current set of tests used for
52 color highlighting, then exit.
53 .It Fl a
54 Show all processes for as long as possible.
55 This is shorthand for
56 .Dq Fl d Li all Li all .
57 This option is especially handy in batch mode.
58 .It Fl b
59 Use
60 .Dq batch
61 mode.
62 In this mode, all input from the terminal is ignored.
63 Interrupt characters (such as ^C and ^\e) still have an effect.
64 This is the default on a dumb terminal, or when the output is not a terminal.
65 .It Fl c
66 Show the full command line for each process.
67 Default is to show just the command name.
68 This option is not supported on all platforms.
69 .It Fl i
70 Use
71 .Dq interactive
72 mode.
73 In this mode, any input is immediately read for processing.
74 See the subsection on
75 .Sx INTERACTIVE MODE
76 for an explanation of which keys perform what functions.
77 After the command is processed, the screen will immediately be updated,
78 even if the command was not understood.
79 This mode is the default when standard output is an intelligent terminal.
80 .It Fl q
81 Renice
82 .Nm
83 to \-20 so that it will run faster.
84 This can be used when the system is being very sluggish to improve the
85 possibility of discovering the problem.
86 This option can only be used by root.
87 .It Fl t
88 Show individual threads on separate lines.
89 By default, on systems which support threading, each process is shown
90 with a count of the number of threads.
91 This option shows each thread on a separate line.
92 This option is not supported on all platforms.
93 .It Fl u
94 Do not take the time to map uid numbers to usernames.
95 Normally,
96 .Nm
97 will read as much of the file
98 .Pa /etc/passwd
99 as is necessary to map all the user id numbers it encounters into login names.
100 This option disables all that, while possibly decreasing execution time.
101 The uid numbers are displayed instead of the names.
102 .It Fl v
103 Write version number information to stderr then exit immediately.
104 No other processing takes place when this option is used.
105 To see current revision information while top is running,
106 use the help command
107 .Dq \&? .
108 .It Fl d Ar count
109 Show only
110 .Ar count
111 displays, then exit.
112 A display is considered to be one update of the screen.
113 This option allows the user to select the number of displays he
114 wants to see before
115 .Nm
116 automatically exits.
117 Any proper prefix of the words
118 .Sq Li infinity ,
119 .Sq Li maximum ,
120 or
121 .Sq Li all
122 can be used to indicate an infinite number of displays.
123 The default for intelligent terminals is
124 .Sq Li infinity .
125 The default for dumb terminals is
126 .Sq Li 1 .
127 .It Fl m Ar mode
128 Start the display in an alternate mode.
129 Some platforms support multiple
130 process displays to show additional process information.
131 The value of
132 .Ar mode
133 is a number indicating which mode to display.
134 The default is
135 .Sq Li 0 .
136 On platforms that do not have multiple display modes this option has
137 no effect.
138 .It Fl o Ar field
139 Sort the process display area on the specified field.
140 The field name is the name of the column as seen in the output,
141 but in lower case.
142 Likely values are
143 .Sq Li cpu ,
144 .Sq Li size ,
145 .Sq Li res ,
146 and
147 .Sq Li time ,
148 but may vary on different operating systems.
149 Note that not all operating systems support this option.
150 .It Fl s Ar time
151 Set the delay between screen updates to
152 .Ar time
153 seconds.
154 The default delay between updates is 5 seconds.
155 .It Fl U Ar username
156 Show only those processes owned by
157 .Ar username .
158 This option currently only accepts usernames and will not understand
159 uid numbers.
160 .El
161 .Pp
162 If
163 .Ar number
164 is given, then the top
165 .Ar number
166 processes will be displayed instead of the default.
167 Both
168 .Ar count
169 and
170 .Ar number
171 fields can be specified as
172 .Sq Li infinite ,
173 indicating that they can stretch as far as possible.
174 This is accomplished by using any proper prefix of the keywords
175 .Sq Li infinity ,
176 .Sq Li maximum ,
177 or
178 .Sq Li all .
179 The default for
180 .Ar count
181 on an intelligent terminal is, in fact,
182 .Sq Li infinity .
183 .Ss INTERACTIVE MODE
184 When
185 .Nm
186 is running in
187 .Dq interactive mode ,
188 it reads commands from the terminal and acts upon them accordingly.
189 In this mode, the terminal is put in
190 .Dq CBREAK ,
191 so that a character will be processed as soon as it is typed.
192 Almost always, a key will be pressed when
193 .Nm
194 is between displays; that is, while it is waiting for
195 .Ar time
196 seconds to elapse.
197 If this is the case, the command will be
198 processed and the display will be updated immediately thereafter
199 (reflecting any changes that the command may have specified).
200 This happens even if the command was incorrect.
201 If a key is pressed while
202 .Nm
203 is in the middle of updating the display, it will finish the update and
204 then process the command.
205 Some commands require additional information,
206 and the user will be prompted accordingly.
207 While typing this information
208 in, the user's erase and kill keys (as set up by the command
209 .Xr stty 1 )
210 are recognized, and a newline terminates the input.
211 Note that a control\-L
212 (^L) always redraws the current screen and a space forces an immediate
213 update to the screen using new data.
214 .Pp
215 These commands are currently recognized:
216 .Bl -tag -width "h or \&?" -offset indent
217 .It h or \&?
218 Display a summary of the commands (help screen).
219 Version information is included in this display.
220 .It C
221 Toggle the use of color in the display.
222 .It c
223 Display only processes whose commands match the specified string.
224 An empty string will display all processes.
225 This command is not supported on all platforms.
226 .It d
227 Change the number of displays to show (prompt for new number).
228 Remember that the next display counts as one, so typing
229 .Dq d1
230 will make
231 .Nm
232 show one final display and then immediately exit.
233 .It f
234 Toggle the display of the full command line.
235 .It H
236 Toggle the display of threads on separate lines.
237 By default, on systems which support threading,
238 each process is shown with a count of the number of threads.
239 This command shows each thread on a separate line.
240 This command is not supported on all platforms.
241 .It i or I
242 Toggle the display of idle processes.
243 .It k
244 Send a signal (
245 .Dq kill
246 by default) to a list of processes.
247 This acts similarly to the command
248 .Xr kill 1 .
249 .It M
250 Sort display by memory usage.
251 Shorthand for
252 .Dq Fl o Li size .
253 .It m
254 Change to a different process display mode.
255 Some systems provide multiple
256 display modes for the process display which shows different information.
257 This command toggles between the available modes.
258 This command is not supported on all platforms.
259 .It N
260 Sort by process id.
261 Shorthand for
262 .Dq Fl o Li pid .
263 .It n or #
264 Change the number of processes to display (prompt for new number).
265 .It o
266 Change the order in which the display is sorted.
267 This command is not available on all systems.
268 The sort key names vary fron system to system,
269 but usually include:
270 .Sq Li cpu ,
271 .Sq Li res ,
272 .Sq Li size ,
273 and
274 .Sq Li time .
275 The default is
276 .Sq Li cpu .
277 .It P
278 Sort by CPU usage.
279 Shorthand for
280 .Dq Fl o Li cpu .
281 .It q
282 Quit
283 .Nm .
284 .It r
285 Change the priority (the niceness) of a list of processes.
286 This acts similarly to the command
287 .Xr renice 8 .
288 .It s
289 Change the number of seconds to delay between displays
290 (prompt for new number).
291 .It T
292 Sort by CPU time.
293 Shorthand for
294 .Dq Fl o Li time .
295 .It U
296 Toggle between displaying usernames and uids.
297 .It u
298 Display only processes owned by a specific username (prompt for username).
299 If the username specified is simply
300 .Dq + ,
301 then processes belonging to all users will be displayed.
302 .El
303 .Ss THE DISPLAY
304 The actual display varies depending on the specific variant of Unix
305 that the machine is running.
306 This description may not exactly match what is seen by top running on
307 this particular machine.
308 Differences are listed at the end of this manual entry.
309 .Pp
310 The top lines of the display show general information
311 about the state of the system.
312 The first line shows
313 (on some systems) the last process id assigned to a process,
314 the three load averages,
315 the system uptime, and the current time.
316 The second line displays the total number of processes followed
317 by a breakdown of processes per state.
318 Examples of states common
319 to Unix systems are sleeping, running, starting, stopped, and zombie.
320 The next line displays a percentage of time spent in each of the
321 processor states (user, nice, system, interrupt, idle).
322 These percentages show the processor activity during the time since
323 the last update.
324 For multi-processor systems, this information is an average of all processors.
325 The next line shows kernel-related activity (not available on all systems).
326 The numbers shown on this line are per-second rates sampled since the last
327 update.
328 The exact information displayed varies between systems, but some examples are:
329 context switches, interrupts, traps, forks, and page faults.
330 .Pp
331 The last two lines show a summary of memory and swap activity.
332 The fields are as follows:
333 .Bl -tag -width "Active:" -offset indent
334 .It Active:
335 number of pages active
336 .It Inact:
337 number of pages inactive
338 .It Wired:
339 number of pages wired down, including cached file data pages
340 .It Cache:
341 number of pages used for VM-level disk caching
342 .It Buf:
343 number of pages used for BIO-level disk caching
344 .It Free:
345 number of pages free
346 .It Total:
347 total available swap usage
348 .It Free:
349 total free swap usage
350 .It Inuse:
351 swap usage
352 .It In:
353 pages paged in from swap devices (last interval)
354 .It Out:
355 pages paged out to swap devices (last interval)
356 .It K:
357 Kilobyte
358 .It M:
359 Megabyte
360 .It %:
361 1/100
362 .El
363 .Pp
364 The remainder of the screen displays information about individual
365 processes.
366 This display is similar in spirit to
367 .Xr ps 1 ,
368 but it is not exactly the same.
369 The columns displayed by top will differ slightly between operating systems.
370 Generally, the following fields are displayed:
371 .Bl -tag -width "USERNAME" -offset indent
372 .It PID
373 The process id.
374 .It USERNAME
375 Username of the process's owner (if
376 .Fl u
377 is specified, a UID column will be substituted for USERNAME).
378 .It THR
379 The number of threads in the processes (this column may also
380 be labeled NLWP).
381 .It PRI
382 Current priority of the process.
383 This field is no longer displayed.
384 .It NICE
385 Nice amount in the range \-20 to 20, as established by the use of
386 the command
387 .Xr nice 1 .
388 .It SIZE
389 Total size of the process (text, data, and stack) given in kilobytes.
390 .It PRES
391 Proportional resident memory: current amount of process memory that resides
392 in physical memory, given in kilobytes.
393 Shared memory is divided among the processes doing the sharing.
394 This field replaces RES.
395 .It STATE
396 Current state (typically one of
397 .Sq sleep ,
398 .Sq run ,
399 .Sq idl ,
400 .Sq zomb ,
401 or
402 .Sq stop ) .
403 .It C
404 Number of CPU the process is currently running on (only on multi-CPU machines).
405 .It TIME
406 Number of system and user cpu seconds that the process has used.
407 .It CTIME
408 The cumulated CPU time of the process and its exited children.
409 This value is similar to what
410 .Xr ps 1
411 displays as CPU time when run with the
412 .Fl S
413 option.
414 .It CPU
415 Percentage of available cpu time used by this process.
416 .It COMMAND
417 Name of the command that the process is currently running.
418 .El
419 .Ss COLOR
420 Top supports the use of ANSI color in its output.
421 By default, color is available but not used.
422 The environment variable
423 .Ev TOPCOLORS
424 specifies colors to use and conditions for which they should be used.
425 At the present time, only numbers in the summary display area can be
426 colored.
427 In a future version it will be possible to highlight numbers
428 in the process display area as well.
429 The environment variable is the only way to specify color:
430 there is no equivalent command line option.
431 Note that the environment variable
432 .Ev TOPCOLOURS
433 is also understood.
434 The British spelling takes precedence.
435 The use of color only works on terminals that understand and process
436 ANSI color escape sequences.
437 .Pp
438 You can see a list of color codes recognized by this installation of top
439 with the
440 .Fl T
441 option.
442 This will also show the current set of tests used for
443 color highligting, as specified in the environment.
444 .Sh ENVIRONMENT
445 The following environment variables affect the execution of
446 .Nm :
447 .Bl -tag -width "TOPCOLORS"
448 .It Ev TOP
449 The environment variable
450 .Ev TOP
451 is examined for options before the command line is scanned.
452 This enables a user to set his or her own defaults.
453 The number of processes to display
454 can also be specified in the environment variable
455 .Ev TOP .
456 The options
457 .Dq Fl C ,
458 .Dq Fl I ,
459 .Dq Fl S ,
460 and
461 .Dq Fl u
462 are actually toggles.
463 A second specification of any of these options will negate the first.
464 Thus a user who has the environment variable
465 .Ev TOP
466 set to
467 .Dq Fl I
468 may use the command
469 .Dq Nm Fl I
470 to see idle processes.
471 .It Ev TOPCOLORS
472 The environment variable is a sequence of color specifications, separated
473 by colons.
474 Each specification takes the form tag=min,max#code where
475 .Li tag
476 is the name of the value to check,
477 .Li min
478 and
479 .Li max
480 specify a range for the value, and
481 .Li code
482 is an ANSI color code.
483 Multiple color codes can be listed and separated with semi-colons.
484 A missing
485 .Li min
486 implies the lowest possible value (usually 0)
487 and a missing
488 .Li max
489 implies infinity.
490 The comma must always be present.
491 When specifying numbers for load averages, they should be multiplied by 100.
492 For example, the specification
493 .Li 1min=500,1000#31
494 indicates that a 1 minute load average between
495 5 and 10 should be displayed in red.
496 Color attributes can be combined.
497 For example, the specification
498 .Li 5min=1000,#37;41
499 indicates that a 5 minute load average higher than 10 should be displayed
500 with white characters on a red background.
501 A special tag named
502 .Li header
503 is used to control the color of the header for process display.
504 It should be specified with no lower and upper limits, specifically
505 .Li header=,#
506 followed by the ANSI color code.
507 .El
508 .Sh SEE ALSO
509 .Xr kill 1 ,
510 .Xr ps 1 ,
511 .Xr stty 1 ,
512 .Xr mem 4 ,
513 .Xr renice 8
514 .Sh AUTHORS
515 .An William LeFebvre
516 .Sh BUGS
517 As with
518 .Xr ps 1 ,
519 things can change while
520 .Nm
521 is collecting information for an update.
522 The picture it gives is only a close approximation to reality.
523 .\" .Sh COPYRIGHT
524 .\" Copyright (C) 1984-2007 William LeFebvre.
525 .\" For additional licensing information, see
526 .\" http://www.unixtop.org/license/