top.xs revision 169257
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 169257 2007-05-04 15:42:58Z rafan $ 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[ 13168799Srafan.B \-abCHIijnqStuv 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 9224139Sjoerg.B \-i 9324139SjoergUse \*(lqinteractive\*(rq mode. In this mode, any input is immediately 9424139Sjoergread for processing. See the section on \*(lqInteractive Mode\*(rq 9524139Sjoergfor an explanation of 9624139Sjoergwhich keys perform what functions. After the command is processed, the 9724139Sjoergscreen will immediately be updated, even if the command was not 9824139Sjoergunderstood. This mode is the default when standard output is an 9924139Sjoergintelligent terminal. 10024139Sjoerg.TP 10124139Sjoerg.B \-I 10224139SjoergDo not display idle processes. 10324139SjoergBy default, top displays both active and idle processes. 10424139Sjoerg.TP 105168799Srafan.B \-j 106168799SrafanDisplay the 107168799Srafan.IR jail (8) 108169257SrafanID. 109168799Srafan.TP 11038090Sdes.B \-t 11138090SdesDo not display the 11238090Sdes.I top 11338090Sdesprocess. 11438090Sdes.TP 115131402Salfred.BI \-m display 116131402SalfredDisplay either 'cpu' or 'io' statistics. Default is 'cpu'. 117131402Salfred.TP 11824139Sjoerg.B \-n 11928935SjmgUse \*(lqnon-interactive\*(rq mode. This is identical to \*(lqbatch\*(rq 12024139Sjoergmode. 12124139Sjoerg.TP 12224139Sjoerg.B \-q 12324139SjoergRenice 12424139Sjoerg.I top 12524139Sjoergto -20 so that it will run faster. This can be used when the system is 12624139Sjoergbeing very sluggish to improve the possibility of discovering the problem. 12724139SjoergThis option can only be used by root. 12824139Sjoerg.TP 12924139Sjoerg.B \-u 13024139SjoergDo not take the time to map uid numbers to usernames. Normally, 13124139Sjoerg.I top 13224139Sjoergwill read as much of the file \*(lq/etc/passwd\*(rq as is necessary to map 13324139Sjoergall the user id numbers it encounters into login names. This option 13424139Sjoergdisables all that, while possibly decreasing execution time. The uid 13524139Sjoergnumbers are displayed instead of the names. 13624139Sjoerg.TP 13789756Sdwmalone.B \-v 13889756SdwmaloneWrite version number information to stderr then exit immediately. 13989756SdwmaloneNo other processing takes place when this option is used. To see current 14089756Sdwmalonerevision information while top is running, use the help command \*(lq?\*(rq. 14189756Sdwmalone.TP 14224139Sjoerg.BI \-d count 14324139SjoergShow only 14424139Sjoerg.I count 14524139Sjoergdisplays, then exit. A display is considered to be one update of the 14624139Sjoergscreen. This option allows the user to select the number of displays he 14724139Sjoergwants to see before 14824139Sjoerg.I top 14924139Sjoergautomatically exits. For intelligent terminals, no upper limit 15024139Sjoergis set. The default is 1 for dumb terminals. 15124139Sjoerg.TP 15224139Sjoerg.BI \-s time 15324139SjoergSet the delay between screen updates to 15424139Sjoerg.I time 15524139Sjoergseconds. The default delay between updates is \nD seconds. 15624139Sjoerg.TP 15724139Sjoerg.BI \-o field 15824139SjoergSort the process display area on the specified field. The field name is 15924139Sjoergthe name of the column as seen in the output, but in lower case. Likely 16024139Sjoergvalues are \*(lqcpu\*(rq, \*(lqsize\*(rq, \*(lqres\*(rq, and \*(lqtime\*(rq, 16124139Sjoergbut may vary on different operating systems. Note that 16224139Sjoergnot all operating systems support this option. 16324139Sjoerg.TP 16424139Sjoerg.BI \-U username 16524139SjoergShow only those processes owned by 16624139Sjoerg.IR username . 16724139SjoergThis option currently only accepts usernames and will not understand 16824139Sjoerguid numbers. 16924139Sjoerg.PP 17024139SjoergBoth 17124139Sjoerg.I count 17224139Sjoergand 17324139Sjoerg.I number 17424139Sjoergfields can be specified as \*(lqinfinite\*(rq, indicating that they can 17524139Sjoergstretch as far as possible. This is accomplished by using any proper 17624139Sjoergprefix of the keywords 17724139Sjoerg\*(lqinfinity\*(rq, 17824139Sjoerg\*(lqmaximum\*(rq, 17924139Sjoergor 18024139Sjoerg\*(lqall\*(rq. 18124139SjoergThe default for 18224139Sjoerg.I count 18324139Sjoergon an intelligent terminal is, in fact, 18424139Sjoerg.BI infinity . 18524139Sjoerg.PP 18624139SjoergThe environment variable 18724139Sjoerg.B TOP 18824139Sjoergis examined for options before the command line is scanned. This enables 18924139Sjoerga user to set his or her own defaults. The number of processes to display 19024139Sjoergcan also be specified in the environment variable 19124139Sjoerg.BR TOP . 19224139SjoergThe options 19324139Sjoerg.BR \-I , 19424139Sjoerg.BR \-S , 19538090Sdes.BR \-u , 19624139Sjoergand 19738090Sdes.B \-t 19824139Sjoergare actually toggles. A second specification of any of these options 19924139Sjoergwill negate the first. Thus a user who has the environment variable 20024139Sjoerg.B TOP 20124139Sjoergset to \*(lq\-I\*(rq may use the command \*(lqtop \-I\*(rq to see idle processes. 20224139Sjoerg.SH "INTERACTIVE MODE" 20324139SjoergWhen 20424139Sjoerg.I top 20524139Sjoergis running in \*(lqinteractive mode\*(rq, it reads commands from the 20624139Sjoergterminal and acts upon them accordingly. In this mode, the terminal is 20724139Sjoergput in \*(lqCBREAK\*(rq, so that a character will be 20824139Sjoergprocessed as soon as it is typed. Almost always, a key will be 20924139Sjoergpressed when 21024139Sjoerg.I top 21124139Sjoergis between displays; that is, while it is waiting for 21224139Sjoerg.I time 21324139Sjoergseconds to elapse. If this is the case, the command will be 21424139Sjoergprocessed and the display will be updated immediately thereafter 21524139Sjoerg(reflecting any changes that the command may have specified). This 21624139Sjoerghappens even if the command was incorrect. If a key is pressed while 21724139Sjoerg.I top 21824139Sjoergis in the middle of updating the display, it will finish the update and 21924139Sjoergthen process the command. Some commands require additional information, 22024139Sjoergand the user will be prompted accordingly. While typing this information 22124139Sjoergin, the user's erase and kill keys (as set up by the command 22224139Sjoerg.IR stty ) 22324139Sjoergare recognized, and a newline terminates the input. 22424139Sjoerg.PP 22524139SjoergThese commands are currently recognized (^L refers to control-L): 22624139Sjoerg.TP 22724139Sjoerg.B ^L 22824139SjoergRedraw the screen. 22924139Sjoerg.IP "\fBh\fP\ or\ \fB?\fP" 23089756SdwmaloneDisplay a summary of the commands (help screen). Version information 23189756Sdwmaloneis included in this display. 23224139Sjoerg.TP 23324139Sjoerg.B q 23424139SjoergQuit 23524139Sjoerg.IR top. 23624139Sjoerg.TP 23724139Sjoerg.B d 23824139SjoergChange the number of displays to show (prompt for new number). 23924139SjoergRemember that the next display counts as one, so typing 24024139Sjoerg.B d1 24124139Sjoergwill make 24224139Sjoerg.I top 24324139Sjoergshow one final display and then immediately exit. 24424139Sjoerg.TP 245131402Salfred.B m 246131402SalfredToggle the display between 'cpu' and 'io' modes. 247131402Salfred.TP 24824139Sjoerg.B n or # 24924139SjoergChange the number of processes to display (prompt for new number). 25024139Sjoerg.TP 25124139Sjoerg.B s 25224139SjoergChange the number of seconds to delay between displays 25324139Sjoerg(prompt for new number). 25424139Sjoerg.TP 255132005Salfred.B S 256132005SalfredToggle the display of system processes. 257132005Salfred.TP 258169237Sstas.B a 259169237SstasToggle the display of process titles. 260169237Sstas.TP 26124139Sjoerg.B k 26224139SjoergSend a signal (\*(lqkill\*(rq by default) to a list of processes. This 26324139Sjoergacts similarly to the command 26424139Sjoerg.IR kill (1)). 26524139Sjoerg.TP 26624139Sjoerg.B r 26724139SjoergChange the priority (the \*(lqnice\*(rq) of a list of processes. 26824139SjoergThis acts similarly to the command 26924139Sjoerg.IR renice (8)). 27024139Sjoerg.TP 27124139Sjoerg.B u 27224139SjoergDisplay only processes owned by a specific username (prompt for username). 27324139SjoergIf the username specified is simply \*(lq+\*(rq, then processes belonging 27424139Sjoergto all users will be displayed. 27524139Sjoerg.TP 27689756Sdwmalone.B o 27789756SdwmaloneChange the order in which the display is sorted. This command is not 278151697Skeramidaavailable on all systems. The sort key names vary from system to system 27989756Sdwmalonebut usually include: \*(lqcpu\*(rq, \*(lqres\*(rq, \*(lqsize\*(rq, 28089756Sdwmalone\*(lqtime\*(rq. The default is cpu. 28189756Sdwmalone.TP 28224139Sjoerg.B e 28324139SjoergDisplay a list of system errors (if any) generated by the last 28424139Sjoerg.BR k ill 28524139Sjoergor 28624139Sjoerg.BR r enice 28724139Sjoergcommand. 28824139Sjoerg.TP 28924139Sjoerg.B i 29024139Sjoerg(or 291143520Sbrueffer.BR I ) 29224139SjoergToggle the display of idle processes. 29338279Sdes.TP 294168799Srafan.B j 295168799SrafanToggle the display of 296168799Srafan.IR jail (8) 297169257SrafanID. 298168799Srafan.TP 29938090Sdes.B t 30038090SdesToggle the display of the 30138090Sdes.I top 30238090Sdesprocess. 30324139Sjoerg.SH "THE DISPLAY" 30424139SjoergThe actual display varies depending on the specific variant of Unix 30524139Sjoergthat the machine is running. This description may not exactly match 30624139Sjoergwhat is seen by top running on this particular machine. Differences 30724139Sjoergare listed at the end of this manual entry. 30824139Sjoerg.PP 30924139SjoergThe top few lines of the display show general information 31024139Sjoergabout the state of the system, including 31124139Sjoergthe last process id assigned to a process (on most systems), 31224139Sjoergthe three load averages, 31324139Sjoergthe current time, 31424139Sjoergthe number of existing processes, 31524139Sjoergthe number of processes in each state 31624139Sjoerg(sleeping, running, starting, zombies, and stopped), 31724139Sjoergand a percentage of time spent in each of the processor states 31824139Sjoerg(user, nice, system, and idle). 31929329SwoschIt also includes information about physical and virtual memory allocation. 32024139Sjoerg.PP 32124139SjoergThe remainder of the screen displays information about individual 32224139Sjoergprocesses. This display is similar in spirit to 32324139Sjoerg.IR ps (1) 324168799Srafanbut it is not exactly the same. PID is the process id, 325168799SrafanJID, when displayed, is the 326168799Srafan.IR jail (8) 327168799SrafanID corresponding to the process, 328168799SrafanUSERNAME is the name of the process's owner (if 32924139Sjoerg.B \-u 33024139Sjoergis specified, a UID column will be substituted for USERNAME), 33124139SjoergPRI is the current priority of the process, 33224139SjoergNICE is the nice amount (in the range \-20 to 20), 33324139SjoergSIZE is the total size of the process (text, data, and stack), 33424139SjoergRES is the current amount of resident memory (both SIZE and RES are 33524139Sjoerggiven in kilobytes), 336158653SkeramidaSTATE is the current state (one of \*(lqSTART\*(rq, \*(lqRUN\*(rq 337158653Skeramida(shown as \*(lqCPUn\*(rq on SMP systems), \*(lqSLEEP\*(rq, \*(lqSTOP\*(rq, 338158653Skeramida\*(lqZOMB\*(rq, \*(lqWAIT\*(rq, \*(lqLOCK\*(rq or the event on which the 339158653Skeramidaprocess waits), 340158653SkeramidaC is the processor number on which the process is executing 341158653Skeramida(visible only on SMP systems), 34224139SjoergTIME is the number of system and user cpu seconds that the process has used, 34324139SjoergWCPU, when displayed, is the weighted cpu percentage (this is the same 34424139Sjoergvalue that 34524139Sjoerg.IR ps (1) 34624139Sjoergdisplays as CPU), 34724139SjoergCPU is the raw percentage and is the field that is sorted to determine 34824139Sjoergthe order of the processes, and 34924139SjoergCOMMAND is the name of the command that the process is currently running 35024139Sjoerg(if the process is swapped out, this column is marked \*(lq<swapped>\*(rq). 35124139Sjoerg.SH NOTES 35224139SjoergThe \*(lqABANDONED\*(rq state (known in the kernel as \*(lqSWAIT\*(rq) was 35324139Sjoergabandoned, thus the name. A process should never end up in this state. 35424139Sjoerg.SH AUTHOR 35524139SjoergWilliam LeFebvre, EECS Department, Northwestern University 35624139Sjoerg.SH ENVIRONMENT 35724139Sjoerg.DT 35824139SjoergTOP user-configurable defaults for options. 35924139Sjoerg.SH FILES 36024139Sjoerg.DT 36124139Sjoerg/dev/kmem kernel memory 36224139Sjoerg.br 36324139Sjoerg/dev/mem physical memory 36424139Sjoerg.br 36524139Sjoerg/etc/passwd used to map uid numbers to user names 36624139Sjoerg.br 367119491Seivind/boot/kernel/kernel system image 36824139Sjoerg.SH BUGS 36924139SjoergDon't shoot me, but the default for 37024139Sjoerg.B \-I 37124139Sjoerghas changed once again. So many people were confused by the fact that 37224139Sjoerg.I top 37324139Sjoergwasn't showing them all the processes that I have decided to make the 37424139Sjoergdefault behavior show idle processes, just like it did in version 2. 37524139SjoergBut to appease folks who can't stand that behavior, I have added the 37624139Sjoergability to set \*(lqdefault\*(rq options in the environment variable 37724139Sjoerg.B TOP 37824139Sjoerg(see the OPTIONS section). Those who want the behavior that version 37924139Sjoerg3.0 had need only set the environment variable 38024139Sjoerg.B TOP 38124139Sjoergto \*(lq\-I\*(rq. 38224139Sjoerg.PP 38324139SjoergThe command name for swapped processes should be tracked down, but this 38424139Sjoergwould make the program run slower. 38524139Sjoerg.PP 38624139SjoergAs with 38724139Sjoerg.IR ps (1), 38824139Sjoergthings can change while 38924139Sjoerg.I top 39024139Sjoergis collecting information for an update. The picture it gives is only a 39124139Sjoergclose approximation to reality. 39224139Sjoerg.SH "SEE ALSO" 39324139Sjoergkill(1), 39424139Sjoergps(1), 39524139Sjoergstty(1), 39624139Sjoergmem(4), 39724139Sjoergrenice(8) 398