Annotation of src/usr.bin/top/top.1, Revision 1.45
1.45 ! jmc 1: .\" $OpenBSD: top.1,v 1.44 2007/02/14 08:29:28 jmc Exp $
1.2 downsj 2: .\"
3: .\" Copyright (c) 1997, Jason Downs. All rights reserved.
4: .\"
5: .\" Redistribution and use in source and binary forms, with or without
6: .\" modification, are permitted provided that the following conditions
7: .\" are met:
8: .\" 1. Redistributions of source code must retain the above copyright
9: .\" notice, this list of conditions and the following disclaimer.
10: .\" 2. Redistributions in binary form must reproduce the above copyright
11: .\" notice, this list of conditions and the following disclaimer in the
12: .\" documentation and/or other materials provided with the distribution.
13: .\"
14: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS
15: .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
16: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
17: .\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT,
18: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
19: .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
20: .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
21: .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24: .\" SUCH DAMAGE.
25: .\"
26: .Dd August 14, 1997
27: .Dt TOP 1
1.10 aaron 28: .Os
1.2 downsj 29: .Sh NAME
30: .Nm top
1.5 aaron 31: .Nd display and update information about the top CPU processes
1.2 downsj 32: .Sh SYNOPSIS
1.6 aaron 33: .Nm top
1.45 ! jmc 34: .Bk -words
1.34 otto 35: .Op Fl bCIinqSTu
1.2 downsj 36: .Op Fl d Ar count
1.45 ! jmc 37: .Op Fl g Ar string
1.23 jmc 38: .Op Fl o Ar field
1.25 otto 39: .Op Fl p Ar pid
1.2 downsj 40: .Op Fl s Ar time
1.45 ! jmc 41: .Op Fl U Ar user
1.2 downsj 42: .Op Ar number
1.45 ! jmc 43: .Ek
1.2 downsj 44: .Sh DESCRIPTION
45: .Nm
46: displays the top processes on the system and periodically updates this
1.13 aaron 47: information.
48: If standard output is an intelligent terminal (see below) then
1.1 downsj 49: as many processes as will fit on the terminal screen are displayed
1.13 aaron 50: by default.
51: Otherwise, a good number of them are shown (around 20).
52: Raw CPU percentage is used to rank the processes.
53: If
1.2 downsj 54: .Ar number
1.1 downsj 55: is given, then the top
1.2 downsj 56: .Ar number
1.1 downsj 57: processes will be displayed instead of the default.
1.2 downsj 58: .Pp
59: .Nm
1.1 downsj 60: makes a distinction between terminals that support advanced capabilities
1.13 aaron 61: and those that do not.
62: This distinction affects the choice of defaults for certain options.
63: In the remainder of this document, an
1.2 downsj 64: .Em intelligent
65: terminal is one that supports cursor addressing, clear screen, and clear
1.13 aaron 66: to end of line.
67: Conversely, a
1.43 jmc 68: .Em dumb
1.13 aaron 69: terminal is one that does not support such features.
70: If the output of
1.2 downsj 71: .Nm
1.1 downsj 72: is redirected to a file, it acts as if it were being run on a dumb
73: terminal.
1.12 aaron 74: .Pp
75: The options are as follows:
1.15 aaron 76: .Bl -tag -width Ds
1.2 downsj 77: .It Fl b
78: Use
79: .Em batch
1.13 aaron 80: mode.
81: In this mode, all input from the terminal is ignored.
82: Interrupt characters (such as
83: .Ql ^C
84: and
85: .Ql ^\e )
86: still have an effect.
1.1 downsj 87: This is the default on a dumb terminal, or when the output is not a terminal.
1.34 otto 88: .It Fl C
1.42 jmc 89: Show command line arguments
90: as well as the process itself.
1.23 jmc 91: .It Fl d Ar count
92: Show only
93: .Ar count
94: displays, then exit.
95: A display is considered to be one update of the screen.
96: This option allows the user to select the number of displays
97: to be shown before
98: .Nm
99: automatically exits.
100: For intelligent terminals, no upper limit is set.
101: The default is 1 for dumb terminals.
1.45 ! jmc 102: .It Fl g Ar string
! 103: Display only processes that contain
! 104: .Ar string
1.35 otto 105: in their command name.
1.27 jmc 106: .It Fl I
107: Do not display idle processes.
108: By default,
109: .Nm
110: displays both active and idle processes.
1.2 downsj 111: .It Fl i
112: Use
113: .Em interactive
1.13 aaron 114: mode.
115: In this mode, any input is immediately read for processing.
116: See the section on
1.2 downsj 117: .Sx INTERACTIVE MODE
1.13 aaron 118: for an explanation of which keys perform what functions.
119: After the command
1.2 downsj 120: is processed, the screen will immediately be updated, even if the command was
1.13 aaron 121: not understood.
122: This mode is the default when standard output is an intelligent terminal.
1.2 downsj 123: .It Fl n
1.10 aaron 124: Use
1.2 downsj 125: .Em non-interactive
1.13 aaron 126: mode.
127: This is identical to
1.2 downsj 128: .Em batch
1.1 downsj 129: mode.
1.23 jmc 130: .It Fl o Ar field
1.45 ! jmc 131: Sort the process display area using the specified
! 132: .Ar field
! 133: as the primary key.
1.23 jmc 134: The field name is the name of the column as seen in the output,
135: but in lower case.
136: The
137: .Ox
1.26 jaredy 138: version of
139: .Nm
140: supports
1.23 jmc 141: .Ar cpu ,
142: .Ar size ,
143: .Ar res ,
144: .Ar time ,
145: and
146: .Ar pri .
1.25 otto 147: .It Fl p Ar pid
148: Show only the process
149: .Ar pid .
1.2 downsj 150: .It Fl q
1.1 downsj 151: Renice
1.2 downsj 152: .Nm
1.26 jaredy 153: to \-20 so that it will run faster.
1.13 aaron 154: This can be used when the system is
1.1 downsj 155: being very sluggish to improve the possibility of discovering the problem.
156: This option can only be used by root.
1.27 jmc 157: .It Fl S
158: Show system processes in the display.
159: Normally, system processes such as the pager and the swapper are not shown.
160: This option makes them visible.
1.23 jmc 161: .It Fl s Ar time
162: Set the delay between screen updates to
163: .Ar time
164: seconds.
165: The value may be fractional, to permit delays of less than 1 second.
166: The default delay between updates is 5 seconds.
1.32 tedu 167: .It Fl T
168: Show process threads in the display.
169: Normally, only the main process is shown.
170: This option makes all threads visible.
1.45 ! jmc 171: .It Fl U Ar user
1.27 jmc 172: Show only those processes owned by
1.45 ! jmc 173: .Ar user .
1.27 jmc 174: This option currently only accepts usernames and will not understand
175: UID numbers.
1.2 downsj 176: .It Fl u
1.13 aaron 177: Do not take the time to map UID numbers to usernames.
178: Normally,
1.2 downsj 179: .Nm
180: will read as much of the password database as is necessary to map
1.13 aaron 181: all the user ID numbers it encounters into login names.
182: This option
183: disables all that, while possibly decreasing execution time.
184: The UID numbers are displayed instead of the names.
1.2 downsj 185: .El
186: .Pp
1.1 downsj 187: Both
1.2 downsj 188: .Ar count
1.1 downsj 189: and
1.2 downsj 190: .Ar number
191: fields can be specified as
192: .Li infinite ,
1.13 aaron 193: indicating that they can stretch as far as possible.
194: This is accomplished by using any proper prefix of the keywords
1.2 downsj 195: .Li infinity ,
196: .Li maximum ,
1.1 downsj 197: or
1.2 downsj 198: .Li all .
1.1 downsj 199: The default for
1.2 downsj 200: .Ar count
1.1 downsj 201: on an intelligent terminal is, in fact,
1.2 downsj 202: .Li infinity .
203: .Pp
1.1 downsj 204: The environment variable
1.2 downsj 205: .Ev TOP
1.13 aaron 206: is examined for options before the command line is scanned.
207: This enables a user to set his or her own defaults.
208: The number of processes to display
1.1 downsj 209: can also be specified in the environment variable
1.2 downsj 210: .Ev TOP .
211: .Pp
1.1 downsj 212: The options
1.2 downsj 213: .Fl I ,
214: .Fl S ,
1.1 downsj 215: and
1.2 downsj 216: .Fl u
1.13 aaron 217: are actually toggles.
218: A second specification of any of these options
219: will negate the first.
220: Thus a user who has the environment variable
1.2 downsj 221: .Ev TOP
1.10 aaron 222: set to
1.5 aaron 223: .Dq -I
1.10 aaron 224: may use the command
1.5 aaron 225: .Dq top -I
1.2 downsj 226: to see idle processes.
227: .Sh INTERACTIVE MODE
1.1 downsj 228: When
1.2 downsj 229: .Nm
230: is running in
231: .Em interactive mode ,
1.13 aaron 232: it reads commands from the terminal and acts upon them accordingly.
233: In this mode, the terminal is put in
1.2 downsj 234: .Dv CBREAK ,
1.13 aaron 235: so that a character will be processed as soon as it is typed.
236: Almost always, a key will be pressed when
1.2 downsj 237: .Nm
1.1 downsj 238: is between displays; that is, while it is waiting for
1.2 downsj 239: .Ar time
1.13 aaron 240: seconds to elapse.
241: If this is the case, the command will be
1.1 downsj 242: processed and the display will be updated immediately thereafter
1.13 aaron 243: (reflecting any changes that the command may have specified).
244: This happens even if the command was incorrect.
245: If a key is pressed while
1.2 downsj 246: .Nm
1.1 downsj 247: is in the middle of updating the display, it will finish the update and
1.13 aaron 248: then process the command.
249: Some commands require additional information,
250: and the user will be prompted accordingly.
251: While typing this information
1.1 downsj 252: in, the user's erase and kill keys (as set up by the command
1.2 downsj 253: .Xr stty 1 )
1.1 downsj 254: are recognized, and a newline terminates the input.
1.2 downsj 255: .Pp
1.1 downsj 256: These commands are currently recognized (^L refers to control-L):
1.2 downsj 257: .Bl -tag -width XxXXXX
1.40 jmc 258: .It h \*(Ba \&?
1.27 jmc 259: Display a summary of the commands (help screen).
1.2 downsj 260: .It ^L
1.1 downsj 261: Redraw the screen.
1.2 downsj 262: .It q
1.1 downsj 263: Quit
1.40 jmc 264: .Nm .
1.23 jmc 265: .El
266: .Pp
267: The following commands may not be available with overstrike terminals:
268: .Bl -tag -width XxXXXX
1.38 otto 269: .It +
1.39 jmc 270: Reset any filters put in place by the
271: .Sq g ,
272: .Sq p ,
273: and
274: .Sq u
275: interactive commands,
276: or their command line equivalents.
1.29 markus 277: .It C
278: Toggle the display of process command line arguments.
1.44 jmc 279: .It d Ar count
280: Show only
281: .Ar count
282: displays,
283: then exit.
1.23 jmc 284: .It e
285: Display a list of system errors (if any) generated by the last
286: .Li kill
287: or
288: .Li renice
289: command.
1.40 jmc 290: .It g Ar string
291: Display only processes that contain
292: .Ar string
293: in their command name.
294: .Sq g+
295: shows all processes.
296: .It I \*(Ba i
1.23 jmc 297: Toggle the display of idle processes.
1.41 jmc 298: .It Xo k
299: .Op - Ns Ar sig
300: .Ar pid
301: .Xc
302: Send signal
303: .No - Ns Ar sig
1.21 jmc 304: .Pf ( Dv TERM
1.41 jmc 305: by default) to process
306: .Ar pid .
1.13 aaron 307: This acts similarly to the command
1.2 downsj 308: .Xr kill 1 .
1.44 jmc 309: .It n\*(Ba# Ar count
310: Show
311: .Ar count
1.40 jmc 312: processes.
313: .It o Ar field
1.45 ! jmc 314: Sort the process display area using the specified
! 315: .Ar field
! 316: as the primary key.
1.23 jmc 317: Values are the same as for the
318: .Fl o
319: flag, as detailed above.
1.40 jmc 320: .It p Ar pid
1.45 ! jmc 321: Show only the process
1.40 jmc 322: .Ar pid .
323: .Sq p+
324: shows all processes.
1.44 jmc 325: .It r Ar count pid
1.2 downsj 326: Change the priority (the
327: .Em nice )
1.44 jmc 328: of a list of processes to
329: .Ar count
1.40 jmc 330: for process
331: .Ar pid .
1.13 aaron 332: This acts similarly to the command
1.2 downsj 333: .Xr renice 8 .
1.27 jmc 334: .It S
335: Toggle the display of system processes.
1.44 jmc 336: .It s Ar time
337: Set the delay between screen updates to
338: .Ar time
1.40 jmc 339: seconds.
1.36 otto 340: .It T
341: Toggle the display of process threads.
1.40 jmc 342: .It u Ar user
1.45 ! jmc 343: Show only those processes owned by
1.40 jmc 344: .Ar user .
345: .Sq u+
346: shows processes belonging to all users.
1.2 downsj 347: .El
348: .Sh THE DISPLAY
349: .\" The actual display varies depending on the specific variant of Unix
350: .\" that the machine is running. This description may not exactly match
351: .\" what is seen by top running on this particular machine. Differences
352: .\" are listed at the end of this manual entry.
353: .\" .Pp
1.1 downsj 354: The top few lines of the display show general information
355: about the state of the system, including
1.11 millert 356: .\" the last process ID assigned to a process,
1.2 downsj 357: .\" (on most systems),
1.24 millert 358: the three load average numbers,
1.1 downsj 359: the current time,
360: the number of existing processes,
361: the number of processes in each state
1.26 jaredy 362: (starting, running, idle, stopped, zombie, dead, and on processor),
1.1 downsj 363: and a percentage of time spent in each of the processor states
1.26 jaredy 364: (user, nice, system, interrupt, and idle).
1.17 aaron 365: It also includes information about physical and virtual memory allocation.
1.24 millert 366: The load average numbers give the number of jobs in the run queue averaged
1.26 jaredy 367: over 1, 5, and 15 minutes.
1.2 downsj 368: .Pp
1.1 downsj 369: The remainder of the screen displays information about individual
1.13 aaron 370: processes.
371: This display is similar in spirit to
1.2 downsj 372: .Xr ps 1
1.13 aaron 373: but it is not exactly the same.
1.26 jaredy 374: The following fields are displayed:
375: .Bl -tag -width USERNAME -offset indent
376: .It PID
377: The process ID.
378: .It USERNAME
379: The name of the process's owner.
380: .It UID
381: Used instead of USERNAME if
1.2 downsj 382: .Fl u
1.26 jaredy 383: is specified.
384: .It PRI
385: The current priority of the process.
386: .It NICE
387: The nice amount (in the range \-20 to 20).
388: .It SIZE
389: The total size of the process (the text, data, and stack segments).
390: .It RES
391: The current amount of resident memory.
392: .It STATE
393: The current state (one of
394: .Li start ,
395: .Li run ,
1.2 downsj 396: .Li sleep ,
1.26 jaredy 397: .Li stop ,
398: .Li idle ,
1.2 downsj 399: .Li zomb ,
1.26 jaredy 400: .Li dead ,
1.2 downsj 401: or
1.26 jaredy 402: .Li onproc ) .
403: On multi-processor systems, this is followed by a slash and the CPU
404: number on which the process is bound.
405: .It WAIT
406: A description of the wait channel the process is sleeping on if it's
407: asleep.
408: .It TIME
409: The number of system and user CPU seconds that the process has used.
410: .It CPU
411: The raw percentage of CPU usage and the default field on which the
412: display is sorted.
413: .It COMMAND
414: The name of the command that the process is currently running.
415: (If the process is swapped out, this column is enclosed by angle
416: brackets.)
417: .El
1.2 downsj 418: .Sh ENVIRONMENT
1.26 jaredy 419: .Bl -tag -width Ev
1.2 downsj 420: .It Ev TOP
421: User-configurable defaults for options.
422: .El
423: .Sh FILES
1.26 jaredy 424: .Bl -tag -width Pa -compact
1.2 downsj 425: .It Pa /dev/kmem
426: kernel memory
427: .It Pa /dev/mem
428: physical memory
1.26 jaredy 429: .It Pa /etc/passwd
430: used to map user ID to name
1.2 downsj 431: .It Pa /bsd
432: kernel image
1.14 aaron 433: .El
1.13 aaron 434: .Sh SEE ALSO
1.30 jmc 435: .Xr fstat 1 ,
1.13 aaron 436: .Xr kill 1 ,
1.30 jmc 437: .Xr netstat 1 ,
1.13 aaron 438: .Xr ps 1 ,
439: .Xr stty 1 ,
440: .Xr systat 1 ,
441: .Xr mem 4 ,
1.30 jmc 442: .Xr iostat 8 ,
443: .Xr pstat 8 ,
444: .Xr renice 8 ,
1.31 jmc 445: .Xr vmstat 8
1.16 aaron 446: .Sh AUTHORS
447: William LeFebvre, EECS Department, Northwestern University
1.2 downsj 448: .Sh BUGS
1.1 downsj 449: As with
1.2 downsj 450: .Xr ps 1 ,
1.1 downsj 451: things can change while
1.2 downsj 452: .Nm
1.13 aaron 453: is collecting information for an update.
454: The picture it gives is only a
1.1 downsj 455: close approximation to reality.