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