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