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