top.xs revision 223936
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: head/contrib/top/top.X 223936 2011-07-11 16:48:52Z jhb $ 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] [ 2324139Sjoerg.BI \-U username 2424139Sjoerg] [ 2524139Sjoerg.I number 2624139Sjoerg] 2724139Sjoerg.SH DESCRIPTION 2824139Sjoerg.\" This defines appropriate quote strings for nroff and troff 2924139Sjoerg.ds lq \&" 3024139Sjoerg.ds rq \&" 3124139Sjoerg.if t .ds lq `` 3224139Sjoerg.if t .ds rq '' 3324139Sjoerg.\" Just in case these number registers aren't set yet... 3424139Sjoerg.if \nN==0 .nr N 10 3563653Sphantom.if \nD==0 .nr D 2 3624139Sjoerg.I Top 3724139Sjoergdisplays the top 3824139Sjoerg.if !\nN==-1 \nN 3924139Sjoergprocesses on the system and periodically updates this information. 4024139Sjoerg.if \nN==-1 \ 4124139Sjoerg\{\ 4224139SjoergIf standard output is an intelligent terminal (see below) then 4324139Sjoergas many processes as will fit on the terminal screen are displayed 4424139Sjoergby default. Otherwise, a good number of them are shown (around 20). 4524139Sjoerg.\} 4624139SjoergRaw cpu percentage is used to rank the processes. If 4724139Sjoerg.I number 4824139Sjoergis given, then the top 4924139Sjoerg.I number 5024139Sjoergprocesses will be displayed instead of the default. 5124139Sjoerg.PP 5224139Sjoerg.I Top 5324139Sjoergmakes a distinction between terminals that support advanced capabilities 5424139Sjoergand those that do not. This 5524139Sjoergdistinction affects the choice of defaults for certain options. In the 5624139Sjoergremainder of this document, an \*(lqintelligent\*(rq terminal is one that 5724139Sjoergsupports cursor addressing, clear screen, and clear to end of line. 5824139SjoergConversely, a \*(lqdumb\*(rq terminal is one that does not support such 5924139Sjoergfeatures. If the output of 6024139Sjoerg.I top 6124139Sjoergis redirected to a file, it acts as if it were being run on a dumb 6224139Sjoergterminal. 6324139Sjoerg.SH OPTIONS 6424139Sjoerg.TP 65157865Skeramida.B \-C 66157865SkeramidaToggle CPU display mode. 67157865SkeramidaBy default top displays the weighted CPU percentage in the WCPU column 68157865Skeramida(this is the same value that 69157865Skeramida.IR ps (1) 70157865Skeramidadisplays as CPU). 71157865SkeramidaEach time 72157865Skeramida.B \-C 73157865Skeramidaflag is passed it toggles between \*(lqraw cpu\*(rq mode 74157865Skeramidaand \*(lqweighted cpu\*(rq mode, showing the \*(lqCPU\*(rq or 75157865Skeramidathe \*(lqWCPU\*(rq column respectively. 76157865Skeramida.TP 7724139Sjoerg.B \-S 7824139SjoergShow system processes in the display. Normally, system processes such as 7924139Sjoergthe pager and the swapper are not shown. This option makes them visible. 8024139Sjoerg.TP 81168710Sstas.B \-a 82168710SstasDisplay command names derived from the argv[] vector, rather than real 83168710Sstasexecutable name. It's useful when you want to watch applications, that 84168710Sstasputs their status information there. If the real name differs from argv[0], 85168710Sstasit will be displayed in parenthesis. 86168710Sstas.TP 8724139Sjoerg.B \-b 8824139SjoergUse \*(lqbatch\*(rq mode. In this mode, all input from the terminal is 8924139Sjoergignored. Interrupt characters (such as ^C and ^\e) still have an effect. 9024139SjoergThis is the default on a dumb terminal, or when the output is not a terminal. 9124139Sjoerg.TP 92222532Sjhb.B \-H 93222532SjhbDisplay each thread for a multithreaded process individually. 94222532SjhbBy default a single summary line is displayed for each process. 95222532Sjhb.TP 9624139Sjoerg.B \-i 9724139SjoergUse \*(lqinteractive\*(rq mode. In this mode, any input is immediately 9824139Sjoergread for processing. See the section on \*(lqInteractive Mode\*(rq 9924139Sjoergfor an explanation of 10024139Sjoergwhich keys perform what functions. After the command is processed, the 10124139Sjoergscreen will immediately be updated, even if the command was not 10224139Sjoergunderstood. This mode is the default when standard output is an 10324139Sjoergintelligent terminal. 10424139Sjoerg.TP 10524139Sjoerg.B \-I 10624139SjoergDo not display idle processes. 10724139SjoergBy default, top displays both active and idle processes. 10824139Sjoerg.TP 109168799Srafan.B \-j 110168799SrafanDisplay the 111168799Srafan.IR jail (8) 112169257SrafanID. 113168799Srafan.TP 11438090Sdes.B \-t 11538090SdesDo not display the 11638090Sdes.I top 11738090Sdesprocess. 11838090Sdes.TP 119131402Salfred.BI \-m display 120131402SalfredDisplay either 'cpu' or 'io' statistics. Default is 'cpu'. 121131402Salfred.TP 12224139Sjoerg.B \-n 12328935SjmgUse \*(lqnon-interactive\*(rq mode. This is identical to \*(lqbatch\*(rq 12424139Sjoergmode. 12524139Sjoerg.TP 126179911Sru.B \-P 127179911SruDisplay per-cpu CPU usage statistics. 128179911Sru.TP 12924139Sjoerg.B \-q 13024139SjoergRenice 13124139Sjoerg.I top 13224139Sjoergto -20 so that it will run faster. This can be used when the system is 13324139Sjoergbeing very sluggish to improve the possibility of discovering the problem. 13424139SjoergThis option can only be used by root. 13524139Sjoerg.TP 13624139Sjoerg.B \-u 13724139SjoergDo not take the time to map uid numbers to usernames. Normally, 13824139Sjoerg.I top 13924139Sjoergwill read as much of the file \*(lq/etc/passwd\*(rq as is necessary to map 14024139Sjoergall the user id numbers it encounters into login names. This option 14124139Sjoergdisables all that, while possibly decreasing execution time. The uid 14224139Sjoergnumbers are displayed instead of the names. 14324139Sjoerg.TP 14489756Sdwmalone.B \-v 14589756SdwmaloneWrite version number information to stderr then exit immediately. 14689756SdwmaloneNo other processing takes place when this option is used. To see current 14789756Sdwmalonerevision information while top is running, use the help command \*(lq?\*(rq. 14889756Sdwmalone.TP 149222530Sjhb.B \-z 150222530SjhbDo not display the system idle process. 151222530Sjhb.TP 15224139Sjoerg.BI \-d count 15324139SjoergShow only 15424139Sjoerg.I count 15524139Sjoergdisplays, then exit. A display is considered to be one update of the 15624139Sjoergscreen. This option allows the user to select the number of displays he 15724139Sjoergwants to see before 15824139Sjoerg.I top 15924139Sjoergautomatically exits. For intelligent terminals, no upper limit 16024139Sjoergis set. The default is 1 for dumb terminals. 16124139Sjoerg.TP 16224139Sjoerg.BI \-s time 16324139SjoergSet the delay between screen updates to 16424139Sjoerg.I time 16524139Sjoergseconds. The default delay between updates is \nD seconds. 16624139Sjoerg.TP 16724139Sjoerg.BI \-o field 16824139SjoergSort the process display area on the specified field. The field name is 16924139Sjoergthe name of the column as seen in the output, but in lower case. Likely 17024139Sjoergvalues are \*(lqcpu\*(rq, \*(lqsize\*(rq, \*(lqres\*(rq, and \*(lqtime\*(rq, 17124139Sjoergbut may vary on different operating systems. Note that 17224139Sjoergnot all operating systems support this option. 17324139Sjoerg.TP 17424139Sjoerg.BI \-U username 17524139SjoergShow only those processes owned by 17624139Sjoerg.IR username . 17724139SjoergThis option currently only accepts usernames and will not understand 17824139Sjoerguid numbers. 17924139Sjoerg.PP 18024139SjoergBoth 18124139Sjoerg.I count 18224139Sjoergand 18324139Sjoerg.I number 18424139Sjoergfields can be specified as \*(lqinfinite\*(rq, indicating that they can 18524139Sjoergstretch as far as possible. This is accomplished by using any proper 18624139Sjoergprefix of the keywords 18724139Sjoerg\*(lqinfinity\*(rq, 18824139Sjoerg\*(lqmaximum\*(rq, 18924139Sjoergor 19024139Sjoerg\*(lqall\*(rq. 19124139SjoergThe default for 19224139Sjoerg.I count 19324139Sjoergon an intelligent terminal is, in fact, 19424139Sjoerg.BI infinity . 19524139Sjoerg.PP 19624139SjoergThe environment variable 19724139Sjoerg.B TOP 19824139Sjoergis examined for options before the command line is scanned. This enables 19924139Sjoerga user to set his or her own defaults. The number of processes to display 20024139Sjoergcan also be specified in the environment variable 20124139Sjoerg.BR TOP . 20224139SjoergThe options 203223870Sjhb.BR \-a , 204223870Sjhb.BR \-C , 205223870Sjhb.BR \-H , 20624139Sjoerg.BR \-I , 207223870Sjhb.BR \-j , 208223936Sjhb.BR \-P , 20924139Sjoerg.BR \-S , 210223870Sjhb.BR \-t , 21138090Sdes.BR \-u , 21224139Sjoergand 213223870Sjhb.B \-z 21424139Sjoergare actually toggles. A second specification of any of these options 21524139Sjoergwill negate the first. Thus a user who has the environment variable 21624139Sjoerg.B TOP 21724139Sjoergset to \*(lq\-I\*(rq may use the command \*(lqtop \-I\*(rq to see idle processes. 21824139Sjoerg.SH "INTERACTIVE MODE" 21924139SjoergWhen 22024139Sjoerg.I top 22124139Sjoergis running in \*(lqinteractive mode\*(rq, it reads commands from the 22224139Sjoergterminal and acts upon them accordingly. In this mode, the terminal is 22324139Sjoergput in \*(lqCBREAK\*(rq, so that a character will be 22424139Sjoergprocessed as soon as it is typed. Almost always, a key will be 22524139Sjoergpressed when 22624139Sjoerg.I top 22724139Sjoergis between displays; that is, while it is waiting for 22824139Sjoerg.I time 22924139Sjoergseconds to elapse. If this is the case, the command will be 23024139Sjoergprocessed and the display will be updated immediately thereafter 23124139Sjoerg(reflecting any changes that the command may have specified). This 23224139Sjoerghappens even if the command was incorrect. If a key is pressed while 23324139Sjoerg.I top 23424139Sjoergis in the middle of updating the display, it will finish the update and 23524139Sjoergthen process the command. Some commands require additional information, 23624139Sjoergand the user will be prompted accordingly. While typing this information 23724139Sjoergin, the user's erase and kill keys (as set up by the command 23824139Sjoerg.IR stty ) 23924139Sjoergare recognized, and a newline terminates the input. 24024139Sjoerg.PP 24124139SjoergThese commands are currently recognized (^L refers to control-L): 24224139Sjoerg.TP 24324139Sjoerg.B ^L 24424139SjoergRedraw the screen. 24524139Sjoerg.IP "\fBh\fP\ or\ \fB?\fP" 24689756SdwmaloneDisplay a summary of the commands (help screen). Version information 24789756Sdwmaloneis included in this display. 24824139Sjoerg.TP 24924139Sjoerg.B q 25024139SjoergQuit 25124139Sjoerg.IR top. 25224139Sjoerg.TP 25324139Sjoerg.B d 25424139SjoergChange the number of displays to show (prompt for new number). 25524139SjoergRemember that the next display counts as one, so typing 25624139Sjoerg.B d1 25724139Sjoergwill make 25824139Sjoerg.I top 25924139Sjoergshow one final display and then immediately exit. 26024139Sjoerg.TP 261131402Salfred.B m 262131402SalfredToggle the display between 'cpu' and 'io' modes. 263131402Salfred.TP 26424139Sjoerg.B n or # 26524139SjoergChange the number of processes to display (prompt for new number). 26624139Sjoerg.TP 26724139Sjoerg.B s 26824139SjoergChange the number of seconds to delay between displays 26924139Sjoerg(prompt for new number). 27024139Sjoerg.TP 271132005Salfred.B S 272132005SalfredToggle the display of system processes. 273132005Salfred.TP 274169237Sstas.B a 275169237SstasToggle the display of process titles. 276169237Sstas.TP 27724139Sjoerg.B k 27824139SjoergSend a signal (\*(lqkill\*(rq by default) to a list of processes. This 27924139Sjoergacts similarly to the command 28024139Sjoerg.IR kill (1)). 28124139Sjoerg.TP 28224139Sjoerg.B r 28324139SjoergChange the priority (the \*(lqnice\*(rq) of a list of processes. 28424139SjoergThis acts similarly to the command 28524139Sjoerg.IR renice (8)). 28624139Sjoerg.TP 28724139Sjoerg.B u 28824139SjoergDisplay only processes owned by a specific username (prompt for username). 28924139SjoergIf the username specified is simply \*(lq+\*(rq, then processes belonging 29024139Sjoergto all users will be displayed. 29124139Sjoerg.TP 29289756Sdwmalone.B o 29389756SdwmaloneChange the order in which the display is sorted. This command is not 294151697Skeramidaavailable on all systems. The sort key names vary from system to system 29589756Sdwmalonebut usually include: \*(lqcpu\*(rq, \*(lqres\*(rq, \*(lqsize\*(rq, 29689756Sdwmalone\*(lqtime\*(rq. The default is cpu. 29789756Sdwmalone.TP 29824139Sjoerg.B e 29924139SjoergDisplay a list of system errors (if any) generated by the last 30024139Sjoerg.BR k ill 30124139Sjoergor 30224139Sjoerg.BR r enice 30324139Sjoergcommand. 30424139Sjoerg.TP 305222532Sjhb.B H 306222532SjhbToggle the display of threads. 307222532Sjhb.TP 30824139Sjoerg.B i 30924139Sjoerg(or 310143520Sbrueffer.BR I ) 31124139SjoergToggle the display of idle processes. 31238279Sdes.TP 313168799Srafan.B j 314168799SrafanToggle the display of 315168799Srafan.IR jail (8) 316169257SrafanID. 317168799Srafan.TP 318223936Sjhb.B P 319223936SjhbToggle the display of per-CPU statistics. 320223936Sjhb.TP 32138090Sdes.B t 32238090SdesToggle the display of the 32338090Sdes.I top 32438090Sdesprocess. 325222530Sjhb.TP 326222530Sjhb.B z 327222530SjhbToggle the display of the system idle process. 32824139Sjoerg.SH "THE DISPLAY" 32924139SjoergThe actual display varies depending on the specific variant of Unix 33024139Sjoergthat the machine is running. This description may not exactly match 33124139Sjoergwhat is seen by top running on this particular machine. Differences 33224139Sjoergare listed at the end of this manual entry. 33324139Sjoerg.PP 33424139SjoergThe top few lines of the display show general information 33524139Sjoergabout the state of the system, including 33624139Sjoergthe last process id assigned to a process (on most systems), 33724139Sjoergthe three load averages, 33824139Sjoergthe current time, 33924139Sjoergthe number of existing processes, 34024139Sjoergthe number of processes in each state 34124139Sjoerg(sleeping, running, starting, zombies, and stopped), 34224139Sjoergand a percentage of time spent in each of the processor states 34324139Sjoerg(user, nice, system, and idle). 34429329SwoschIt also includes information about physical and virtual memory allocation. 34524139Sjoerg.PP 34624139SjoergThe remainder of the screen displays information about individual 34724139Sjoergprocesses. This display is similar in spirit to 34824139Sjoerg.IR ps (1) 349168799Srafanbut it is not exactly the same. PID is the process id, 350168799SrafanJID, when displayed, is the 351168799Srafan.IR jail (8) 352168799SrafanID corresponding to the process, 353168799SrafanUSERNAME is the name of the process's owner (if 35424139Sjoerg.B \-u 35524139Sjoergis specified, a UID column will be substituted for USERNAME), 35624139SjoergPRI is the current priority of the process, 35724139SjoergNICE is the nice amount (in the range \-20 to 20), 35824139SjoergSIZE is the total size of the process (text, data, and stack), 35924139SjoergRES is the current amount of resident memory (both SIZE and RES are 36024139Sjoerggiven in kilobytes), 361158653SkeramidaSTATE is the current state (one of \*(lqSTART\*(rq, \*(lqRUN\*(rq 362158653Skeramida(shown as \*(lqCPUn\*(rq on SMP systems), \*(lqSLEEP\*(rq, \*(lqSTOP\*(rq, 363158653Skeramida\*(lqZOMB\*(rq, \*(lqWAIT\*(rq, \*(lqLOCK\*(rq or the event on which the 364158653Skeramidaprocess waits), 365158653SkeramidaC is the processor number on which the process is executing 366158653Skeramida(visible only on SMP systems), 36724139SjoergTIME is the number of system and user cpu seconds that the process has used, 36824139SjoergWCPU, when displayed, is the weighted cpu percentage (this is the same 36924139Sjoergvalue that 37024139Sjoerg.IR ps (1) 37124139Sjoergdisplays as CPU), 37224139SjoergCPU is the raw percentage and is the field that is sorted to determine 37324139Sjoergthe order of the processes, and 37424139SjoergCOMMAND is the name of the command that the process is currently running 37524139Sjoerg(if the process is swapped out, this column is marked \*(lq<swapped>\*(rq). 37624139Sjoerg.SH NOTES 377222532SjhbIf a process is in the \*(lqSLEEP\*(rq or \*(lqLOCK\*(rq state, 378222532Sjhbthe state column will report the name of the event or lock on which the 379222532Sjhbprocess is waiting. 380222532SjhbLock names are prefixed with an asterisk \*(lq*\*(rq while sleep events 381222532Sjhbare not. 38224139Sjoerg.SH AUTHOR 38324139SjoergWilliam LeFebvre, EECS Department, Northwestern University 38424139Sjoerg.SH ENVIRONMENT 38524139Sjoerg.DT 38624139SjoergTOP user-configurable defaults for options. 38724139Sjoerg.SH FILES 38824139Sjoerg.DT 38924139Sjoerg/dev/kmem kernel memory 39024139Sjoerg.br 39124139Sjoerg/dev/mem physical memory 39224139Sjoerg.br 39324139Sjoerg/etc/passwd used to map uid numbers to user names 39424139Sjoerg.br 395119491Seivind/boot/kernel/kernel system image 39624139Sjoerg.SH BUGS 39724139SjoergDon't shoot me, but the default for 39824139Sjoerg.B \-I 39924139Sjoerghas changed once again. So many people were confused by the fact that 40024139Sjoerg.I top 40124139Sjoergwasn't showing them all the processes that I have decided to make the 40224139Sjoergdefault behavior show idle processes, just like it did in version 2. 40324139SjoergBut to appease folks who can't stand that behavior, I have added the 40424139Sjoergability to set \*(lqdefault\*(rq options in the environment variable 40524139Sjoerg.B TOP 40624139Sjoerg(see the OPTIONS section). Those who want the behavior that version 40724139Sjoerg3.0 had need only set the environment variable 40824139Sjoerg.B TOP 40924139Sjoergto \*(lq\-I\*(rq. 41024139Sjoerg.PP 41124139SjoergThe command name for swapped processes should be tracked down, but this 41224139Sjoergwould make the program run slower. 41324139Sjoerg.PP 41424139SjoergAs with 41524139Sjoerg.IR ps (1), 41624139Sjoergthings can change while 41724139Sjoerg.I top 41824139Sjoergis collecting information for an update. The picture it gives is only a 41924139Sjoergclose approximation to reality. 42024139Sjoerg.SH "SEE ALSO" 42124139Sjoergkill(1), 42224139Sjoergps(1), 42324139Sjoergstty(1), 42424139Sjoergmem(4), 42524139Sjoergrenice(8) 426