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