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