1.\" Copyright (c) 1984 through 2008, William LeFebvre 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 8.\" * Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 11.\" * Redistributions in binary form must reproduce the above 12.\" copyright notice, this list of conditions and the following disclaimer 13.\" in the documentation and/or other materials provided with the 14.\" distribution. 15.\" 16.\" * Neither the name of William LeFebvre nor the names of other 17.\" contributors may be used to endorse or promote products derived from 18.\" this software without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 23.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 24.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 25.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 26.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31.\" 32.Dd February 15, 2023 33.Dt TOP 1 34.Os 35.Sh NAME 36.Nm top 37.Nd display and update information about the top cpu processes 38.Sh SYNOPSIS 39.Nm 40.Op Fl CIMSTabcinqtuv 41.Op Fl d Ar count 42.Op Fl m Ar mode 43.Op Fl o Ar field 44.Op Fl s Ar time 45.Op Fl U Ar username 46.Op Ar number 47.Sh DESCRIPTION 48.Nm 49displays the top 50processes on the system and periodically updates this information. 51Raw cpu percentage is used to rank the processes. 52.Pp 53.Nm 54makes a distinction between terminals that support advanced capabilities 55and those that do not. 56This distinction affects the choice of defaults for certain options. 57In the remainder of this document, an 58.Dq intelligent 59terminal is one that 60supports cursor addressing, clear screen, and clear to end of line. 61Conversely, a 62.Dq dumb 63terminal is one that does not support such features. 64If the output of 65.Nm 66is redirected to a file, it acts as if it were being run on a dumb 67terminal. 68.Ss OPTIONS 69.Bl -tag -width "-U username" -offset indent 70.It Fl C 71Turn off the use of color in the display. 72.It Fl I 73Do not display idle processes. 74By default, top displays both active and idle processes. 75.It Fl M 76Enable multi-CPU display. 77.It Fl S 78Show system processes in the display. 79Normally, system processes such as the pager and the swapper are not shown. 80This option makes them visible. 81.It Fl T 82List all available color tags and the current set of tests used for 83color highlighting, then exit. 84.It Fl a 85Show all processes for as long as possible. 86This is shorthand for 87.Dq Fl d Li all Li all . 88This option is especially handy in batch mode. 89.It Fl b 90Use 91.Dq batch 92mode. 93In this mode, all input from the terminal is ignored. 94Interrupt characters (such as ^C and ^\e) still have an effect. 95This is the default on a dumb terminal, or when the output is not a terminal. 96.It Fl c 97Show the full command line for each process. 98Default is to show just the command name. 99This option is not supported on all platforms. 100.It Fl i 101Use 102.Dq interactive 103mode. 104In this mode, any input is immediately read for processing. 105See the subsection on 106.Sx INTERACTIVE MODE 107for an explanation of which keys perform what functions. 108After the command is processed, the screen will immediately be updated, 109even if the command was not understood. 110This mode is the default when standard output is an intelligent terminal. 111.It Fl q 112Renice 113.Nm 114to \-20 so that it will run faster. 115This can be used when the system is being very sluggish to improve the 116possibility of discovering the problem. 117This option can only be used by root. 118.It Fl t 119Show individual threads on separate lines. 120By default, on systems which support threading, each process is shown 121with a count of the number of threads. 122This option shows each thread on a separate line. 123This option is not supported on all platforms. 124.It Fl u 125Do not take the time to map uid numbers to usernames. 126Normally, 127.Nm 128will read as much of the file 129.Pa /etc/passwd 130as is necessary to map all the user id numbers it encounters into login names. 131This option disables all that, while possibly decreasing execution time. 132The uid numbers are displayed instead of the names. 133.It Fl v 134Write version number information to stderr then exit immediately. 135No other processing takes place when this option is used. 136To see current revision information while top is running, 137use the help command 138.Dq \&? . 139.It Fl d Ar count 140Show only 141.Ar count 142displays, then exit. 143A display is considered to be one update of the screen. 144This option allows the user to select the number of displays he 145wants to see before 146.Nm 147automatically exits. 148Any proper prefix of the words 149.Sq Li infinity , 150.Sq Li maximum , 151or 152.Sq Li all 153can be used to indicate an infinite number of displays. 154The default for intelligent terminals is 155.Sq Li infinity . 156The default for dumb terminals is 157.Sq Li 1 . 158.It Fl m Ar mode 159Start the display in an alternate mode. 160Some platforms support multiple 161process displays to show additional process information. 162The value of 163.Ar mode 164is a number indicating which mode to display. 165The default is 166.Sq Li 0 . 167On platforms that do not have multiple display modes this option has 168no effect. 169.It Fl o Ar field 170Sort the process display area on the specified field. 171The field name is the name of the column as seen in the output, 172but in lower case. 173Likely values are 174.Sq Li cpu , 175.Sq Li size , 176.Sq Li res , 177and 178.Sq Li time , 179but may vary on different operating systems. 180Note that not all operating systems support this option. 181.It Fl s Ar time 182Set the delay between screen updates to 183.Ar time 184seconds. 185The default delay between updates is 5 seconds. 186.It Fl U Ar username 187Show only those processes owned by 188.Ar username . 189This option currently only accepts usernames and will not understand 190uid numbers. 191.El 192.Pp 193If 194.Ar number 195is given, then the top 196.Ar number 197processes will be displayed instead of the default. 198Both 199.Ar count 200and 201.Ar number 202fields can be specified as 203.Sq Li infinite , 204indicating that they can stretch as far as possible. 205This is accomplished by using any proper prefix of the keywords 206.Sq Li infinity , 207.Sq Li maximum , 208or 209.Sq Li all . 210The default for 211.Ar count 212on an intelligent terminal is, in fact, 213.Sq Li infinity . 214.Ss INTERACTIVE MODE 215When 216.Nm 217is running in 218.Dq interactive mode , 219it reads commands from the terminal and acts upon them accordingly. 220In this mode, the terminal is put in 221.Dq CBREAK , 222so that a character will be processed as soon as it is typed. 223Almost always, a key will be pressed when 224.Nm 225is between displays; that is, while it is waiting for 226.Ar time 227seconds to elapse. 228If this is the case, the command will be 229processed and the display will be updated immediately thereafter 230(reflecting any changes that the command may have specified). 231This happens even if the command was incorrect. 232If a key is pressed while 233.Nm 234is in the middle of updating the display, it will finish the update and 235then process the command. 236Some commands require additional information, 237and the user will be prompted accordingly. 238While typing this information 239in, the user's erase and kill keys (as set up by the command 240.Xr stty 1 ) 241are recognized, and a newline terminates the input. 242Note that a control\-L 243(^L) always redraws the current screen and a space forces an immediate 244update to the screen using new data. 245.Pp 246These commands are currently recognized: 247.Bl -tag -width "h or \&?" -offset indent 248.It h or \&? 249Display a summary of the commands (help screen). 250Version information is included in this display. 251.It C 252Toggle the use of color in the display. 253.It c 254Display only processes whose commands match the specified string. 255An empty string will display all processes. 256This command is not supported on all platforms. 257.It d 258Change the number of displays to show (prompt for new number). 259Remember that the next display counts as one, so typing 260.Dq d1 261will make 262.Nm 263show one final display and then immediately exit. 264.It f 265Toggle the display of the full command line. 266.It H 267Toggle the display of threads on separate lines. 268By default, on systems which support threading, 269each process is shown with a count of the number of threads. 270This command shows each thread on a separate line. 271This command is not supported on all platforms. 272.It i or I 273Toggle the display of idle processes. 274.It k 275Send a signal ( 276.Dq kill 277by default) to a list of processes. 278This acts similarly to the command 279.Xr kill 1 . 280.It M 281Sort display by memory usage. 282Shorthand for 283.Dq Fl o Li size . 284.It m 285Change to a different process display mode. 286Some systems provide multiple 287display modes for the process display which shows different information. 288This command toggles between the available modes. 289This command is not supported on all platforms. 290.It N 291Sort by process id. 292Shorthand for 293.Dq Fl o Li pid . 294.It n or # 295Change the number of processes to display (prompt for new number). 296.It o 297Change the order in which the display is sorted. 298This command is not available on all systems. 299The sort key names vary fron system to system, 300but usually include: 301.Sq Li cpu , 302.Sq Li res , 303.Sq Li size , 304and 305.Sq Li time . 306The default is 307.Sq Li cpu . 308.It P 309Sort by CPU usage. 310Shorthand for 311.Dq Fl o Li cpu . 312.It q 313Quit 314.Nm . 315.It r 316Change the priority (the niceness) of a list of processes. 317This acts similarly to the command 318.Xr renice 8 . 319.It s 320Change the number of seconds to delay between displays 321(prompt for new number). 322.It T 323Sort by CPU time. 324Shorthand for 325.Dq Fl o Li time . 326.It U 327Toggle between displaying usernames and uids. 328.It u 329Display only processes owned by a specific username (prompt for username). 330If the username specified is simply 331.Dq + , 332then processes belonging to all users will be displayed. 333.El 334.Ss THE DISPLAY 335The actual display varies depending on the specific variant of Unix 336that the machine is running. 337This description may not exactly match what is seen by top running on 338this particular machine. 339Differences are listed at the end of this manual entry. 340.Pp 341The top lines of the display show general information 342about the state of the system. 343The first line shows 344(on some systems) the last process id assigned to a process, 345the three load averages, 346the system uptime, and the current time. 347The second line displays the total number of processes followed 348by a breakdown of processes per state. 349Examples of states common to Unix systems are sleeping, running, starting, 350stopped, zombie, and dumping (i.e., generating a core). 351The next line displays a percentage of time spent in each of the 352processor states (user, nice, system, interrupt, idle). 353These percentages show the processor activity during the time since 354the last update. 355For multi-processor systems, this information is an average of all processors. 356The next line shows kernel-related activity (not available on all systems). 357The numbers shown on this line are per-second rates sampled since the last 358update. 359The exact information displayed varies between systems, but some examples are: 360context switches, interrupts, traps, forks, and page faults. 361.Pp 362The last two lines show a summary of memory and swap activity. 363The fields are as follows: 364.Bl -tag -width "Active:" -offset indent 365.It Active: 366number of pages active 367.It Inact: 368number of pages inactive 369.It Wired: 370number of pages wired down, including cached file data pages 371.It Cache: 372number of pages used for VM-level disk caching 373.It Buf: 374number of pages used for BIO-level disk caching 375.It Free: 376number of pages free 377.It Total: 378total available swap usage 379.It Free: 380total free swap usage 381.It Inuse: 382swap usage 383.It In: 384pages paged in from swap devices (last interval) 385.It Out: 386pages paged out to swap devices (last interval) 387.It K: 388Kilobyte 389.It M: 390Megabyte 391.It %: 3921/100 393.El 394.Pp 395The remainder of the screen displays information about individual 396processes. 397This display is similar in spirit to 398.Xr ps 1 , 399but it is not exactly the same. 400The columns displayed by top will differ slightly between operating systems. 401Generally, the following fields are displayed: 402.Bl -tag -width "USERNAME" -offset indent 403.It PID 404The process id. 405.It USERNAME 406Username of the process's owner (if 407.Fl u 408is specified, a UID column will be substituted for USERNAME). 409.It NICE 410Nice amount in the range \-20 to 20, as established by the use of 411the command 412.Xr nice 1 . 413.It SIZE 414Total size of the process (text, data, and stack) given in kilobytes. 415.It RES 416Resident memory: current amount of process memory that resides in physical 417memory, given in kilobytes, megabytes or gigabytes depending on the size to be reported. 418.It STATE 419Current state, may be: 420.Sq START , 421.Sq RUN 422(shown as 423.Sq CPUn 424on SMP systems), 425.Sq SLEEP 426(generally shown as the event on which the process waits), 427.Sq STOP , 428.Sq ZOMBIE , 429or 430.Sq DUMP . 431.It C 432Number of CPU the process is currently running on (only on multi-CPU machines). 433.It TIME 434Number of system and user cpu seconds that the process has used. 435.It CTIME 436The cumulated CPU time of the process and its exited children. 437This value is similar to what 438.Xr ps 1 439displays as CPU time when run with the 440.Fl S 441option. 442.It CPU 443Percentage of available cpu time used by this process. 444.It COMMAND 445Name of the command that the process is currently running. 446.El 447.Ss COLOR 448Top supports the use of ANSI color in its output. 449By default, color is available but not used. 450The environment variable 451.Ev TOPCOLORS 452specifies colors to use and conditions for which they should be used. 453At the present time, only numbers in the summary display area can be 454colored. 455In a future version it will be possible to highlight numbers 456in the process display area as well. 457The environment variable is the only way to specify color: 458there is no equivalent command line option. 459Note that the environment variable 460.Ev TOPCOLOURS 461is also understood. 462The British spelling takes precedence. 463The use of color only works on terminals that understand and process 464ANSI color escape sequences. 465.Pp 466You can see a list of color codes recognized by this installation of top 467with the 468.Fl T 469option. 470This will also show the current set of tests used for 471color highligting, as specified in the environment. 472.Sh ENVIRONMENT 473The following environment variables affect the execution of 474.Nm : 475.Bl -tag -width "TOPCOLORS" 476.It Ev TOP 477The environment variable 478.Ev TOP 479is examined for options before the command line is scanned. 480This enables a user to set his or her own defaults. 481The number of processes to display 482can also be specified in the environment variable 483.Ev TOP . 484The options 485.Dq Fl C , 486.Dq Fl I , 487.Dq Fl S , 488and 489.Dq Fl u 490are actually toggles. 491A second specification of any of these options will negate the first. 492Thus a user who has the environment variable 493.Ev TOP 494set to 495.Dq Fl I 496may use the command 497.Dq Nm Fl I 498to see idle processes. 499.It Ev TOPCOLORS 500The environment variable is a sequence of color specifications, separated 501by colons. 502Each specification takes the form tag=min,max#code where 503.Li tag 504is the name of the value to check, 505.Li min 506and 507.Li max 508specify a range for the value, and 509.Li code 510is an ANSI color code. 511Multiple color codes can be listed and separated with semi-colons. 512A missing 513.Li min 514implies the lowest possible value (usually 0) 515and a missing 516.Li max 517implies infinity. 518The comma must always be present. 519When specifying numbers for load averages, they should be multiplied by 100. 520For example, the specification 521.Li 1min=500,1000#31 522indicates that a 1 minute load average between 5235 and 10 should be displayed in red. 524Color attributes can be combined. 525For example, the specification 526.Li 5min=1000,#37;41 527indicates that a 5 minute load average higher than 10 should be displayed 528with white characters on a red background. 529A special tag named 530.Li header 531is used to control the color of the header for process display. 532It should be specified with no lower and upper limits, specifically 533.Li header=,# 534followed by the ANSI color code. 535.El 536.Sh SEE ALSO 537.Xr kill 1 , 538.Xr ps 1 , 539.Xr stty 1 , 540.Xr mem 4 , 541.Xr renice 8 542.Sh AUTHORS 543.An William LeFebvre 544.Sh BUGS 545As with 546.Xr ps 1 , 547things can change while 548.Nm 549is collecting information for an update. 550The picture it gives is only a close approximation to reality. 551.\" .Sh COPYRIGHT 552.\" Copyright (C) 1984-2007 William LeFebvre. 553.\" For additional licensing information, see 554.\" http://www.unixtop.org/license/ 555