Annotation of src/usr.bin/top/top.1, Revision 1.23
1.23 ! jmc 1: .\" $OpenBSD: top.1,v 1.22 2003/09/02 18:50:07 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.23 ! jmc 34: .Op Fl biInqSu
1.2 downsj 35: .Op Fl d Ar count
1.23 ! jmc 36: .Op Fl o Ar field
1.2 downsj 37: .Op Fl s Ar time
38: .Op Fl U Ar username
39: .Op Ar number
40: .Sh DESCRIPTION
41: .Nm
42: displays the top processes on the system and periodically updates this
1.13 aaron 43: information.
44: If standard output is an intelligent terminal (see below) then
1.1 downsj 45: as many processes as will fit on the terminal screen are displayed
1.13 aaron 46: by default.
47: Otherwise, a good number of them are shown (around 20).
48: Raw CPU percentage is used to rank the processes.
49: If
1.2 downsj 50: .Ar number
1.1 downsj 51: is given, then the top
1.2 downsj 52: .Ar number
1.1 downsj 53: processes will be displayed instead of the default.
1.2 downsj 54: .Pp
55: .Nm
1.1 downsj 56: makes a distinction between terminals that support advanced capabilities
1.13 aaron 57: and those that do not.
58: This distinction affects the choice of defaults for certain options.
59: In the remainder of this document, an
1.2 downsj 60: .Em intelligent
61: terminal is one that supports cursor addressing, clear screen, and clear
1.13 aaron 62: to end of line.
63: Conversely, a
64: .Dq dumb
65: terminal is one that does not support such features.
66: If the output of
1.2 downsj 67: .Nm
1.1 downsj 68: is redirected to a file, it acts as if it were being run on a dumb
69: terminal.
1.12 aaron 70: .Pp
71: The options are as follows:
1.15 aaron 72: .Bl -tag -width Ds
1.2 downsj 73: .It Fl b
74: Use
75: .Em batch
1.13 aaron 76: mode.
77: In this mode, all input from the terminal is ignored.
78: Interrupt characters (such as
79: .Ql ^C
80: and
81: .Ql ^\e )
82: still have an effect.
1.1 downsj 83: This is the default on a dumb terminal, or when the output is not a terminal.
1.23 ! jmc 84: .It Fl d Ar count
! 85: Show only
! 86: .Ar count
! 87: displays, then exit.
! 88: A display is considered to be one update of the screen.
! 89: This option allows the user to select the number of displays
! 90: to be shown before
! 91: .Nm
! 92: automatically exits.
! 93: For intelligent terminals, no upper limit is set.
! 94: The default is 1 for dumb terminals.
1.2 downsj 95: .It Fl i
96: Use
97: .Em interactive
1.13 aaron 98: mode.
99: In this mode, any input is immediately read for processing.
100: See the section on
1.2 downsj 101: .Sx INTERACTIVE MODE
1.13 aaron 102: for an explanation of which keys perform what functions.
103: After the command
1.2 downsj 104: is processed, the screen will immediately be updated, even if the command was
1.13 aaron 105: not understood.
106: This mode is the default when standard output is an intelligent terminal.
1.2 downsj 107: .It Fl I
1.1 downsj 108: Do not display idle processes.
109: By default, top displays both active and idle processes.
1.2 downsj 110: .It Fl n
1.10 aaron 111: Use
1.2 downsj 112: .Em non-interactive
1.13 aaron 113: mode.
114: This is identical to
1.2 downsj 115: .Em batch
1.1 downsj 116: mode.
1.23 ! jmc 117: .It Fl o Ar field
! 118: Sort the process display area using the specified field as the primary key.
! 119: The field name is the name of the column as seen in the output,
! 120: but in lower case.
! 121: The
! 122: .Ox
! 123: version of top supports
! 124: .Ar cpu ,
! 125: .Ar size ,
! 126: .Ar res ,
! 127: .Ar time ,
! 128: and
! 129: .Ar pri .
1.2 downsj 130: .It Fl q
1.1 downsj 131: Renice
1.2 downsj 132: .Nm
1.13 aaron 133: to -20 so that it will run faster.
134: This can be used when the system is
1.1 downsj 135: being very sluggish to improve the possibility of discovering the problem.
136: This option can only be used by root.
1.23 ! jmc 137: .It Fl s Ar time
! 138: Set the delay between screen updates to
! 139: .Ar time
! 140: seconds.
! 141: The value may be fractional, to permit delays of less than 1 second.
! 142: The default delay between updates is 5 seconds.
! 143: .It Fl S
! 144: Show system processes in the display.
! 145: Normally, system processes such as the pager and the swapper are not shown.
! 146: This option makes them visible.
1.2 downsj 147: .It Fl u
1.13 aaron 148: Do not take the time to map UID numbers to usernames.
149: Normally,
1.2 downsj 150: .Nm
151: will read as much of the password database as is necessary to map
1.13 aaron 152: all the user ID numbers it encounters into login names.
153: This option
154: disables all that, while possibly decreasing execution time.
155: The UID numbers are displayed instead of the names.
1.2 downsj 156: .It Fl U Ar username
1.1 downsj 157: Show only those processes owned by
1.2 downsj 158: .Ar username .
1.1 downsj 159: This option currently only accepts usernames and will not understand
1.5 aaron 160: UID numbers.
1.2 downsj 161: .El
162: .Pp
1.1 downsj 163: Both
1.2 downsj 164: .Ar count
1.1 downsj 165: and
1.2 downsj 166: .Ar number
167: fields can be specified as
168: .Li infinite ,
1.13 aaron 169: indicating that they can stretch as far as possible.
170: This is accomplished by using any proper prefix of the keywords
1.2 downsj 171: .Li infinity ,
172: .Li maximum ,
1.1 downsj 173: or
1.2 downsj 174: .Li all .
1.1 downsj 175: The default for
1.2 downsj 176: .Ar count
1.1 downsj 177: on an intelligent terminal is, in fact,
1.2 downsj 178: .Li infinity .
179: .Pp
1.1 downsj 180: The environment variable
1.2 downsj 181: .Ev TOP
1.13 aaron 182: is examined for options before the command line is scanned.
183: This enables a user to set his or her own defaults.
184: The number of processes to display
1.1 downsj 185: can also be specified in the environment variable
1.2 downsj 186: .Ev TOP .
187: .Pp
1.1 downsj 188: The options
1.2 downsj 189: .Fl I ,
190: .Fl S ,
1.1 downsj 191: and
1.2 downsj 192: .Fl u
1.13 aaron 193: are actually toggles.
194: A second specification of any of these options
195: will negate the first.
196: Thus a user who has the environment variable
1.2 downsj 197: .Ev TOP
1.10 aaron 198: set to
1.5 aaron 199: .Dq -I
1.10 aaron 200: may use the command
1.5 aaron 201: .Dq top -I
1.2 downsj 202: to see idle processes.
203: .Sh INTERACTIVE MODE
1.1 downsj 204: When
1.2 downsj 205: .Nm
206: is running in
207: .Em interactive mode ,
1.13 aaron 208: it reads commands from the terminal and acts upon them accordingly.
209: In this mode, the terminal is put in
1.2 downsj 210: .Dv CBREAK ,
1.13 aaron 211: so that a character will be processed as soon as it is typed.
212: Almost always, a key will be pressed when
1.2 downsj 213: .Nm
1.1 downsj 214: is between displays; that is, while it is waiting for
1.2 downsj 215: .Ar time
1.13 aaron 216: seconds to elapse.
217: If this is the case, the command will be
1.1 downsj 218: processed and the display will be updated immediately thereafter
1.13 aaron 219: (reflecting any changes that the command may have specified).
220: This happens even if the command was incorrect.
221: If a key is pressed while
1.2 downsj 222: .Nm
1.1 downsj 223: is in the middle of updating the display, it will finish the update and
1.13 aaron 224: then process the command.
225: Some commands require additional information,
226: and the user will be prompted accordingly.
227: While typing this information
1.1 downsj 228: in, the user's erase and kill keys (as set up by the command
1.2 downsj 229: .Xr stty 1 )
1.1 downsj 230: are recognized, and a newline terminates the input.
1.2 downsj 231: .Pp
1.1 downsj 232: These commands are currently recognized (^L refers to control-L):
1.2 downsj 233: .Bl -tag -width XxXXXX
234: .It ^L
1.1 downsj 235: Redraw the screen.
1.22 jmc 236: .It h or \&?
1.1 downsj 237: Display a summary of the commands (help screen).
1.2 downsj 238: .It q
1.1 downsj 239: Quit
1.2 downsj 240: .Nm top .
1.23 ! jmc 241: .El
! 242: .Pp
! 243: The following commands may not be available with overstrike terminals:
! 244: .Bl -tag -width XxXXXX
1.2 downsj 245: .It d
1.1 downsj 246: Change the number of displays to show (prompt for new number).
247: Remember that the next display counts as one, so typing
1.5 aaron 248: .Dq d1
1.1 downsj 249: will make
1.2 downsj 250: .Nm
1.1 downsj 251: show one final display and then immediately exit.
1.23 ! jmc 252: .It e
! 253: Display a list of system errors (if any) generated by the last
! 254: .Li kill
! 255: or
! 256: .Li renice
! 257: command.
! 258: .It i or I
! 259: Toggle the display of idle processes.
1.2 downsj 260: .It k
261: Send a signal
1.21 jmc 262: .Pf ( Dv TERM
1.13 aaron 263: by default) to a list of processes.
264: This acts similarly to the command
1.2 downsj 265: .Xr kill 1 .
1.23 ! jmc 266: .It n or #
! 267: Change the number of processes to display (prompt for new number).
! 268: .It o
! 269: Change the sorting order of the processes
! 270: .Pq prompt for order .
! 271: Values are the same as for the
! 272: .Fl o
! 273: flag, as detailed above.
1.2 downsj 274: .It r
275: Change the priority (the
276: .Em nice )
1.13 aaron 277: of a list of processes.
278: This acts similarly to the command
1.2 downsj 279: .Xr renice 8 .
1.23 ! jmc 280: .It s
! 281: Change the number of seconds to delay between displays
! 282: (prompt for new number).
! 283: .It S
! 284: Toggle the display of system processes.
1.2 downsj 285: .It u
1.1 downsj 286: Display only processes owned by a specific username (prompt for username).
1.2 downsj 287: If the username specified is simply
288: .Dq + ,
289: then processes belonging to all users will be displayed.
290: .El
291: .Sh THE DISPLAY
292: .\" The actual display varies depending on the specific variant of Unix
293: .\" that the machine is running. This description may not exactly match
294: .\" what is seen by top running on this particular machine. Differences
295: .\" are listed at the end of this manual entry.
296: .\" .Pp
1.1 downsj 297: The top few lines of the display show general information
298: about the state of the system, including
1.11 millert 299: .\" the last process ID assigned to a process,
1.2 downsj 300: .\" (on most systems),
1.1 downsj 301: the three load averages,
302: the current time,
303: the number of existing processes,
304: the number of processes in each state
305: (sleeping, running, starting, zombies, and stopped),
306: and a percentage of time spent in each of the processor states
307: (user, nice, system, and idle).
1.17 aaron 308: It also includes information about physical and virtual memory allocation.
1.2 downsj 309: .Pp
1.1 downsj 310: The remainder of the screen displays information about individual
1.13 aaron 311: processes.
312: This display is similar in spirit to
1.2 downsj 313: .Xr ps 1
1.13 aaron 314: but it is not exactly the same.
315: PID is the process ID, USERNAME is the name
1.1 downsj 316: of the process's owner (if
1.2 downsj 317: .Fl u
1.1 downsj 318: is specified, a UID column will be substituted for USERNAME),
319: PRI is the current priority of the process,
1.2 downsj 320: NICE is the nice amount (in the range -20 to 20),
1.1 downsj 321: SIZE is the total size of the process (text, data, and stack),
322: RES is the current amount of resident memory (both SIZE and RES are
323: given in kilobytes),
1.2 downsj 324: STATE is the current state (one of
325: .Li sleep ,
326: .Li WAIT ,
327: .Li run ,
328: .Li idl ,
329: .Li zomb ,
330: or
331: .Li stop ) ,
1.5 aaron 332: TIME is the number of system and user CPU seconds that the process has used,
333: WCPU, when displayed, is the weighted CPU percentage (this is the same
1.1 downsj 334: value that
1.2 downsj 335: .Xr ps 1
1.1 downsj 336: displays as CPU),
337: CPU is the raw percentage and is the field that is sorted to determine
338: the order of the processes, and
339: COMMAND is the name of the command that the process is currently running
1.2 downsj 340: (if the process is swapped out, this column is marked
341: .Li <swapped> ) .
342: .Sh NOTES
343: The
344: .Em ABANDONED
345: state (known in the kernel as
1.21 jmc 346: .Em SWAIT )
1.13 aaron 347: was abandoned, thus the name.
348: A process should never end up in this state.
1.2 downsj 349: .Sh ENVIRONMENT
350: .Bl -tag -width XxXXXX
351: .It Ev TOP
352: User-configurable defaults for options.
353: .El
354: .Sh FILES
355: .Bl -tag -width XxXXXXXXX -compact
356: .It Pa /dev/kmem
357: kernel memory
358: .It Pa /dev/mem
359: physical memory
360: .It Pa /bsd
361: kernel image
1.14 aaron 362: .El
1.13 aaron 363: .Sh SEE ALSO
364: .Xr kill 1 ,
365: .Xr ps 1 ,
366: .Xr stty 1 ,
367: .Xr systat 1 ,
368: .Xr mem 4 ,
369: .Xr renice 8
1.16 aaron 370: .Sh AUTHORS
371: William LeFebvre, EECS Department, Northwestern University
1.2 downsj 372: .Sh BUGS
1.1 downsj 373: Don't shoot me, but the default for
1.2 downsj 374: .Fl I
1.13 aaron 375: has changed once again.
376: So many people were confused by the fact that
1.2 downsj 377: .Nm
1.1 downsj 378: wasn't showing them all the processes that I have decided to make the
379: default behavior show idle processes, just like it did in version 2.
380: But to appease folks who can't stand that behavior, I have added the
1.2 downsj 381: ability to set
382: .Li default
383: options in the environment variable
384: .Ev TOP
385: (see the
386: .Sx OPTIONS
1.13 aaron 387: section).
388: Those who want the behavior that version 3.0 had need only set
1.2 downsj 389: the environment variable
390: .Ev TOP
391: to
392: .Li -I .
393: .Pp
1.1 downsj 394: The command name for swapped processes should be tracked down, but this
395: would make the program run slower.
1.2 downsj 396: .Pp
1.1 downsj 397: As with
1.2 downsj 398: .Xr ps 1 ,
1.1 downsj 399: things can change while
1.2 downsj 400: .Nm
1.13 aaron 401: is collecting information for an update.
402: The picture it gives is only a
1.1 downsj 403: close approximation to reality.
![[BACK]](/icons/back.gif){kind=icon}
Return to top.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / top