Annotation of src/usr.bin/top/top.1, Revision 1.2
1.2 ! downsj 1: .\" $OpenBSD: top.1,v 1.1 1997/08/14 14:00:25 downsj Exp $
! 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
! 38: .Nd display and update information about the top cpu processes
! 39: .Sh SYNOPSIS
! 40: .Nm
! 41: .Op Fl SbiInqu
! 42: .Op Fl d Ar count
! 43: .Op Fl s Ar time
! 44: .\" .Op Fl o Ar field
! 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).
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
! 99: mode. This is indentical to
! 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.1 downsj 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.1 downsj 112: all the user id numbers it encounters into login names. This option
113: disables all that, while possibly decreasing execution time. The uid
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
119: screen. This option allows the user to select the number of displays he
120: wants to see 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.
! 128: .\" .It Fl o Ar field
! 129: .\" Sort the process display area on the specified field. The field name is
! 130: .\" the name of the column as seen in the output, but in lower case. Likely
! 131: .\" values are
! 132: .\" .Ar cpu ,
! 133: .\" .Ar size ,
! 134: .\" .Ar res ,
! 135: .\" and
! 136: .\" .Ar time ,
! 137: .\" but may vary on different operating systems. Note that
! 138: .\" not all operating systems support this option.
! 139: .It Fl U Ar username
1.1 downsj 140: Show only those processes owned by
1.2 ! downsj 141: .Ar username .
1.1 downsj 142: This option currently only accepts usernames and will not understand
143: uid numbers.
1.2 ! downsj 144: .El
! 145: .Pp
1.1 downsj 146: Both
1.2 ! downsj 147: .Ar count
1.1 downsj 148: and
1.2 ! downsj 149: .Ar number
! 150: fields can be specified as
! 151: .Li infinite ,
! 152: indicating that they can stretch as far as possible. This is accomplished
! 153: by using any proper prefix of the keywords
! 154: .Li infinity ,
! 155: .Li maximum ,
1.1 downsj 156: or
1.2 ! downsj 157: .Li all .
1.1 downsj 158: The default for
1.2 ! downsj 159: .Ar count
1.1 downsj 160: on an intelligent terminal is, in fact,
1.2 ! downsj 161: .Li infinity .
! 162: .Pp
1.1 downsj 163: The environment variable
1.2 ! downsj 164: .Ev TOP
1.1 downsj 165: is examined for options before the command line is scanned. This enables
166: a user to set his or her own defaults. The number of processes to display
167: can also be specified in the environment variable
1.2 ! downsj 168: .Ev TOP .
! 169: .Pp
1.1 downsj 170: The options
1.2 ! downsj 171: .Fl I ,
! 172: .Fl S ,
1.1 downsj 173: and
1.2 ! downsj 174: .Fl u
1.1 downsj 175: are actually toggles. A second specification of any of these options
176: will negate the first. Thus a user who has the environment variable
1.2 ! downsj 177: .Ev TOP
! 178: set to
! 179: .Li -I
! 180: may use the command
! 181: .Li top -I
! 182: to see idle processes.
! 183: .Sh INTERACTIVE MODE
1.1 downsj 184: When
1.2 ! downsj 185: .Nm
! 186: is running in
! 187: .Em interactive mode ,
! 188: it reads commands from the terminal and acts upon them accordingly. In this
! 189: mode, the terminal is put in
! 190: .Dv CBREAK ,
! 191: so that a character will be processed as soon as it is typed. Almost always,
! 192: a key will be pressed when
! 193: .Nm
1.1 downsj 194: is between displays; that is, while it is waiting for
1.2 ! downsj 195: .Ar time
1.1 downsj 196: seconds to elapse. If this is the case, the command will be
197: processed and the display will be updated immediately thereafter
198: (reflecting any changes that the command may have specified). This
199: happens even if the command was incorrect. If a key is pressed while
1.2 ! downsj 200: .Nm
1.1 downsj 201: is in the middle of updating the display, it will finish the update and
202: then process the command. Some commands require additional information,
203: and the user will be prompted accordingly. While typing this information
204: in, the user's erase and kill keys (as set up by the command
1.2 ! downsj 205: .Xr stty 1 )
1.1 downsj 206: are recognized, and a newline terminates the input.
1.2 ! downsj 207: .Pp
1.1 downsj 208: These commands are currently recognized (^L refers to control-L):
1.2 ! downsj 209: .Bl -tag -width XxXXXX
! 210: .It ^L
1.1 downsj 211: Redraw the screen.
1.2 ! downsj 212: .It h or ?
1.1 downsj 213: Display a summary of the commands (help screen).
1.2 ! downsj 214: .It q
1.1 downsj 215: Quit
1.2 ! downsj 216: .Nm top .
! 217: .It d
1.1 downsj 218: Change the number of displays to show (prompt for new number).
219: Remember that the next display counts as one, so typing
1.2 ! downsj 220: .Li d1
1.1 downsj 221: will make
1.2 ! downsj 222: .Nm
1.1 downsj 223: show one final display and then immediately exit.
1.2 ! downsj 224: .It n or #
1.1 downsj 225: Change the number of processes to display (prompt for new number).
1.2 ! downsj 226: .It s
1.1 downsj 227: Change the number of seconds to delay between displays
228: (prompt for new number).
1.2 ! downsj 229: .It k
! 230: Send a signal
! 231: .Ns ( Dv TERM
! 232: by default) to a list of processes. This acts similarly to the command
! 233: .Xr kill 1 .
! 234: .It r
! 235: Change the priority (the
! 236: .Em nice )
! 237: of a list of processes. This acts similarly to the command
! 238: .Xr renice 8 .
! 239: .It u
1.1 downsj 240: Display only processes owned by a specific username (prompt for username).
1.2 ! downsj 241: If the username specified is simply
! 242: .Dq + ,
! 243: then processes belonging to all users will be displayed.
! 244: .It e
1.1 downsj 245: Display a list of system errors (if any) generated by the last
1.2 ! downsj 246: .Li kill
1.1 downsj 247: or
1.2 ! downsj 248: .Li renice
1.1 downsj 249: command.
1.2 ! downsj 250: .It i or I
1.1 downsj 251: Toggle the display of idle processes.
1.2 ! downsj 252: .El
! 253: .Sh THE DISPLAY
! 254: .\" The actual display varies depending on the specific variant of Unix
! 255: .\" that the machine is running. This description may not exactly match
! 256: .\" what is seen by top running on this particular machine. Differences
! 257: .\" are listed at the end of this manual entry.
! 258: .\" .Pp
1.1 downsj 259: The top few lines of the display show general information
260: about the state of the system, including
1.2 ! downsj 261: the last process id assigned to a process
! 262: .\" (on most systems),
1.1 downsj 263: the three load averages,
264: the current time,
265: the number of existing processes,
266: the number of processes in each state
267: (sleeping, running, starting, zombies, and stopped),
268: and a percentage of time spent in each of the processor states
269: (user, nice, system, and idle).
270: It also includes information about physial and virtual memory allocation.
1.2 ! downsj 271: .Pp
1.1 downsj 272: The remainder of the screen displays information about individual
273: processes. This display is similar in spirit to
1.2 ! downsj 274: .Xr ps 1
1.1 downsj 275: but it is not exactly the same. PID is the process id, USERNAME is the name
276: of the process's owner (if
1.2 ! downsj 277: .Fl u
1.1 downsj 278: is specified, a UID column will be substituted for USERNAME),
279: PRI is the current priority of the process,
1.2 ! downsj 280: NICE is the nice amount (in the range -20 to 20),
1.1 downsj 281: SIZE is the total size of the process (text, data, and stack),
282: RES is the current amount of resident memory (both SIZE and RES are
283: given in kilobytes),
1.2 ! downsj 284: STATE is the current state (one of
! 285: .Li sleep ,
! 286: .Li WAIT ,
! 287: .Li run ,
! 288: .Li idl ,
! 289: .Li zomb ,
! 290: or
! 291: .Li stop ) ,
1.1 downsj 292: TIME is the number of system and user cpu seconds that the process has used,
293: WCPU, when displayed, is the weighted cpu percentage (this is the same
294: value that
1.2 ! downsj 295: .Xr ps 1
1.1 downsj 296: displays as CPU),
297: CPU is the raw percentage and is the field that is sorted to determine
298: the order of the processes, and
299: COMMAND is the name of the command that the process is currently running
1.2 ! downsj 300: (if the process is swapped out, this column is marked
! 301: .Li <swapped> ) .
! 302: .Sh NOTES
! 303: The
! 304: .Em ABANDONED
! 305: state (known in the kernel as
! 306: .Em SWAIT
! 307: was abandoned, thus the name. A process should never end up in this state.
! 308: .Sh AUTHOR
1.1 downsj 309: William LeFebvre, EECS Department, Northwestern University
1.2 ! downsj 310: .Sh ENVIRONMENT
! 311: .Bl -tag -width XxXXXX
! 312: .It Ev TOP
! 313: User-configurable defaults for options.
! 314: .El
! 315: .Sh FILES
! 316: .Bl -tag -width XxXXXXXXX -compact
! 317: .It Pa /dev/kmem
! 318: kernel memory
! 319: .It Pa /dev/mem
! 320: physical memory
! 321: .It Pa /bsd
! 322: kernel image
! 323: .Sh BUGS
1.1 downsj 324: Don't shoot me, but the default for
1.2 ! downsj 325: .Fl I
1.1 downsj 326: has changed once again. So many people were confused by the fact that
1.2 ! downsj 327: .Nm
1.1 downsj 328: wasn't showing them all the processes that I have decided to make the
329: default behavior show idle processes, just like it did in version 2.
330: But to appease folks who can't stand that behavior, I have added the
1.2 ! downsj 331: ability to set
! 332: .Li default
! 333: options in the environment variable
! 334: .Ev TOP
! 335: (see the
! 336: .Sx OPTIONS
! 337: section). Those who want the behavior that version 3.0 had need only set
! 338: the environment variable
! 339: .Ev TOP
! 340: to
! 341: .Li -I .
! 342: .Pp
1.1 downsj 343: The command name for swapped processes should be tracked down, but this
344: would make the program run slower.
1.2 ! downsj 345: .Pp
1.1 downsj 346: As with
1.2 ! downsj 347: .Xr ps 1 ,
1.1 downsj 348: things can change while
1.2 ! downsj 349: .Nm
1.1 downsj 350: is collecting information for an update. The picture it gives is only a
351: close approximation to reality.
1.2 ! downsj 352: .Sh SEE ALSO
! 353: .Xr kill 1 ,
! 354: .Xr ps 1 ,
! 355: .Xr stty 1 ,
! 356: .Xr mem 4 ,
! 357: .Xr renice 8 .
![[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