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