top - Import DragonFly specific patches for 3.8beta1.
[dragonfly.git] / usr.bin / top / top.x
1 .\" NOTE:  changes to the manual page for "top" should be made in the
2 .\"        file "" and NOT in the file "top.1".
3 .nr N 30
4 .nr D 5
5 .nr L 1
6 .nr K 1
7 .TH TOP 1 Local
8 .UC 4
10 top \- display and update information about the top cpu processes
12 .B top
13 [
14 .B \-CISTabcinqtuv
15 ] [
16 .BI \-d count
17 ] [
18 .BI \-m mode
19 ] [
20 .BI \-o field
21 ] [
22 .BI \-s time
23 ] [
24 .BI \-U username
25 ] [
26 .I number
27 ]
29 .\" This defines appropriate quote strings for nroff and troff
30 .ds lq \&"
31 .ds rq \&"
32 .if t .ds lq ``
33 .if t .ds rq ''
34 .\" Just in case these number registers aren't set yet...
35 .if \nN==0 .nr N 10
36 .if \nD==0 .nr D 5
37 .I Top
38 displays the top
39 .if !\nN==-1 \nN
40 processes on the system and periodically updates this information.
41 .if \nN==-1 \
42 \{\
43 If standard output is an intelligent terminal (see below) then
44 as many processes as will fit on the terminal screen are displayed
45 by default.  Otherwise, a good number of them are shown (around 20).
46 .\}
47 Raw cpu percentage is used to rank the processes.  If
48 .I number
49 is given, then the top
50 .I number
51 processes will be displayed instead of the default.
52 .PP
53 .I Top
54 makes a distinction between terminals that support advanced capabilities
55 and those that do not.  This
56 distinction affects the choice of defaults for certain options.  In the
57 remainder of this document, an \*(lqintelligent\*(rq terminal is one that
58 supports cursor addressing, clear screen, and clear to end of line.
59 Conversely, a \*(lqdumb\*(rq terminal is one that does not support such
60 features.  If the output of
61 .I top
62 is redirected to a file, it acts as if it were being run on a dumb
63 terminal.
65 .if \nL==0 Long options are not available on this system.
66 .TP
67 .B "\-C, \-\-color"
68 Turn off the use of color in the display.
69 .TP
70 .B "\-I, \-\-idle-procs"
71 Do not display idle processes.
72 By default, top displays both active and idle processes.
73 .TP
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.
77 .TP
78 .B "\-T, \-\-tag-names"
79 List all available color tags and the current set of tests used for
80 color highlighting, then exit.
81 .TP
82 .B "\-a, \-\-all"
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.
85 .TP
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.
90 .TP
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.
94 .TP
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
98 for an explanation of
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.
103 .TP
104 .B "\-q, \-\-quick"
105 Renice
106 .I top
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.
110 .TP
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.
116 .TP
117 .B "\-u, \-\-uids"
118 Do not take the time to map uid numbers to usernames.  Normally,
119 .I top
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.
124 .TP
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.
129 .TP
130 .B "\-d \fIcount\fP, \-\-displays \fIcount\fP"
131 Show only
132 .I count
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
135 wants to see before
136 .I top
137 automatically exits.  Any proper prefix of the words \*(lqinfinity\*(rq,
138 \*(lqmaximum\*(rq,
139 or
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.
143 .TP
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
149 no effect.
150 .TP
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.
157 .TP
158 .B "\-s \fItime\fP, \-\-delay=\fItime\fP"
159 Set the delay between screen updates to
160 .I time
161 seconds.  The default delay between updates is \nD seconds.
162 .TP
163 .B "\-U \fIusername\fP, \-\-user=\fIusername\fP"
164 Show only those processes owned by
165 .IR username .
166 This option currently only accepts usernames and will not understand
167 uid numbers.
168 .PP
169 Both
170 .I count
171 and
172 .I number
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
176 \*(lqinfinity\*(rq,
177 \*(lqmaximum\*(rq,
178 or
179 \*(lqall\*(rq.
180 The default for
181 .I count
182 on an intelligent terminal is, in fact,
183 \fBinfinity\fP.
184 .PP
185 The environment variable
186 .B TOP
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
190 .BR TOP .
191 The options
192 .BR \-C ,
193 .BR \-I ,
194 .BR \-S ,
195 and
196 .B \-u
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
199 .B TOP
200 set to \*(lq\-I\*(rq may use the command \*(lqtop \-I\*(rq to see idle processes.
202 When
203 .I top
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
208 pressed when
209 .I top
210 is between displays; that is, while it is waiting for
211 .I time
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 
216 .I top
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
221 .IR stty )
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.
225 .PP
226 These commands are currently recognized:
227 .TP
228 .I "\fBh\fP\ or\ \fB?\fP"
229 Display a summary of the commands (help screen).  Version information
230 is included in this display.
231 .TP
232 .B C
233 Toggle the use of color in the display.
234 .TP
235 .B c
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 
238 platforms.
239 .TP
240 .B d
241 Change the number of displays to show (prompt for new number).
242 Remember that the next display counts as one, so typing
243 .B d1
244 will make
245 .I top
246 show one final display and then immediately exit.
247 .TP
248 .B f
249 Toggle the display of the full command line.
250 .TP
251 .B H
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.
256 .TP
257 .B i
258 (or
259 .BR I )
260 Toggle the display of idle processes.
261 .if \nK==1 \{\
262 .TP
263 .B k
264 Send a signal (\*(lqkill\*(rq by default) to a list of processes.  This
265 acts similarly to the command
266 .IR kill (1)).
267 .\}
268 .TP
269 .B M
270 Sort display by memory usage.  Shorthand for \*(lqo size\*(rq.
271 .TP
272 .B m
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.
277 .TP
278 .B N
279 Sort by process id.  Shorthand for \*(lqo pid\*(rq.
280 .TP
281 .B n or #
282 Change the number of processes to display (prompt for new number).
283 .TP
284 .B o
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.
289 .TP
290 .B P
291 Sort by CPU usage.  Shorthand for \*(lqo cpu\*(rq.
292 .TP
293 .B q
294 Quit
295 .IR top.
296 .if \nK==1 \{\
297 .TP
298 .B r
299 Change the priority (the \*(lqnice\*(rq) of a list of processes.
300 This acts similarly to the command
301 .IR renice (8)).
302 .\}
303 .TP
304 .B s
305 Change the number of seconds to delay between displays
306 (prompt for new number).
307 .TP
308 .B T
309 Sort by CPU time.  Shorthand for \*(lqo time\*(rq.
310 .TP
311 .B U
312 Toggle between displaying usernames and uids.
313 .TP
314 .B u
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.
323 .PP
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.
339 The exact
340 information displayed varies between systems, but some examples are:
341 context switches, interrupts, traps, forks, and page faults.  The last
342 one or two lines show a summary of memory and swap activity.  These lines
343 vary between systems.
344 .PP
345 The remainder of the screen displays information about individual
346 processes.  This display is similar in spirit to
347 .IR ps (1)
348 but it is not exactly the same.  The columns displayed by top will
349 differ slightly between operating systems.  Generally, the following
350 fields are displayed:
351 .TP
352 .B PID
353 The process id.
354 .TP
356 Username of the process's owner (if
357 .B \-u
358 is specified, a UID column will be substituted for USERNAME).
359 .TP
360 .B THR
361 The number of threads in the processes (this column may also
362 be labeled NLWP).
363 .TP
364 .B PRI
365 Current priority of the process.
366 .TP
367 .B NICE
368 Nice amount in the range \-20 to 20, as established by the use of
369 the command
370 .IR nice .
371 .TP
372 .B SIZE
373 Total size of the process (text, data, and stack) given in kilobytes.
374 .TP
375 .B RES
376 Resident memory: current amount of process memory that resides in physical
377 memory, given in kilobytes.
378 .TP
379 .B STATE
380 Current state (typically one of \*(lqsleep\*(rq,
381 \*(lqrun\*(rq, \*(lqidl\*(rq, \*(lqzomb\*(rq, or \*(lqstop\*(rq).
382 .TP
383 .B TIME
384 Number of system and user cpu seconds that the process has used.
385 .TP
386 .B CPU
387 Percentage of available cpu time used by this process.
388 .TP
390 Name of the command that the process is currently running.
392 Top supports the use of ANSI color in its output. By default, color is
393 available but not used.  The environment variable
395 specifies colors to use and conditions for which they should be used.
396 At the present time, only numbers in the summay display area can be 
397 colored. In a future version it will be possible to highlight numbers
398 in the process display area as well.  The environment variable is the
399 only way to specify color: there is no equivalent command line option.
400 Note that the environment variable
402 is also understood. The British spelling takes precedence.  The use of
403 color only works on terminals that understand and process ANSI color
404 escape sequences.
405 .PP
406 The environment variable is a sequence of color specifications, separated
407 by colons. Each specification takes the form tag=min,max#code where
408 .I tag
409 is the name of the value to check,
410 .I min
411 and
412 .I max
413 specify a range for the value, and
414 .I code
415 is an ANSI color code.  Multiple color codes can be listed and separated
416 with semi-colons.  A missing
417 .I min
418 implies the lowest possible value (usually 0)
419 and a missing
420 .I max
421 implies infinity. The comma must always be present. When specifying numbers
422 for load averages, they should be multiplied by 100.
423 For example, the specification
424 .B 1min=500,1000#31
425 indicates that a 1 minute load average between
426 5 and 10 should be displayed in red. Color attributes can be combined.
427 For example, the specification
428 .B 5min=1000,#37;41
429 indicates that a 5 minute load average higher than 10 should be displayed
430 with white characters on a red background. A special tag named
431 .I header
432 is used to control the color of the header for process display.  It should
433 be specified with no lower and upper limits, specifically
434 .B header=,#
435 followed by the ANSI color code.
436 .PP
437 You can see a list of color codes recognized by this installation of top
438 with the
439 .B \-T
440 option.  This will also show the current set of tests used for
441 color highligting, as specified in the environment.
443 William LeFebvre
445 .DT
446 TOP             user-configurable defaults for options.
447 TOPCOLORS       color specification
448 .SH BUGS
449 As with
450 .IR ps (1),
451 things can change while
452 .I top
453 is collecting information for an update.  The picture it gives is only a
454 close approximation to reality.
455 .SH "SEE ALSO"
456 kill(1),
457 ps(1),
458 stty(1),
459 mem(4),
460 renice(8)
462 Copyright (C) 1984-2007 William LeFebvre. For additional licensing
463 information, see