From 1b9d0472b72177a604d3c5dd26d25eec00049bd2 Mon Sep 17 00:00:00 2001 From: joerg Date: Sun, 23 Mar 1997 18:51:21 +0000 Subject: This is the long-awaited import of top into the base system (actually, the src/contrib/top part right now). This tools is simply too system- dependant to maintain it in the ports collection. --- contrib/top/top.X | 324 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 324 insertions(+) create mode 100644 contrib/top/top.X (limited to 'contrib/top/top.X') diff --git a/contrib/top/top.X b/contrib/top/top.X new file mode 100644 index 0000000..219e2fb --- /dev/null +++ b/contrib/top/top.X @@ -0,0 +1,324 @@ +.\" NOTE: changes to the manual page for "top" should be made in the +.\" file "top.X" and NOT in the file "top.1". +.nr N %topn% +.nr D %delay% +.TH TOP 1 Local +.UC 4 +.SH NAME +top \- display and update information about the top cpu processes +.SH SYNOPSIS +.B top +[ +.B \-SbiInqu +] [ +.BI \-d count +] [ +.BI \-s time +] [ +.BI \-o field +] [ +.BI \-U username +] [ +.I number +] +.SH DESCRIPTION +.\" This defines appropriate quote strings for nroff and troff +.ds lq \&" +.ds rq \&" +.if t .ds lq `` +.if t .ds rq '' +.\" Just in case these number registers aren't set yet... +.if \nN==0 .nr N 10 +.if \nD==0 .nr D 5 +.I Top +displays the top +.if !\nN==-1 \nN +processes on the system and periodically updates this information. +.if \nN==-1 \ +\{\ +If standard output is an intelligent terminal (see below) then +as many processes as will fit on the terminal screen are displayed +by default. Otherwise, a good number of them are shown (around 20). +.\} +Raw cpu percentage is used to rank the processes. If +.I number +is given, then the top +.I number +processes will be displayed instead of the default. +.PP +.I Top +makes a distinction between terminals that support advanced capabilities +and those that do not. This +distinction affects the choice of defaults for certain options. In the +remainder of this document, an \*(lqintelligent\*(rq terminal is one that +supports cursor addressing, clear screen, and clear to end of line. +Conversely, a \*(lqdumb\*(rq terminal is one that does not support such +features. If the output of +.I top +is redirected to a file, it acts as if it were being run on a dumb +terminal. +.SH OPTIONS +.TP +.B \-S +Show system processes in the display. Normally, system processes such as +the pager and the swapper are not shown. This option makes them visible. +.TP +.B \-b +Use \*(lqbatch\*(rq mode. In this mode, all input from the terminal is +ignored. Interrupt characters (such as ^C and ^\e) still have an effect. +This is the default on a dumb terminal, or when the output is not a terminal. +.TP +.B \-i +Use \*(lqinteractive\*(rq mode. In this mode, any input is immediately +read for processing. See the section on \*(lqInteractive Mode\*(rq +for an explanation of +which keys perform what functions. After the command is processed, the +screen will immediately be updated, even if the command was not +understood. This mode is the default when standard output is an +intelligent terminal. +.TP +.B \-I +Do not display idle processes. +By default, top displays both active and idle processes. +.TP +.B \-n +Use \*(lqnon-interactive\*(rq mode. This is indentical to \*(lqbatch\*(rq +mode. +.TP +.B \-q +Renice +.I top +to -20 so that it will run faster. This can be used when the system is +being very sluggish to improve the possibility of discovering the problem. +This option can only be used by root. +.TP +.B \-u +Do not take the time to map uid numbers to usernames. Normally, +.I top +will read as much of the file \*(lq/etc/passwd\*(rq as is necessary to map +all the user id numbers it encounters into login names. This option +disables all that, while possibly decreasing execution time. The uid +numbers are displayed instead of the names. +.TP +.BI \-d count +Show only +.I count +displays, then exit. A display is considered to be one update of the +screen. This option allows the user to select the number of displays he +wants to see before +.I top +automatically exits. For intelligent terminals, no upper limit +is set. The default is 1 for dumb terminals. +.TP +.BI \-s time +Set the delay between screen updates to +.I time +seconds. The default delay between updates is \nD seconds. +.TP +.BI \-o field +Sort the process display area on the specified field. The field name is +the name of the column as seen in the output, but in lower case. Likely +values are \*(lqcpu\*(rq, \*(lqsize\*(rq, \*(lqres\*(rq, and \*(lqtime\*(rq, +but may vary on different operating systems. Note that +not all operating systems support this option. +.TP +.BI \-U username +Show only those processes owned by +.IR username . +This option currently only accepts usernames and will not understand +uid numbers. +.PP +Both +.I count +and +.I number +fields can be specified as \*(lqinfinite\*(rq, indicating that they can +stretch as far as possible. This is accomplished by using any proper +prefix of the keywords +\*(lqinfinity\*(rq, +\*(lqmaximum\*(rq, +or +\*(lqall\*(rq. +The default for +.I count +on an intelligent terminal is, in fact, +.BI infinity . +.PP +The environment variable +.B TOP +is examined for options before the command line is scanned. This enables +a user to set his or her own defaults. The number of processes to display +can also be specified in the environment variable +.BR TOP . +The options +.BR \-I , +.BR \-S , +and +.B \-u +are actually toggles. A second specification of any of these options +will negate the first. Thus a user who has the environment variable +.B TOP +set to \*(lq\-I\*(rq may use the command \*(lqtop \-I\*(rq to see idle processes. +.SH "INTERACTIVE MODE" +When +.I top +is running in \*(lqinteractive mode\*(rq, it reads commands from the +terminal and acts upon them accordingly. In this mode, the terminal is +put in \*(lqCBREAK\*(rq, so that a character will be +processed as soon as it is typed. Almost always, a key will be +pressed when +.I top +is between displays; that is, while it is waiting for +.I time +seconds to elapse. If this is the case, the command will be +processed and the display will be updated immediately thereafter +(reflecting any changes that the command may have specified). This +happens even if the command was incorrect. If a key is pressed while +.I top +is in the middle of updating the display, it will finish the update and +then process the command. Some commands require additional information, +and the user will be prompted accordingly. While typing this information +in, the user's erase and kill keys (as set up by the command +.IR stty ) +are recognized, and a newline terminates the input. +.PP +These commands are currently recognized (^L refers to control-L): +.TP +.B ^L +Redraw the screen. +.IP "\fBh\fP\ or\ \fB?\fP" +Display a summary of the commands (help screen). +.TP +.B q +Quit +.IR top. +.TP +.B d +Change the number of displays to show (prompt for new number). +Remember that the next display counts as one, so typing +.B d1 +will make +.I top +show one final display and then immediately exit. +.TP +.B n or # +Change the number of processes to display (prompt for new number). +.TP +.B s +Change the number of seconds to delay between displays +(prompt for new number). +.TP +.B k +Send a signal (\*(lqkill\*(rq by default) to a list of processes. This +acts similarly to the command +.IR kill (1)). +.TP +.B r +Change the priority (the \*(lqnice\*(rq) of a list of processes. +This acts similarly to the command +.IR renice (8)). +.TP +.B u +Display only processes owned by a specific username (prompt for username). +If the username specified is simply \*(lq+\*(rq, then processes belonging +to all users will be displayed. +.TP +.B e +Display a list of system errors (if any) generated by the last +.BR k ill +or +.BR r enice +command. +.TP +.B i +(or +.BR I) +Toggle the display of idle processes. +.SH "THE DISPLAY" +The actual display varies depending on the specific variant of Unix +that the machine is running. This description may not exactly match +what is seen by top running on this particular machine. Differences +are listed at the end of this manual entry. +.PP +The top few lines of the display show general information +about the state of the system, including +the last process id assigned to a process (on most systems), +the three load averages, +the current time, +the number of existing processes, +the number of processes in each state +(sleeping, running, starting, zombies, and stopped), +and a percentage of time spent in each of the processor states +(user, nice, system, and idle). +It also includes information about physial and virtual memory allocation. +.PP +The remainder of the screen displays information about individual +processes. This display is similar in spirit to +.IR ps (1) +but it is not exactly the same. PID is the process id, USERNAME is the name +of the process's owner (if +.B \-u +is specified, a UID column will be substituted for USERNAME), +PRI is the current priority of the process, +NICE is the nice amount (in the range \-20 to 20), +SIZE is the total size of the process (text, data, and stack), +RES is the current amount of resident memory (both SIZE and RES are +given in kilobytes), +STATE is the current state (one of \*(lqsleep\*(rq, \*(lqWAIT\*(rq, +\*(lqrun\*(rq, \*(lqidl\*(rq, \*(lqzomb\*(rq, or \*(lqstop\*(rq), +TIME is the number of system and user cpu seconds that the process has used, +WCPU, when displayed, is the weighted cpu percentage (this is the same +value that +.IR ps (1) +displays as CPU), +CPU is the raw percentage and is the field that is sorted to determine +the order of the processes, and +COMMAND is the name of the command that the process is currently running +(if the process is swapped out, this column is marked \*(lq\*(rq). +.SH NOTES +The \*(lqABANDONED\*(rq state (known in the kernel as \*(lqSWAIT\*(rq) was +abandoned, thus the name. A process should never end up in this state. +.SH AUTHOR +William LeFebvre, EECS Department, Northwestern University +.SH ENVIRONMENT +.DT +TOP user-configurable defaults for options. +.SH FILES +.DT +/dev/kmem kernel memory +.br +/dev/mem physical memory +.br +/etc/passwd used to map uid numbers to user names +.br +/vmunix system image +.SH BUGS +Don't shoot me, but the default for +.B \-I +has changed once again. So many people were confused by the fact that +.I top +wasn't showing them all the processes that I have decided to make the +default behavior show idle processes, just like it did in version 2. +But to appease folks who can't stand that behavior, I have added the +ability to set \*(lqdefault\*(rq options in the environment variable +.B TOP +(see the OPTIONS section). Those who want the behavior that version +3.0 had need only set the environment variable +.B TOP +to \*(lq\-I\*(rq. +.PP +The command name for swapped processes should be tracked down, but this +would make the program run slower. +.PP +As with +.IR ps (1), +things can change while +.I top +is collecting information for an update. The picture it gives is only a +close approximation to reality. +.SH "SEE ALSO" +kill(1), +ps(1), +stty(1), +mem(4), +renice(8) -- cgit v1.1