usr.bin/top/top.1

   1 .Dd November 18, 2021
   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 abCHIijnPpqSTtuvxz
  10 .Op Fl d Ar count
  11 .Op Fl J Ar jail
  12 .Op Fl m Ar mode
  13 .Op Fl o Ar field
  14 .Op Fl p Ar pid
  15 .Op Fl s Ar time
  16 .Op Fl U Ar uid
  17 .Op Ar number
  18 .Sh DESCRIPTION
  19 .Nm
  20 displays the top
  21 processes on the system and periodically updates this information.
  22 If standard output is an intelligent terminal (see below) then
  23 as many processes as will fit on the terminal screen are displayed
  24 by default.
  25 Otherwise, a good number of them are shown (around 20).
  26 Raw cpu percentage is used to rank the processes.
  27 If
  28 .Ar number
  29 is given, then the top
  30 .Ar number
  31 processes will be displayed instead of the default.
  32 .Pp
  33 .Nm
  34 makes a distinction between terminals that support advanced capabilities
  35 and those that do not.
  36 This distinction affects the choice of defaults for certain options.
  37 In the remainder of this document, an
  38 .Dq intelligent
  39 terminal is one that
  40 supports cursor addressing, clear screen, and clear to end of line.
  41 Conversely, a
  42 .Dq dumb
  43 terminal is one that does not support such
  44 features.
  45 If the output of
  46 .Nm
  47 is redirected to a file, it acts as if it were being run on a dumb
  48 terminal.
  49 .Pp
  50 The options are as follows:
  51 .Bl -tag -width indent
  52 .It Fl a
  53 Display command names derived from the argv[] vector, rather than real
  54 executable name.
  55 It it useful when you want to watch applications, that
  56 puts their status information there.
  57 If the real name differs from argv[0],
  58 it will be displayed in parenthesis.
  59 Non-printable characters in the command line are
  60 encoded in C-style backslash sequences or
  61 a three digit octal sequences.
  62 .It Fl b
  63 Use
  64 .Dq batch
  65 mode.
  66 In this mode, all input from the terminal is
  67 ignored.
  68 Interrupt characters (such as ^C and ^\e) still have an effect.
  69 This is the default on a dumb terminal, or when the output is not a terminal.
  70 .It Fl C
  71 Toggle CPU display mode.
  72 By default top displays the weighted CPU percentage in the WCPU column
  73 (this is the same value that
  74 .Xr ps 1
  75 displays as CPU).
  76 Each time
  77 .Fl C
  78 flag is passed it toggles between
  79 .Dq raw cpu
  80 mode and
  81 .Dq weighted cpu
  82 mode, showing the
  83 .Dq CPU
  84 or the
  85 .Dq WCPU
  86 column respectively.
  87 .It Fl d Ar count
  88 Show only
  89 .Ar count
  90 displays, then exit.
  91 A display is considered to be one update of the
  92 screen.
  93 The default is 1 for dumb terminals.
  94 Note that for
  95 .Ar count
  96 = 1
  97 no information is available about the percentage of time spent by the CPU in every state.
  98 .It Fl H
  99 Display each thread for a multithreaded process individually.
 100 By default a single summary line is displayed for each process.
 101 .It Fl I
 102 Do not display idle processes.
 103 By default, top displays both active and idle processes.
 104 .It Fl i
 105 Use
 106 .Dq interactive
 107 mode.
 108 In this mode, any input is immediately
 109 read for processing.
 110 See the section on
 111 .Dq Interactive Mode
 112 for an explanation of
 113 which keys perform what functions.
 114 After the command is processed, the
 115 screen will immediately be updated, even if the command was not
 116 understood.
 117 This mode is the default when standard output is an
 118 intelligent terminal.
 119 .It Fl J Ar jail
 120 Show only those processes owned by
 121 .Ar jail .
 122 This may be either the
 123 .Ar jid
 124 or
 125 .Ar name
 126 of the jail.
 127 Use
 128 0
 129 to limit to host processes.
 130 Using this option implies
 131 .Fl j .
 132 .It Fl j
 133 Display the
 134 .Xr jail 8
 135 ID.
 136 .It Fl m Ar mode
 137 Display statistics in the specified
 138 .Ar mode .
 139 Available modes are
 140 .Cm cpu
 141 and
 142 .Cm io .
 143 Default is
 144 .Cm cpu .
 145 .It Fl n
 146 Use
 147 .Dq non-interactive
 148 mode.
 149 This is identical to
 150 .Dq batch
 151 mode.
 152 .It Fl o Ar field
 153 Sort the process display area on the specified field.
 154 The field name
 155 is the name of the column as seen in the output, but in lower case:
 156 .Dq cpu ,
 157 .Dq size ,
 158 .Dq res ,
 159 .Dq time ,
 160 .Dq pri ,
 161 .Dq threads ,
 162 .Dq total ,
 163 .Dq read ,
 164 .Dq write ,
 165 .Dq fault ,
 166 .Dq vcsw ,
 167 .Dq ivcsw ,
 168 .Dq jid ,
 169 .Dq swap ,
 170 or
 171 .Dq pid .
 172 .It Fl P
 173 Display per-cpu CPU usage statistics.
 174 .It Fl p Ar pid
 175 Show only the process
 176 .Ar pid .
 177 .It Fl q
 178 Renice
 179 .Nm
 180 to -20 so that it will run faster.
 181 This can be used when the system is
 182 being very sluggish to improve the possibility of discovering the problem.
 183 This option can only be used by root.
 184 .It Fl S
 185 Show system processes in the display.
 186 Normally, system processes such as the pager and the swapper are not shown.
 187 This option makes them visible.
 188 .It Fl s Ar time
 189 Set the delay between screen updates to
 190 .Ar time
 191 seconds, which may be fractional.
 192 The default delay between updates is 1 second.
 193 .It Fl T
 194 Toggle displaying thread ID (tid) instead of process id (pid).
 195 .It Fl t
 196 Do not display the
 197 .Nm
 198 process itself.
 199 .It Fl U Ar username
 200 Show only those processes owned by
 201 .Ar username .
 202 This option currently only accepts usernames and will not understand
 203 uid numbers.
 204 .It Fl u
 205 Do not map uid numbers to usernames.
 206 Normally,
 207 .Nm
 208 will read as much of the file
 209 .Pa /etc/passwd
 210 as is necessary to map
 211 all the user id numbers it encounters into login names.
 212 This option disables all that, while possibly decreasing execution time.
 213 The uid numbers are displayed instead of the names.
 214 .It Fl v
 215 Write version number information to stderr then exit immediately.
 216 .It Fl w
 217 Display approximate swap usage for each process.
 218 .It Fl z
 219 Do not display the system idle process.
 220 .El
 221 .Pp
 222 Both
 223 .Ar count
 224 and
 225 .Ar number
 226 fields can be specified as
 227 .Dq infinite ,
 228 indicating that they can
 229 stretch as far as possible.
 230 This is accomplished by using any proper
 231 prefix of the keywords
 232 .Dq infinity ,
 233 .Dq maximum ,
 234 or
 235 .Dq all .
 236 Boolean flags are toggles.
 237 A second specification of any of these options will negate the first.
 238 .Sh "INTERACTIVE MODE"
 239 When
 240 .Nm
 241 is running in
 242 .Dq interactive mode ,
 243 it reads commands from the
 244 terminal and acts upon them accordingly.
 245 In this mode, the terminal is
 246 put in
 247 .Dq CBREAK ,
 248 so that a character will be
 249 processed as soon as it is typed.
 250 Almost always, a key will be
 251 pressed when
 252 .Nm
 253 is between displays; that is, while it is waiting for
 254 .Ar time
 255 seconds to elapse.
 256 If this is the case, the command will be
 257 processed and the display will be updated immediately thereafter
 258 (reflecting any changes that the command may have specified).
 259 This
 260 happens even if the command was incorrect.
 261 If a key is pressed while
 262 .Nm
 263 is in the middle of updating the display, it will finish the update and
 264 then process the command.
 265 Some commands require additional information,
 266 and the user will be prompted accordingly.
 267 While typing this information
 268 in, the user's erase and kill keys (as set up by the command
 269 .Xr stty 1 )
 270 are recognized, and a newline terminates the input.
 271 .Pp
 272 These commands are currently recognized (^L refers to control-L):
 273 .Bl -tag -width indent
 274 .It ^L
 275 Redraw the screen.
 276 .It h
 277 Display a summary of the commands (help screen).
 278 Version information
 279 is included in this display.
 280 .It q
 281 Quit
 282 .Nm
 283 .It d
 284 Change the number of displays to show (prompt for new number).
 285 Remember that the next display counts as one, so typing 'd1' will make
 286 .Nm
 287 show one final display and then immediately exit.
 288 .It /
 289 Display only processes that contain the specified string in their
 290 command name.
 291 If displaying arguments is enabled, the arguments are searched
 292 too. '+' shows all processes.
 293 .It m
 294 Toggle the display between 'cpu' and 'io' modes.
 295 .It n or #
 296 Change the number of processes to display (prompt for new number).
 297 .It s
 298 Change the number of seconds to delay between displays
 299 (prompt for new number).
 300 .It S
 301 Toggle the display of system processes.
 302 .It a
 303 Toggle the display of process titles.
 304 .It k
 305 Send a signal
 306 .Pq SIGKILL by default
 307 to a list of processes.
 308 This acts similarly to the command
 309 .Xr kill 1 .
 310 .It r
 311 Change the priority
 312 .Pq the Dq nice
 313 of a list of processes.
 314 This acts similarly to
 315 .Xr renice 8 .
 316 .It u
 317 Display only processes owned by a specific set of usernames (prompt for
 318 username).
 319 If the username specified is simply
 320 .Dq +
 321 or
 322 .Dq - ,
 323 then processes belonging to all users will be displayed.
 324 Usernames can be added
 325 to and removed from the set by prepending them with
 326 .Dq +
 327 and
 328 .Dq - ,
 329 respectively.
 330 .It o
 331 Change the order in which the display is sorted.
 332 The sort key names include
 333 .Dq cpu ,
 334 .Dq res ,
 335 .Dq size ,
 336 and
 337 .Dq time.
 338 The default is cpu.
 339 .It p
 340 Display a specific process (prompt for pid).
 341 If the pid specified is simply
 342 .Dq + ,
 343 then show all processes.
 344 .It e
 345 Display a list of system errors (if any) generated by the last
 346 command.
 347 .It H
 348 Toggle the display of threads.
 349 .It i or I
 350 Toggle the display of idle processes.
 351 .It j
 352 Toggle the display of
 353 .Xr jail 8
 354 ID.
 355 .It J
 356 Display only processes owned by a specific jail (prompt for jail).
 357 If the jail specified is simply
 358 .Dq + ,
 359 then processes belonging
 360 to all jails and the host will be displayed.
 361 This will also enable the display of JID.
 362 .It P
 363 Toggle the display of per-CPU statistics.
 364 .It T
 365 Toggle display of TID and PID
 366 .It t
 367 Toggle the display of the
 368 .Nm
 369 process.
 370 .It w
 371 Toggle the display of swap usage.
 372 .It z
 373 Toggle the display of the system idle process.
 374 .El
 375 .Sh "THE DISPLAY"
 376 The top few lines of the display show general information
 377 about the state of the system, including
 378 the last process id assigned to a process (on most systems),
 379 the three load averages,
 380 the current time,
 381 the number of existing processes,
 382 the number of processes in each state
 383 (sleeping, running, starting, zombies, and stopped),
 384 and a percentage of time spent in each of the processor states
 385 (user, nice, system, and idle).
 386 It also includes information about physical and virtual memory allocation.
 387 .Pp
 388 The remainder of the screen displays information about individual
 389 processes.
 390 This display is similar in spirit to
 391 .Xr ps 1
 392 but it is not exactly the same.
 393 PID is the process id,
 394 JID, when displayed, is the
 395 .Xr jail 8
 396 ID corresponding to the process,
 397 USERNAME is the name of the process's owner (if
 398 .Fl u
 399 is specified, a UID column will be substituted for USERNAME),
 400 PRI is the current priority of the process,
 401 NICE is the
 402 .Xr nice 1
 403 amount,
 404 SIZE is the total size of the process (text, data, and stack),
 405 RES is the current amount of resident memory,
 406 SWAP is the approximate amount of swap, if enabled
 407 (SIZE, RES and SWAP are given in kilobytes),
 408 STATE is the current state (one of
 409 .Dq START ,
 410 .Dq RUN
 411 (shown as
 412 .Dq CPUn
 413 on SMP systems),
 414 .Dq SLEEP ,
 415 .Dq STOP ,
 416 .Dq ZOMB ,
 417 .Dq WAIT ,
 418 .Dq LOCK ,
 419 or the event on which the process waits),
 420 C is the processor number on which the process is executing
 421 (visible only on SMP systems),
 422 TIME is the number of system and user cpu seconds that the process has used,
 423 WCPU, when displayed, is the weighted cpu percentage (this is the same
 424 value that
 425 .Xr ps 1
 426 displays as CPU),
 427 CPU is the raw percentage and is the field that is sorted to determine
 428 the order of the processes, and
 429 COMMAND is the name of the command that the process is currently running
 430 (if the process is swapped out, this column is marked
 431 .Dq <swapped> ) .
 432 .Pp
 433 If a process is in the
 434 .Dq SLEEP
 435 or
 436 .Dq LOCK
 437 state,
 438 the state column will report the name of the event or lock on which the
 439 process is waiting.
 440 Lock names are prefixed with an asterisk
 441 .Dq *
 442 while sleep events
 443 are not.
 444 .Sh DESCRIPTION OF MEMORY
 445 .Bd -literal
 446 Mem: 61M Active, 86M Inact, 368K Laundry, 22G Wired, 102G Free
 447 ARC: 15G Total, 9303M MFU, 6155M MRU, 1464K Anon, 98M Header, 35M Other
 448      15G Compressed, 27G Uncompressed, 1.75:1 Ratio, 174M Overhead
 449 Swap: 4096M Total, 532M Free, 13% Inuse, 80K In, 104K Out
 450 .Ed
 451 .Ss Physical Memory Stats
 452 .Bl -tag -width "Uncompressed" -compact
 453 .It Em Active
 454 number of bytes active
 455 .It Em Inact
 456 number of clean bytes inactive
 457 .It Em Laundry
 458 number of dirty bytes queued for laundering
 459 .It Em Wired
 460 number of bytes wired down, including IO-level cached file data pages
 461 .It Em Buf
 462 number of bytes used for IO-level disk caching
 463 .It Em Free
 464 number of bytes free
 465 .El
 466 .Ss ZFS ARC Stats
 467 These stats are only displayed when the ARC is in use.
 468 .Pp
 469 .Bl -tag -width "Uncompressed" -compact
 470 .It Em Total
 471 number of wired bytes used for the ZFS ARC
 472 .It Em MRU
 473 number of ARC bytes holding most recently used data
 474 .It Em MFU
 475 number of ARC bytes holding most frequently used data
 476 .It Em Anon
 477 number of ARC bytes holding in flight data
 478 .It Em Header
 479 number of ARC bytes holding headers
 480 .It Em Other
 481 miscellaneous ARC bytes
 482 .It Em Compressed
 483 bytes of memory used by ARC caches
 484 .It Em Uncompressed
 485 bytes of data stored in ARC caches before compression
 486 .It Em Ratio
 487 compression ratio of data cached in the ARC
 488 .El
 489 .Ss Swap Stats
 490 .Bl -tag -width "Uncompressed" -compact
 491 .It Em Total
 492 total available swap usage
 493 .It Em Free
 494 total free swap usage
 495 .It Em Inuse
 496 swap usage
 497 .It Em \&In
 498 bytes paged in from swap devices (last interval)
 499 .It Em Out
 500 bytes paged out to swap devices (last interval)
 501 .El
 502 .Sh ENVIRONMENT
 503 .Bl -tag -width "Uncompressed"
 504 .It Ev TOP
 505 Default set of arguments to
 506 .Nm .
 507 .It Ev LC_CTYPE
 508 The locale to use when displaying the
 509 .Va argv
 510 vector when
 511 .Fl a
 512 flag is specified.
 513 .El
 514 .Sh SEE ALSO
 515 .Xr kill 1 ,
 516 .Xr ps 1 ,
 517 .Xr stty 1 ,
 518 .Xr getrusage 2 ,
 519 .Xr humanize_number 3 ,
 520 .Xr mem 4 ,
 521 .Xr renice 8
 522 .Sh AUTHORS
 523 .An William LeFebvre, EECS Department, Northwestern University
 524 .Sh BUGS
 525 The command name for swapped processes should be tracked down, but this
 526 would make the program run slower.
 527 .Pp
 528 As with
 529 .Xr ps 1 ,
 530 things can change while
 531 .Nm
 532 is collecting information for an update.
 533 The picture it gives is only a close approximation to reality.