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