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