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