usr.bin/top/top.1

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