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$ 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[ 13222530Sjhb.B \-abCHIijnPqStuvz 1424139Sjoerg] [ 1524139Sjoerg.BI \-d count 1624139Sjoerg] [ 17157842Sru.BI \-m io | cpu 1824139Sjoerg] [ 1924139Sjoerg.BI \-o field 2024139Sjoerg] [ 21157842Sru.BI \-s time 22157842Sru] [ 23266280Sbdrewery.BI \-J jail 24266280Sbdrewery] [ 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 151222530Sjhb.B \-z 152222530SjhbDo not display the system idle process. 153222530Sjhb.TP 15424139Sjoerg.BI \-d count 15524139SjoergShow only 15624139Sjoerg.I count 15724139Sjoergdisplays, then exit. A display is considered to be one update of the 15824139Sjoergscreen. This option allows the user to select the number of displays he 15924139Sjoergwants to see before 16024139Sjoerg.I top 16124139Sjoergautomatically exits. For intelligent terminals, no upper limit 16224139Sjoergis set. The default is 1 for dumb terminals. 16324139Sjoerg.TP 16424139Sjoerg.BI \-s time 16524139SjoergSet the delay between screen updates to 16624139Sjoerg.I time 16724139Sjoergseconds. The default delay between updates is \nD seconds. 16824139Sjoerg.TP 16924139Sjoerg.BI \-o field 17024139SjoergSort the process display area on the specified field. The field name is 17124139Sjoergthe name of the column as seen in the output, but in lower case. Likely 17224139Sjoergvalues are \*(lqcpu\*(rq, \*(lqsize\*(rq, \*(lqres\*(rq, and \*(lqtime\*(rq, 17324139Sjoergbut may vary on different operating systems. Note that 17424139Sjoergnot all operating systems support this option. 17524139Sjoerg.TP 176266280Sbdrewery.BI \-J jail 177266280SbdreweryShow only those processes owned by 178266280Sbdrewery.IR jail . 179266280SbdreweryThis may be either the 180266280Sbdrewery.B jid 181266280Sbdreweryor 182266280Sbdrewery.B name 183266280Sbdreweryof the jail. 184266280SbdreweryUse 185266280Sbdrewery.B 0 186266280Sbdreweryto limit to host processes. 187266280SbdreweryUsing this option implies the 188266280Sbdrewery.B \-j 189266280Sbdreweryflag. 190266280Sbdrewery.PP 19124139Sjoerg.BI \-U username 19224139SjoergShow only those processes owned by 19324139Sjoerg.IR username . 19424139SjoergThis option currently only accepts usernames and will not understand 19524139Sjoerguid numbers. 19624139Sjoerg.PP 19724139SjoergBoth 19824139Sjoerg.I count 19924139Sjoergand 20024139Sjoerg.I number 20124139Sjoergfields can be specified as \*(lqinfinite\*(rq, indicating that they can 20224139Sjoergstretch as far as possible. This is accomplished by using any proper 20324139Sjoergprefix of the keywords 20424139Sjoerg\*(lqinfinity\*(rq, 20524139Sjoerg\*(lqmaximum\*(rq, 20624139Sjoergor 20724139Sjoerg\*(lqall\*(rq. 20824139SjoergThe default for 20924139Sjoerg.I count 21024139Sjoergon an intelligent terminal is, in fact, 21124139Sjoerg.BI infinity . 21224139Sjoerg.PP 21324139SjoergThe environment variable 21424139Sjoerg.B TOP 21524139Sjoergis examined for options before the command line is scanned. This enables 21624139Sjoerga user to set his or her own defaults. The number of processes to display 21724139Sjoergcan also be specified in the environment variable 21824139Sjoerg.BR TOP . 21924139SjoergThe options 220223870Sjhb.BR \-a , 221223870Sjhb.BR \-C , 222223870Sjhb.BR \-H , 22324139Sjoerg.BR \-I , 224223870Sjhb.BR \-j , 225223936Sjhb.BR \-P , 22624139Sjoerg.BR \-S , 227223870Sjhb.BR \-t , 22838090Sdes.BR \-u , 22924139Sjoergand 230223870Sjhb.B \-z 23124139Sjoergare actually toggles. A second specification of any of these options 23224139Sjoergwill negate the first. Thus a user who has the environment variable 23324139Sjoerg.B TOP 23424139Sjoergset to \*(lq\-I\*(rq may use the command \*(lqtop \-I\*(rq to see idle processes. 23524139Sjoerg.SH "INTERACTIVE MODE" 23624139SjoergWhen 23724139Sjoerg.I top 23824139Sjoergis running in \*(lqinteractive mode\*(rq, it reads commands from the 23924139Sjoergterminal and acts upon them accordingly. In this mode, the terminal is 24024139Sjoergput in \*(lqCBREAK\*(rq, so that a character will be 24124139Sjoergprocessed as soon as it is typed. Almost always, a key will be 24224139Sjoergpressed when 24324139Sjoerg.I top 24424139Sjoergis between displays; that is, while it is waiting for 24524139Sjoerg.I time 24624139Sjoergseconds to elapse. If this is the case, the command will be 24724139Sjoergprocessed and the display will be updated immediately thereafter 24824139Sjoerg(reflecting any changes that the command may have specified). This 24924139Sjoerghappens even if the command was incorrect. If a key is pressed while 25024139Sjoerg.I top 25124139Sjoergis in the middle of updating the display, it will finish the update and 25224139Sjoergthen process the command. Some commands require additional information, 25324139Sjoergand the user will be prompted accordingly. While typing this information 25424139Sjoergin, the user's erase and kill keys (as set up by the command 25524139Sjoerg.IR stty ) 25624139Sjoergare recognized, and a newline terminates the input. 25724139Sjoerg.PP 25824139SjoergThese commands are currently recognized (^L refers to control-L): 25924139Sjoerg.TP 26024139Sjoerg.B ^L 26124139SjoergRedraw the screen. 26224139Sjoerg.IP "\fBh\fP\ or\ \fB?\fP" 26389756SdwmaloneDisplay a summary of the commands (help screen). Version information 26489756Sdwmaloneis included in this display. 26524139Sjoerg.TP 26624139Sjoerg.B q 26724139SjoergQuit 26824139Sjoerg.IR top. 26924139Sjoerg.TP 27024139Sjoerg.B d 27124139SjoergChange the number of displays to show (prompt for new number). 27224139SjoergRemember that the next display counts as one, so typing 27324139Sjoerg.B d1 27424139Sjoergwill make 27524139Sjoerg.I top 27624139Sjoergshow one final display and then immediately exit. 27724139Sjoerg.TP 278131402Salfred.B m 279131402SalfredToggle the display between 'cpu' and 'io' modes. 280131402Salfred.TP 28124139Sjoerg.B n or # 28224139SjoergChange the number of processes to display (prompt for new number). 28324139Sjoerg.TP 28424139Sjoerg.B s 28524139SjoergChange the number of seconds to delay between displays 28624139Sjoerg(prompt for new number). 28724139Sjoerg.TP 288132005Salfred.B S 289132005SalfredToggle the display of system processes. 290132005Salfred.TP 291169237Sstas.B a 292169237SstasToggle the display of process titles. 293169237Sstas.TP 29424139Sjoerg.B k 29524139SjoergSend a signal (\*(lqkill\*(rq by default) to a list of processes. This 29624139Sjoergacts similarly to the command 29724139Sjoerg.IR kill (1)). 29824139Sjoerg.TP 29924139Sjoerg.B r 30024139SjoergChange the priority (the \*(lqnice\*(rq) of a list of processes. 30124139SjoergThis acts similarly to the command 30224139Sjoerg.IR renice (8)). 30324139Sjoerg.TP 30424139Sjoerg.B u 30524139SjoergDisplay only processes owned by a specific username (prompt for username). 30624139SjoergIf the username specified is simply \*(lq+\*(rq, then processes belonging 30724139Sjoergto all users will be displayed. 30824139Sjoerg.TP 30989756Sdwmalone.B o 31089756SdwmaloneChange the order in which the display is sorted. This command is not 311151697Skeramidaavailable on all systems. The sort key names vary from system to system 31289756Sdwmalonebut usually include: \*(lqcpu\*(rq, \*(lqres\*(rq, \*(lqsize\*(rq, 31389756Sdwmalone\*(lqtime\*(rq. The default is cpu. 31489756Sdwmalone.TP 31524139Sjoerg.B e 31624139SjoergDisplay a list of system errors (if any) generated by the last 31724139Sjoerg.BR k ill 31824139Sjoergor 31924139Sjoerg.BR r enice 32024139Sjoergcommand. 32124139Sjoerg.TP 322222532Sjhb.B H 323222532SjhbToggle the display of threads. 324222532Sjhb.TP 32524139Sjoerg.B i 32624139Sjoerg(or 327143520Sbrueffer.BR I ) 32824139SjoergToggle the display of idle processes. 32938279Sdes.TP 330168799Srafan.B j 331168799SrafanToggle the display of 332168799Srafan.IR jail (8) 333169257SrafanID. 334168799Srafan.TP 335266280Sbdrewery.B J 336266280SbdreweryDisplay only processes owned by a specific jail (prompt for jail). 337266280SbdreweryIf the jail specified is simply \*(lq+\*(rq, then processes belonging 338266280Sbdreweryto all jails and the host will be displayed. 339266280SbdreweryThis will also enable the display of JID. 340266280Sbdrewery.TP 341223936Sjhb.B P 342223936SjhbToggle the display of per-CPU statistics. 343223936Sjhb.TP 34438090Sdes.B t 34538090SdesToggle the display of the 34638090Sdes.I top 34738090Sdesprocess. 348222530Sjhb.TP 349222530Sjhb.B z 350222530SjhbToggle the display of the system idle process. 35124139Sjoerg.SH "THE DISPLAY" 35224139SjoergThe actual display varies depending on the specific variant of Unix 35324139Sjoergthat the machine is running. This description may not exactly match 35424139Sjoergwhat is seen by top running on this particular machine. Differences 35524139Sjoergare listed at the end of this manual entry. 35624139Sjoerg.PP 35724139SjoergThe top few lines of the display show general information 35824139Sjoergabout the state of the system, including 35924139Sjoergthe last process id assigned to a process (on most systems), 36024139Sjoergthe three load averages, 36124139Sjoergthe current time, 36224139Sjoergthe number of existing processes, 36324139Sjoergthe number of processes in each state 36424139Sjoerg(sleeping, running, starting, zombies, and stopped), 36524139Sjoergand a percentage of time spent in each of the processor states 36624139Sjoerg(user, nice, system, and idle). 36729329SwoschIt also includes information about physical and virtual memory allocation. 36824139Sjoerg.PP 36924139SjoergThe remainder of the screen displays information about individual 37024139Sjoergprocesses. This display is similar in spirit to 37124139Sjoerg.IR ps (1) 372168799Srafanbut it is not exactly the same. PID is the process id, 373168799SrafanJID, when displayed, is the 374168799Srafan.IR jail (8) 375168799SrafanID corresponding to the process, 376168799SrafanUSERNAME is the name of the process's owner (if 37724139Sjoerg.B \-u 37824139Sjoergis specified, a UID column will be substituted for USERNAME), 37924139SjoergPRI is the current priority of the process, 38024139SjoergNICE is the nice amount (in the range \-20 to 20), 38124139SjoergSIZE is the total size of the process (text, data, and stack), 38224139SjoergRES is the current amount of resident memory (both SIZE and RES are 38324139Sjoerggiven in kilobytes), 384158653SkeramidaSTATE is the current state (one of \*(lqSTART\*(rq, \*(lqRUN\*(rq 385158653Skeramida(shown as \*(lqCPUn\*(rq on SMP systems), \*(lqSLEEP\*(rq, \*(lqSTOP\*(rq, 386158653Skeramida\*(lqZOMB\*(rq, \*(lqWAIT\*(rq, \*(lqLOCK\*(rq or the event on which the 387158653Skeramidaprocess waits), 388158653SkeramidaC is the processor number on which the process is executing 389158653Skeramida(visible only on SMP systems), 39024139SjoergTIME is the number of system and user cpu seconds that the process has used, 39124139SjoergWCPU, when displayed, is the weighted cpu percentage (this is the same 39224139Sjoergvalue that 39324139Sjoerg.IR ps (1) 39424139Sjoergdisplays as CPU), 39524139SjoergCPU is the raw percentage and is the field that is sorted to determine 39624139Sjoergthe order of the processes, and 39724139SjoergCOMMAND is the name of the command that the process is currently running 39824139Sjoerg(if the process is swapped out, this column is marked \*(lq<swapped>\*(rq). 39924139Sjoerg.SH NOTES 400222532SjhbIf a process is in the \*(lqSLEEP\*(rq or \*(lqLOCK\*(rq state, 401222532Sjhbthe state column will report the name of the event or lock on which the 402222532Sjhbprocess is waiting. 403222532SjhbLock names are prefixed with an asterisk \*(lq*\*(rq while sleep events 404222532Sjhbare not. 40524139Sjoerg.SH AUTHOR 40624139SjoergWilliam LeFebvre, EECS Department, Northwestern University 40724139Sjoerg.SH ENVIRONMENT 40824139Sjoerg.DT 40924139SjoergTOP user-configurable defaults for options. 41024139Sjoerg.SH FILES 41124139Sjoerg.DT 41224139Sjoerg/dev/kmem kernel memory 41324139Sjoerg.br 41424139Sjoerg/dev/mem physical memory 41524139Sjoerg.br 41624139Sjoerg/etc/passwd used to map uid numbers to user names 41724139Sjoerg.br 418119491Seivind/boot/kernel/kernel system image 41924139Sjoerg.SH BUGS 42024139SjoergDon't shoot me, but the default for 42124139Sjoerg.B \-I 42224139Sjoerghas changed once again. So many people were confused by the fact that 42324139Sjoerg.I top 42424139Sjoergwasn't showing them all the processes that I have decided to make the 42524139Sjoergdefault behavior show idle processes, just like it did in version 2. 42624139SjoergBut to appease folks who can't stand that behavior, I have added the 42724139Sjoergability to set \*(lqdefault\*(rq options in the environment variable 42824139Sjoerg.B TOP 42924139Sjoerg(see the OPTIONS section). Those who want the behavior that version 43024139Sjoerg3.0 had need only set the environment variable 43124139Sjoerg.B TOP 43224139Sjoergto \*(lq\-I\*(rq. 43324139Sjoerg.PP 43424139SjoergThe command name for swapped processes should be tracked down, but this 43524139Sjoergwould make the program run slower. 43624139Sjoerg.PP 43724139SjoergAs with 43824139Sjoerg.IR ps (1), 43924139Sjoergthings can change while 44024139Sjoerg.I top 44124139Sjoergis collecting information for an update. The picture it gives is only a 44224139Sjoergclose approximation to reality. 44324139Sjoerg.SH "SEE ALSO" 44424139Sjoergkill(1), 44524139Sjoergps(1), 44624139Sjoergstty(1), 44724139Sjoergmem(4), 44824139Sjoergrenice(8) 449