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