124139Sjoerg.\" NOTE: changes to the manual page for "top" should be made in the 224139Sjoerg.\" file "top.X" and NOT in the file "top.1". 363653Sphantom.\" $FreeBSD: stable/11/contrib/top/top.xs 322509 2017-08-14 15:08:49Z gahr $ 424139Sjoerg.nr N %topn% 524139Sjoerg.nr D %delay% 624139Sjoerg.TH TOP 1 Local 724139Sjoerg.UC 4 824139Sjoerg.SH NAME 924139Sjoergtop \- display and update information about the top cpu processes 1024139Sjoerg.SH SYNOPSIS 1124139Sjoerg.B top 1224139Sjoerg[ 13307757Sdes.B \-abCHIijnPqStuvwz 1424139Sjoerg] [ 1524139Sjoerg.BI \-d count 1624139Sjoerg] [ 17157842Sru.BI \-m io | cpu 1824139Sjoerg] [ 1924139Sjoerg.BI \-o field 2024139Sjoerg] [ 21157842Sru.BI \-s time 22157842Sru] [ 23265249Sbdrewery.BI \-J jail 24265249Sbdrewery] [ 2524139Sjoerg.BI \-U username 2624139Sjoerg] [ 2724139Sjoerg.I number 2824139Sjoerg] 2924139Sjoerg.SH DESCRIPTION 3024139Sjoerg.\" This defines appropriate quote strings for nroff and troff 3124139Sjoerg.ds lq \&" 3224139Sjoerg.ds rq \&" 3324139Sjoerg.if t .ds lq `` 3424139Sjoerg.if t .ds rq '' 3524139Sjoerg.\" Just in case these number registers aren't set yet... 3624139Sjoerg.if \nN==0 .nr N 10 3763653Sphantom.if \nD==0 .nr D 2 3824139Sjoerg.I Top 3924139Sjoergdisplays the top 4024139Sjoerg.if !\nN==-1 \nN 4124139Sjoergprocesses on the system and periodically updates this information. 4224139Sjoerg.if \nN==-1 \ 4324139Sjoerg\{\ 4424139SjoergIf standard output is an intelligent terminal (see below) then 4524139Sjoergas many processes as will fit on the terminal screen are displayed 4624139Sjoergby default. Otherwise, a good number of them are shown (around 20). 4724139Sjoerg.\} 4824139SjoergRaw cpu percentage is used to rank the processes. If 4924139Sjoerg.I number 5024139Sjoergis given, then the top 5124139Sjoerg.I number 5224139Sjoergprocesses will be displayed instead of the default. 5324139Sjoerg.PP 5424139Sjoerg.I Top 5524139Sjoergmakes a distinction between terminals that support advanced capabilities 5624139Sjoergand those that do not. This 5724139Sjoergdistinction affects the choice of defaults for certain options. In the 5824139Sjoergremainder of this document, an \*(lqintelligent\*(rq terminal is one that 5924139Sjoergsupports cursor addressing, clear screen, and clear to end of line. 6024139SjoergConversely, a \*(lqdumb\*(rq terminal is one that does not support such 6124139Sjoergfeatures. If the output of 6224139Sjoerg.I top 6324139Sjoergis redirected to a file, it acts as if it were being run on a dumb 6424139Sjoergterminal. 6524139Sjoerg.SH OPTIONS 6624139Sjoerg.TP 67157865Skeramida.B \-C 68157865SkeramidaToggle CPU display mode. 69157865SkeramidaBy default top displays the weighted CPU percentage in the WCPU column 70157865Skeramida(this is the same value that 71157865Skeramida.IR ps (1) 72157865Skeramidadisplays as CPU). 73157865SkeramidaEach time 74157865Skeramida.B \-C 75157865Skeramidaflag is passed it toggles between \*(lqraw cpu\*(rq mode 76157865Skeramidaand \*(lqweighted cpu\*(rq mode, showing the \*(lqCPU\*(rq or 77157865Skeramidathe \*(lqWCPU\*(rq column respectively. 78157865Skeramida.TP 7924139Sjoerg.B \-S 8024139SjoergShow system processes in the display. Normally, system processes such as 8124139Sjoergthe pager and the swapper are not shown. This option makes them visible. 8224139Sjoerg.TP 83168710Sstas.B \-a 84168710SstasDisplay command names derived from the argv[] vector, rather than real 85168710Sstasexecutable name. It's useful when you want to watch applications, that 86168710Sstasputs their status information there. If the real name differs from argv[0], 87168710Sstasit will be displayed in parenthesis. 88168710Sstas.TP 8924139Sjoerg.B \-b 9024139SjoergUse \*(lqbatch\*(rq mode. In this mode, all input from the terminal is 9124139Sjoergignored. Interrupt characters (such as ^C and ^\e) still have an effect. 9224139SjoergThis is the default on a dumb terminal, or when the output is not a terminal. 9324139Sjoerg.TP 94222532Sjhb.B \-H 95222532SjhbDisplay each thread for a multithreaded process individually. 96222532SjhbBy default a single summary line is displayed for each process. 97222532Sjhb.TP 9824139Sjoerg.B \-i 9924139SjoergUse \*(lqinteractive\*(rq mode. In this mode, any input is immediately 10024139Sjoergread for processing. See the section on \*(lqInteractive Mode\*(rq 10124139Sjoergfor an explanation of 10224139Sjoergwhich keys perform what functions. After the command is processed, the 10324139Sjoergscreen will immediately be updated, even if the command was not 10424139Sjoergunderstood. This mode is the default when standard output is an 10524139Sjoergintelligent terminal. 10624139Sjoerg.TP 10724139Sjoerg.B \-I 10824139SjoergDo not display idle processes. 10924139SjoergBy default, top displays both active and idle processes. 11024139Sjoerg.TP 111168799Srafan.B \-j 112168799SrafanDisplay the 113168799Srafan.IR jail (8) 114169257SrafanID. 115168799Srafan.TP 11638090Sdes.B \-t 11738090SdesDo not display the 11838090Sdes.I top 11938090Sdesprocess. 12038090Sdes.TP 121131402Salfred.BI \-m display 122131402SalfredDisplay either 'cpu' or 'io' statistics. Default is 'cpu'. 123131402Salfred.TP 12424139Sjoerg.B \-n 12528935SjmgUse \*(lqnon-interactive\*(rq mode. This is identical to \*(lqbatch\*(rq 12624139Sjoergmode. 12724139Sjoerg.TP 128179911Sru.B \-P 129179911SruDisplay per-cpu CPU usage statistics. 130179911Sru.TP 13124139Sjoerg.B \-q 13224139SjoergRenice 13324139Sjoerg.I top 13424139Sjoergto -20 so that it will run faster. This can be used when the system is 13524139Sjoergbeing very sluggish to improve the possibility of discovering the problem. 13624139SjoergThis option can only be used by root. 13724139Sjoerg.TP 13824139Sjoerg.B \-u 13924139SjoergDo not take the time to map uid numbers to usernames. Normally, 14024139Sjoerg.I top 14124139Sjoergwill read as much of the file \*(lq/etc/passwd\*(rq as is necessary to map 14224139Sjoergall the user id numbers it encounters into login names. This option 14324139Sjoergdisables all that, while possibly decreasing execution time. The uid 14424139Sjoergnumbers are displayed instead of the names. 14524139Sjoerg.TP 14689756Sdwmalone.B \-v 14789756SdwmaloneWrite version number information to stderr then exit immediately. 14889756SdwmaloneNo other processing takes place when this option is used. To see current 14989756Sdwmalonerevision information while top is running, use the help command \*(lq?\*(rq. 15089756Sdwmalone.TP 151307757Sdes.B \-w 152307757SdesDisplay approximate swap usage for each process. 153307757Sdes.TP 154222530Sjhb.B \-z 155222530SjhbDo not display the system idle process. 156222530Sjhb.TP 15724139Sjoerg.BI \-d count 15824139SjoergShow only 15924139Sjoerg.I count 16024139Sjoergdisplays, then exit. A display is considered to be one update of the 16124139Sjoergscreen. This option allows the user to select the number of displays he 16224139Sjoergwants to see before 16324139Sjoerg.I top 16424139Sjoergautomatically exits. For intelligent terminals, no upper limit 16524139Sjoergis set. The default is 1 for dumb terminals. 16624139Sjoerg.TP 16724139Sjoerg.BI \-s time 16824139SjoergSet the delay between screen updates to 16924139Sjoerg.I time 17024139Sjoergseconds. The default delay between updates is \nD seconds. 17124139Sjoerg.TP 17224139Sjoerg.BI \-o field 173307757SdesSort the process display area on the specified field. The field name 174307757Sdesis the name of the column as seen in the output, but in lower case: 175307757Sdes\*(lqcpu\*(lq, \*(rqsize\*(lq, \*(rqres\*(lq, \*(rqtime\*(lq, 176307757Sdes\*(rqpri\*(lq, \*(rqthreads\*(lq, \*(lqtotal\*(lq, \*(rqread\*(lq, 177307757Sdes\*(rqwrite\*(lq, \*(rqfault\*(lq, \*(rqvcsw\*(lq, \*(rqivcsw\*(lq, 178307757Sdes\*(lqjid\*(lq, \*(rqswap\*(lq or \*(rqpid\*(lq. 17924139Sjoerg.TP 180265249Sbdrewery.BI \-J jail 181265249SbdreweryShow only those processes owned by 182265249Sbdrewery.IR jail . 183265249SbdreweryThis may be either the 184265249Sbdrewery.B jid 185265249Sbdreweryor 186265249Sbdrewery.B name 187265249Sbdreweryof the jail. 188265249SbdreweryUse 189265249Sbdrewery.B 0 190265249Sbdreweryto limit to host processes. 191265249SbdreweryUsing this option implies the 192265249Sbdrewery.B \-j 193265249Sbdreweryflag. 194265249Sbdrewery.PP 19524139Sjoerg.BI \-U username 19624139SjoergShow only those processes owned by 19724139Sjoerg.IR username . 19824139SjoergThis option currently only accepts usernames and will not understand 19924139Sjoerguid numbers. 20024139Sjoerg.PP 20124139SjoergBoth 20224139Sjoerg.I count 20324139Sjoergand 20424139Sjoerg.I number 20524139Sjoergfields can be specified as \*(lqinfinite\*(rq, indicating that they can 20624139Sjoergstretch as far as possible. This is accomplished by using any proper 20724139Sjoergprefix of the keywords 20824139Sjoerg\*(lqinfinity\*(rq, 20924139Sjoerg\*(lqmaximum\*(rq, 21024139Sjoergor 21124139Sjoerg\*(lqall\*(rq. 21224139SjoergThe default for 21324139Sjoerg.I count 21424139Sjoergon an intelligent terminal is, in fact, 21524139Sjoerg.BI infinity . 21624139Sjoerg.PP 21724139SjoergThe environment variable 21824139Sjoerg.B TOP 21924139Sjoergis examined for options before the command line is scanned. This enables 22024139Sjoerga user to set his or her own defaults. The number of processes to display 22124139Sjoergcan also be specified in the environment variable 22224139Sjoerg.BR TOP . 22324139SjoergThe options 224223870Sjhb.BR \-a , 225223870Sjhb.BR \-C , 226223870Sjhb.BR \-H , 22724139Sjoerg.BR \-I , 228223870Sjhb.BR \-j , 229223936Sjhb.BR \-P , 23024139Sjoerg.BR \-S , 231223870Sjhb.BR \-t , 23238090Sdes.BR \-u , 233307757Sdes.BR \-w , 23424139Sjoergand 235223870Sjhb.B \-z 23624139Sjoergare actually toggles. A second specification of any of these options 23724139Sjoergwill negate the first. Thus a user who has the environment variable 23824139Sjoerg.B TOP 23924139Sjoergset to \*(lq\-I\*(rq may use the command \*(lqtop \-I\*(rq to see idle processes. 24024139Sjoerg.SH "INTERACTIVE MODE" 24124139SjoergWhen 24224139Sjoerg.I top 24324139Sjoergis running in \*(lqinteractive mode\*(rq, it reads commands from the 24424139Sjoergterminal and acts upon them accordingly. In this mode, the terminal is 24524139Sjoergput in \*(lqCBREAK\*(rq, so that a character will be 24624139Sjoergprocessed as soon as it is typed. Almost always, a key will be 24724139Sjoergpressed when 24824139Sjoerg.I top 24924139Sjoergis between displays; that is, while it is waiting for 25024139Sjoerg.I time 25124139Sjoergseconds to elapse. If this is the case, the command will be 25224139Sjoergprocessed and the display will be updated immediately thereafter 25324139Sjoerg(reflecting any changes that the command may have specified). This 25424139Sjoerghappens even if the command was incorrect. If a key is pressed while 25524139Sjoerg.I top 25624139Sjoergis in the middle of updating the display, it will finish the update and 25724139Sjoergthen process the command. Some commands require additional information, 25824139Sjoergand the user will be prompted accordingly. While typing this information 25924139Sjoergin, the user's erase and kill keys (as set up by the command 26024139Sjoerg.IR stty ) 26124139Sjoergare recognized, and a newline terminates the input. 26224139Sjoerg.PP 26324139SjoergThese commands are currently recognized (^L refers to control-L): 26424139Sjoerg.TP 26524139Sjoerg.B ^L 26624139SjoergRedraw the screen. 26724139Sjoerg.IP "\fBh\fP\ or\ \fB?\fP" 26889756SdwmaloneDisplay a summary of the commands (help screen). Version information 26989756Sdwmaloneis included in this display. 27024139Sjoerg.TP 27124139Sjoerg.B q 27224139SjoergQuit 27324139Sjoerg.IR top. 27424139Sjoerg.TP 27524139Sjoerg.B d 27624139SjoergChange the number of displays to show (prompt for new number). 27724139SjoergRemember that the next display counts as one, so typing 27824139Sjoerg.B d1 27924139Sjoergwill make 28024139Sjoerg.I top 28124139Sjoergshow one final display and then immediately exit. 28224139Sjoerg.TP 283131402Salfred.B m 284131402SalfredToggle the display between 'cpu' and 'io' modes. 285131402Salfred.TP 28624139Sjoerg.B n or # 28724139SjoergChange the number of processes to display (prompt for new number). 28824139Sjoerg.TP 28924139Sjoerg.B s 29024139SjoergChange the number of seconds to delay between displays 29124139Sjoerg(prompt for new number). 29224139Sjoerg.TP 293132005Salfred.B S 294132005SalfredToggle the display of system processes. 295132005Salfred.TP 296169237Sstas.B a 297169237SstasToggle the display of process titles. 298169237Sstas.TP 29924139Sjoerg.B k 30024139SjoergSend a signal (\*(lqkill\*(rq by default) to a list of processes. This 30124139Sjoergacts similarly to the command 30224139Sjoerg.IR kill (1)). 30324139Sjoerg.TP 30424139Sjoerg.B r 30524139SjoergChange the priority (the \*(lqnice\*(rq) of a list of processes. 30624139SjoergThis acts similarly to the command 30724139Sjoerg.IR renice (8)). 30824139Sjoerg.TP 30924139Sjoerg.B u 310322509SgahrDisplay only processes owned by a specific set of usernames (prompt for 311322509Sgahrusername). If the username specified is simply \*(lq+\*(rq or \*(lq-\*(rq, 312322509Sgahrthen processes belonging to all users will be displayed. Usernames can be added 313322509Sgahrto and removed from the set by prepending them with \*(lq+\*(rq and 314322509Sgahr\*(lq-\*(rq, respectively. 31524139Sjoerg.TP 31689756Sdwmalone.B o 31789756SdwmaloneChange the order in which the display is sorted. This command is not 318151697Skeramidaavailable on all systems. The sort key names vary from system to system 31989756Sdwmalonebut usually include: \*(lqcpu\*(rq, \*(lqres\*(rq, \*(lqsize\*(rq, 32089756Sdwmalone\*(lqtime\*(rq. The default is cpu. 32189756Sdwmalone.TP 32224139Sjoerg.B e 32324139SjoergDisplay a list of system errors (if any) generated by the last 32424139Sjoerg.BR k ill 32524139Sjoergor 32624139Sjoerg.BR r enice 32724139Sjoergcommand. 32824139Sjoerg.TP 329222532Sjhb.B H 330222532SjhbToggle the display of threads. 331222532Sjhb.TP 33224139Sjoerg.B i 33324139Sjoerg(or 334143520Sbrueffer.BR I ) 33524139SjoergToggle the display of idle processes. 33638279Sdes.TP 337168799Srafan.B j 338168799SrafanToggle the display of 339168799Srafan.IR jail (8) 340169257SrafanID. 341168799Srafan.TP 342265249Sbdrewery.B J 343265249SbdreweryDisplay only processes owned by a specific jail (prompt for jail). 344265249SbdreweryIf the jail specified is simply \*(lq+\*(rq, then processes belonging 345265249Sbdreweryto all jails and the host will be displayed. 346265249SbdreweryThis will also enable the display of JID. 347265249Sbdrewery.TP 348223936Sjhb.B P 349223936SjhbToggle the display of per-CPU statistics. 350223936Sjhb.TP 35138090Sdes.B t 35238090SdesToggle the display of the 35338090Sdes.I top 35438090Sdesprocess. 355222530Sjhb.TP 356307757Sdes.B w 357307757SdesToggle the display of swap usage. 358307757Sdes.TP 359222530Sjhb.B z 360222530SjhbToggle the display of the system idle process. 36124139Sjoerg.SH "THE DISPLAY" 36224139SjoergThe actual display varies depending on the specific variant of Unix 36324139Sjoergthat the machine is running. This description may not exactly match 36424139Sjoergwhat is seen by top running on this particular machine. Differences 36524139Sjoergare listed at the end of this manual entry. 36624139Sjoerg.PP 36724139SjoergThe top few lines of the display show general information 36824139Sjoergabout the state of the system, including 36924139Sjoergthe last process id assigned to a process (on most systems), 37024139Sjoergthe three load averages, 37124139Sjoergthe current time, 37224139Sjoergthe number of existing processes, 37324139Sjoergthe number of processes in each state 37424139Sjoerg(sleeping, running, starting, zombies, and stopped), 37524139Sjoergand a percentage of time spent in each of the processor states 37624139Sjoerg(user, nice, system, and idle). 37729329SwoschIt also includes information about physical and virtual memory allocation. 37824139Sjoerg.PP 37924139SjoergThe remainder of the screen displays information about individual 38024139Sjoergprocesses. This display is similar in spirit to 38124139Sjoerg.IR ps (1) 382168799Srafanbut it is not exactly the same. PID is the process id, 383168799SrafanJID, when displayed, is the 384168799Srafan.IR jail (8) 385168799SrafanID corresponding to the process, 386168799SrafanUSERNAME is the name of the process's owner (if 38724139Sjoerg.B \-u 38824139Sjoergis specified, a UID column will be substituted for USERNAME), 38924139SjoergPRI is the current priority of the process, 39024139SjoergNICE is the nice amount (in the range \-20 to 20), 39124139SjoergSIZE is the total size of the process (text, data, and stack), 392307757SdesRES is the current amount of resident memory, 393307757SdesSWAP is the approximate amount of swap, if enabled 394307757Sdes(SIZE, RES and SWAP are given in kilobytes), 395158653SkeramidaSTATE is the current state (one of \*(lqSTART\*(rq, \*(lqRUN\*(rq 396158653Skeramida(shown as \*(lqCPUn\*(rq on SMP systems), \*(lqSLEEP\*(rq, \*(lqSTOP\*(rq, 397158653Skeramida\*(lqZOMB\*(rq, \*(lqWAIT\*(rq, \*(lqLOCK\*(rq or the event on which the 398158653Skeramidaprocess waits), 399158653SkeramidaC is the processor number on which the process is executing 400158653Skeramida(visible only on SMP systems), 40124139SjoergTIME is the number of system and user cpu seconds that the process has used, 40224139SjoergWCPU, when displayed, is the weighted cpu percentage (this is the same 40324139Sjoergvalue that 40424139Sjoerg.IR ps (1) 40524139Sjoergdisplays as CPU), 40624139SjoergCPU is the raw percentage and is the field that is sorted to determine 40724139Sjoergthe order of the processes, and 40824139SjoergCOMMAND is the name of the command that the process is currently running 40924139Sjoerg(if the process is swapped out, this column is marked \*(lq<swapped>\*(rq). 41024139Sjoerg.SH NOTES 411222532SjhbIf a process is in the \*(lqSLEEP\*(rq or \*(lqLOCK\*(rq state, 412222532Sjhbthe state column will report the name of the event or lock on which the 413222532Sjhbprocess is waiting. 414222532SjhbLock names are prefixed with an asterisk \*(lq*\*(rq while sleep events 415222532Sjhbare not. 41624139Sjoerg.SH AUTHOR 41724139SjoergWilliam LeFebvre, EECS Department, Northwestern University 41824139Sjoerg.SH ENVIRONMENT 41924139Sjoerg.DT 42024139SjoergTOP user-configurable defaults for options. 42124139Sjoerg.SH FILES 42224139Sjoerg.DT 42324139Sjoerg/dev/kmem kernel memory 42424139Sjoerg.br 42524139Sjoerg/dev/mem physical memory 42624139Sjoerg.br 42724139Sjoerg/etc/passwd used to map uid numbers to user names 42824139Sjoerg.br 429119491Seivind/boot/kernel/kernel system image 43024139Sjoerg.SH BUGS 43124139SjoergDon't shoot me, but the default for 43224139Sjoerg.B \-I 43324139Sjoerghas changed once again. So many people were confused by the fact that 43424139Sjoerg.I top 43524139Sjoergwasn't showing them all the processes that I have decided to make the 43624139Sjoergdefault behavior show idle processes, just like it did in version 2. 43724139SjoergBut to appease folks who can't stand that behavior, I have added the 43824139Sjoergability to set \*(lqdefault\*(rq options in the environment variable 43924139Sjoerg.B TOP 44024139Sjoerg(see the OPTIONS section). Those who want the behavior that version 44124139Sjoerg3.0 had need only set the environment variable 44224139Sjoerg.B TOP 44324139Sjoergto \*(lq\-I\*(rq. 44424139Sjoerg.PP 44524139SjoergThe command name for swapped processes should be tracked down, but this 44624139Sjoergwould make the program run slower. 44724139Sjoerg.PP 44824139SjoergAs with 44924139Sjoerg.IR ps (1), 45024139Sjoergthings can change while 45124139Sjoerg.I top 45224139Sjoergis collecting information for an update. The picture it gives is only a 45324139Sjoergclose approximation to reality. 45424139Sjoerg.SH "SEE ALSO" 45524139Sjoergkill(1), 45624139Sjoergps(1), 45724139Sjoergstty(1), 45824139Sjoergmem(4), 45924139Sjoergrenice(8) 460