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