Annotation of src/usr.bin/top/top.1, Revision 1.1
1.1 ! downsj 1: .\" $OpenBSD$
! 2: .nr N 15
! 3: .nr D 5
! 4: .TH TOP 1 Local
! 5: .UC 4
! 6: .SH NAME
! 7: top \- display and update information about the top cpu processes
! 8: .SH SYNOPSIS
! 9: .B top
! 10: [
! 11: .B \-SbiInqu
! 12: ] [
! 13: .BI \-d count
! 14: ] [
! 15: .BI \-s time
! 16: ] [
! 17: .BI \-o field
! 18: ] [
! 19: .BI \-U username
! 20: ] [
! 21: .I number
! 22: ]
! 23: .SH DESCRIPTION
! 24: .\" This defines appropriate quote strings for nroff and troff
! 25: .ds lq \&"
! 26: .ds rq \&"
! 27: .if t .ds lq ``
! 28: .if t .ds rq ''
! 29: .\" Just in case these number registers aren't set yet...
! 30: .if \nN==0 .nr N 10
! 31: .if \nD==0 .nr D 5
! 32: .I Top
! 33: displays the top
! 34: .if !\nN==-1 \nN
! 35: processes on the system and periodically updates this information.
! 36: .if \nN==-1 \
! 37: \{\
! 38: If standard output is an intelligent terminal (see below) then
! 39: as many processes as will fit on the terminal screen are displayed
! 40: by default. Otherwise, a good number of them are shown (around 20).
! 41: .\}
! 42: Raw cpu percentage is used to rank the processes. If
! 43: .I number
! 44: is given, then the top
! 45: .I number
! 46: processes will be displayed instead of the default.
! 47: .PP
! 48: .I Top
! 49: makes a distinction between terminals that support advanced capabilities
! 50: and those that do not. This
! 51: distinction affects the choice of defaults for certain options. In the
! 52: remainder of this document, an \*(lqintelligent\*(rq terminal is one that
! 53: supports cursor addressing, clear screen, and clear to end of line.
! 54: Conversely, a \*(lqdumb\*(rq terminal is one that does not support such
! 55: features. If the output of
! 56: .I top
! 57: is redirected to a file, it acts as if it were being run on a dumb
! 58: terminal.
! 59: .SH OPTIONS
! 60: .TP
! 61: .B \-S
! 62: Show system processes in the display. Normally, system processes such as
! 63: the pager and the swapper are not shown. This option makes them visible.
! 64: .TP
! 65: .B \-b
! 66: Use \*(lqbatch\*(rq mode. In this mode, all input from the terminal is
! 67: ignored. Interrupt characters (such as ^C and ^\e) still have an effect.
! 68: This is the default on a dumb terminal, or when the output is not a terminal.
! 69: .TP
! 70: .B \-i
! 71: Use \*(lqinteractive\*(rq mode. In this mode, any input is immediately
! 72: read for processing. See the section on \*(lqInteractive Mode\*(rq
! 73: for an explanation of
! 74: which keys perform what functions. After the command is processed, the
! 75: screen will immediately be updated, even if the command was not
! 76: understood. This mode is the default when standard output is an
! 77: intelligent terminal.
! 78: .TP
! 79: .B \-I
! 80: Do not display idle processes.
! 81: By default, top displays both active and idle processes.
! 82: .TP
! 83: .B \-n
! 84: Use \*(lqnon-interactive\*(rq mode. This is indentical to \*(lqbatch\*(rq
! 85: mode.
! 86: .TP
! 87: .B \-q
! 88: Renice
! 89: .I top
! 90: to -20 so that it will run faster. This can be used when the system is
! 91: being very sluggish to improve the possibility of discovering the problem.
! 92: This option can only be used by root.
! 93: .TP
! 94: .B \-u
! 95: Do not take the time to map uid numbers to usernames. Normally,
! 96: .I top
! 97: will read as much of the file \*(lq/etc/passwd\*(rq as is necessary to map
! 98: all the user id numbers it encounters into login names. This option
! 99: disables all that, while possibly decreasing execution time. The uid
! 100: numbers are displayed instead of the names.
! 101: .TP
! 102: .BI \-d count
! 103: Show only
! 104: .I count
! 105: displays, then exit. A display is considered to be one update of the
! 106: screen. This option allows the user to select the number of displays he
! 107: wants to see before
! 108: .I top
! 109: automatically exits. For intelligent terminals, no upper limit
! 110: is set. The default is 1 for dumb terminals.
! 111: .TP
! 112: .BI \-s time
! 113: Set the delay between screen updates to
! 114: .I time
! 115: seconds. The default delay between updates is \nD seconds.
! 116: .TP
! 117: .BI \-o field
! 118: Sort the process display area on the specified field. The field name is
! 119: the name of the column as seen in the output, but in lower case. Likely
! 120: values are \*(lqcpu\*(rq, \*(lqsize\*(rq, \*(lqres\*(rq, and \*(lqtime\*(rq,
! 121: but may vary on different operating systems. Note that
! 122: not all operating systems support this option.
! 123: .TP
! 124: .BI \-U username
! 125: Show only those processes owned by
! 126: .IR username .
! 127: This option currently only accepts usernames and will not understand
! 128: uid numbers.
! 129: .PP
! 130: Both
! 131: .I count
! 132: and
! 133: .I number
! 134: fields can be specified as \*(lqinfinite\*(rq, indicating that they can
! 135: stretch as far as possible. This is accomplished by using any proper
! 136: prefix of the keywords
! 137: \*(lqinfinity\*(rq,
! 138: \*(lqmaximum\*(rq,
! 139: or
! 140: \*(lqall\*(rq.
! 141: The default for
! 142: .I count
! 143: on an intelligent terminal is, in fact,
! 144: .BI infinity .
! 145: .PP
! 146: The environment variable
! 147: .B TOP
! 148: is examined for options before the command line is scanned. This enables
! 149: a user to set his or her own defaults. The number of processes to display
! 150: can also be specified in the environment variable
! 151: .BR TOP .
! 152: The options
! 153: .BR \-I ,
! 154: .BR \-S ,
! 155: and
! 156: .B \-u
! 157: are actually toggles. A second specification of any of these options
! 158: will negate the first. Thus a user who has the environment variable
! 159: .B TOP
! 160: set to \*(lq\-I\*(rq may use the command \*(lqtop \-I\*(rq to see idle processes.
! 161: .SH "INTERACTIVE MODE"
! 162: When
! 163: .I top
! 164: is running in \*(lqinteractive mode\*(rq, it reads commands from the
! 165: terminal and acts upon them accordingly. In this mode, the terminal is
! 166: put in \*(lqCBREAK\*(rq, so that a character will be
! 167: processed as soon as it is typed. Almost always, a key will be
! 168: pressed when
! 169: .I top
! 170: is between displays; that is, while it is waiting for
! 171: .I time
! 172: seconds to elapse. If this is the case, the command will be
! 173: processed and the display will be updated immediately thereafter
! 174: (reflecting any changes that the command may have specified). This
! 175: happens even if the command was incorrect. If a key is pressed while
! 176: .I top
! 177: is in the middle of updating the display, it will finish the update and
! 178: then process the command. Some commands require additional information,
! 179: and the user will be prompted accordingly. While typing this information
! 180: in, the user's erase and kill keys (as set up by the command
! 181: .IR stty )
! 182: are recognized, and a newline terminates the input.
! 183: .PP
! 184: These commands are currently recognized (^L refers to control-L):
! 185: .TP
! 186: .B ^L
! 187: Redraw the screen.
! 188: .IP "\fBh\fP\ or\ \fB?\fP"
! 189: Display a summary of the commands (help screen).
! 190: .TP
! 191: .B q
! 192: Quit
! 193: .IR top.
! 194: .TP
! 195: .B d
! 196: Change the number of displays to show (prompt for new number).
! 197: Remember that the next display counts as one, so typing
! 198: .B d1
! 199: will make
! 200: .I top
! 201: show one final display and then immediately exit.
! 202: .TP
! 203: .B n or #
! 204: Change the number of processes to display (prompt for new number).
! 205: .TP
! 206: .B s
! 207: Change the number of seconds to delay between displays
! 208: (prompt for new number).
! 209: .TP
! 210: .B k
! 211: Send a signal (\*(lqkill\*(rq by default) to a list of processes. This
! 212: acts similarly to the command
! 213: .IR kill (1)).
! 214: .TP
! 215: .B r
! 216: Change the priority (the \*(lqnice\*(rq) of a list of processes.
! 217: This acts similarly to the command
! 218: .IR renice (8)).
! 219: .TP
! 220: .B u
! 221: Display only processes owned by a specific username (prompt for username).
! 222: If the username specified is simply \*(lq+\*(rq, then processes belonging
! 223: to all users will be displayed.
! 224: .TP
! 225: .B e
! 226: Display a list of system errors (if any) generated by the last
! 227: .BR k ill
! 228: or
! 229: .BR r enice
! 230: command.
! 231: .TP
! 232: .B i
! 233: (or
! 234: .BR I)
! 235: Toggle the display of idle processes.
! 236: .SH "THE DISPLAY"
! 237: The actual display varies depending on the specific variant of Unix
! 238: that the machine is running. This description may not exactly match
! 239: what is seen by top running on this particular machine. Differences
! 240: are listed at the end of this manual entry.
! 241: .PP
! 242: The top few lines of the display show general information
! 243: about the state of the system, including
! 244: the last process id assigned to a process (on most systems),
! 245: the three load averages,
! 246: the current time,
! 247: the number of existing processes,
! 248: the number of processes in each state
! 249: (sleeping, running, starting, zombies, and stopped),
! 250: and a percentage of time spent in each of the processor states
! 251: (user, nice, system, and idle).
! 252: It also includes information about physial and virtual memory allocation.
! 253: .PP
! 254: The remainder of the screen displays information about individual
! 255: processes. This display is similar in spirit to
! 256: .IR ps (1)
! 257: but it is not exactly the same. PID is the process id, USERNAME is the name
! 258: of the process's owner (if
! 259: .B \-u
! 260: is specified, a UID column will be substituted for USERNAME),
! 261: PRI is the current priority of the process,
! 262: NICE is the nice amount (in the range \-20 to 20),
! 263: SIZE is the total size of the process (text, data, and stack),
! 264: RES is the current amount of resident memory (both SIZE and RES are
! 265: given in kilobytes),
! 266: STATE is the current state (one of \*(lqsleep\*(rq, \*(lqWAIT\*(rq,
! 267: \*(lqrun\*(rq, \*(lqidl\*(rq, \*(lqzomb\*(rq, or \*(lqstop\*(rq),
! 268: TIME is the number of system and user cpu seconds that the process has used,
! 269: WCPU, when displayed, is the weighted cpu percentage (this is the same
! 270: value that
! 271: .IR ps (1)
! 272: displays as CPU),
! 273: CPU is the raw percentage and is the field that is sorted to determine
! 274: the order of the processes, and
! 275: COMMAND is the name of the command that the process is currently running
! 276: (if the process is swapped out, this column is marked \*(lq<swapped>\*(rq).
! 277: .SH NOTES
! 278: The \*(lqABANDONED\*(rq state (known in the kernel as \*(lqSWAIT\*(rq) was
! 279: abandoned, thus the name. A process should never end up in this state.
! 280: .SH AUTHOR
! 281: William LeFebvre, EECS Department, Northwestern University
! 282: .SH ENVIRONMENT
! 283: .DT
! 284: TOP user-configurable defaults for options.
! 285: .SH FILES
! 286: .DT
! 287: /dev/kmem kernel memory
! 288: .br
! 289: /dev/mem physical memory
! 290: .br
! 291: /bsd system image
! 292: .SH BUGS
! 293: Don't shoot me, but the default for
! 294: .B \-I
! 295: has changed once again. So many people were confused by the fact that
! 296: .I top
! 297: wasn't showing them all the processes that I have decided to make the
! 298: default behavior show idle processes, just like it did in version 2.
! 299: But to appease folks who can't stand that behavior, I have added the
! 300: ability to set \*(lqdefault\*(rq options in the environment variable
! 301: .B TOP
! 302: (see the OPTIONS section). Those who want the behavior that version
! 303: 3.0 had need only set the environment variable
! 304: .B TOP
! 305: to \*(lq\-I\*(rq.
! 306: .PP
! 307: The command name for swapped processes should be tracked down, but this
! 308: would make the program run slower.
! 309: .PP
! 310: As with
! 311: .IR ps (1),
! 312: things can change while
! 313: .I top
! 314: is collecting information for an update. The picture it gives is only a
! 315: close approximation to reality.
! 316: .SH "SEE ALSO"
! 317: kill(1),
! 318: ps(1),
! 319: stty(1),
! 320: mem(4),
! 321: 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