[BACK]Return to top.1 CVS log [TXT][DIR] Up to [local] / src / usr.bin / top

Diff for /src/usr.bin/top/top.1 between version 1.1 and 1.2

version 1.1, 1997/08/14 14:00:25 version 1.2, 1997/08/14 15:05:03
Line 1 
Line 1 
 .\"     $OpenBSD$  .\"     $OpenBSD$
 .nr N 15  .\"
 .nr D 5  .\" Copyright (c) 1997, Jason Downs.  All rights reserved.
 .TH TOP 1 Local  .\"
 .UC 4  .\" Redistribution and use in source and binary forms, with or without
 .SH NAME  .\" modification, are permitted provided that the following conditions
 top \- display and update information about the top cpu processes  .\" are met:
 .SH SYNOPSIS  .\" 1. Redistributions of source code must retain the above copyright
 .B top  .\"    notice, this list of conditions and the following disclaimer.
 [  .\" 2. Redistributions in binary form must reproduce the above copyright
 .B \-SbiInqu  .\"    notice, this list of conditions and the following disclaimer in the
 ] [  .\"    documentation and/or other materials provided with the distribution.
 .BI \-d count  .\" 3. All advertising materials mentioning features or use of this software
 ] [  .\"    must display the following acknowledgement:
 .BI \-s time  .\"      This product includes software developed by Jason Downs for the
 ] [  .\"      OpenBSD system.
 .BI \-o field  .\" 4. Neither the name(s) of the author(s) nor the name OpenBSD
 ] [  .\"    may be used to endorse or promote products derived from this software
 .BI \-U username  .\"    without specific prior written permission.
 ] [  .\"
 .I number  .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS
 ]  .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 .SH DESCRIPTION  .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 .\" This defines appropriate quote strings for nroff and troff  .\" DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT,
 .ds lq \&"  .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 .ds rq \&"  .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 .if t .ds lq ``  .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 .if t .ds rq ''  .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 .\" Just in case these number registers aren't set yet...  .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 .if \nN==0 .nr N 10  .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .if \nD==0 .nr D 5  .\" SUCH DAMAGE.
 .I Top  .\"
 displays the top  .Dd August 14, 1997
 .if !\nN==-1 \nN  .Dt TOP 1
 processes on the system and periodically updates this information.  .Os OpenBSD
 .if \nN==-1 \  .Sh NAME
 \{\  .Nm top
 If standard output is an intelligent terminal (see below) then  .Nd display and update information about the top cpu processes
   .Sh SYNOPSIS
   .Nm
   .Op Fl SbiInqu
   .Op Fl d Ar count
   .Op Fl s Ar time
   .\" .Op Fl o Ar field
   .Op Fl U Ar username
   .Op Ar number
   .Sh DESCRIPTION
   .Nm
   displays the top processes on the system and periodically updates this
   information.  If standard output is an intelligent terminal (see below) then
 as many processes as will fit on the terminal screen are displayed  as many processes as will fit on the terminal screen are displayed
 by default.  Otherwise, a good number of them are shown (around 20).  by default.  Otherwise, a good number of them are shown (around 20).
 .\}  
 Raw cpu percentage is used to rank the processes.  If  Raw cpu percentage is used to rank the processes.  If
 .I number  .Ar number
 is given, then the top  is given, then the top
 .I number  .Ar number
 processes will be displayed instead of the default.  processes will be displayed instead of the default.
 .PP  .Pp
 .I Top  .Nm
 makes a distinction between terminals that support advanced capabilities  makes a distinction between terminals that support advanced capabilities
 and those that do not.  This  and those that do not.  This
 distinction affects the choice of defaults for certain options.  In the  distinction affects the choice of defaults for certain options.  In the
 remainder of this document, an \*(lqintelligent\*(rq terminal is one that  remainder of this document, an
 supports cursor addressing, clear screen, and clear to end of line.  .Em intelligent
 Conversely, a \*(lqdumb\*(rq terminal is one that does not support such  terminal is one that supports cursor addressing, clear screen, and clear
 features.  If the output of  to end of line.  Conversely, a
 .I top  .Em dumb
   terminal is one that does not support such features.  If the output of
   .Nm
 is redirected to a file, it acts as if it were being run on a dumb  is redirected to a file, it acts as if it were being run on a dumb
 terminal.  terminal.
 .SH OPTIONS  .Sh OPTIONS
 .TP  .Bl -tag -width XxXXXXXXXXX
 .B \-S  .It Fl S
 Show system processes in the display.  Normally, system processes such as  Show system processes in the display.  Normally, system processes such as
 the pager and the swapper are not shown.  This option makes them visible.  the pager and the swapper are not shown.  This option makes them visible.
 .TP  .It Fl b
 .B \-b  Use
 Use \*(lqbatch\*(rq mode.  In this mode, all input from the terminal is  .Em batch
   mode.  In this mode, all input from the terminal is
 ignored.  Interrupt characters (such as ^C and ^\e) still have an effect.  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.  This is the default on a dumb terminal, or when the output is not a terminal.
 .TP  .It Fl i
 .B \-i  Use
 Use \*(lqinteractive\*(rq mode.  In this mode, any input is immediately  .Em interactive
 read for processing.  See the section on \*(lqInteractive Mode\*(rq  mode.  In this mode, any input is immediately read for processing.  See the
 for an explanation of  section on
 which keys perform what functions.  After the command is processed, the  .Sx INTERACTIVE MODE
 screen will immediately be updated, even if the command was not  for an explanation of which keys perform what functions.  After the command
 understood.  This mode is the default when standard output is an  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.  intelligent terminal.
 .TP  .It Fl I
 .B \-I  
 Do not display idle processes.  Do not display idle processes.
 By default, top displays both active and idle processes.  By default, top displays both active and idle processes.
 .TP  .It Fl n
 .B \-n  Use
 Use \*(lqnon-interactive\*(rq mode.  This is indentical to \*(lqbatch\*(rq  .Em non-interactive
   mode.  This is indentical to
   .Em batch
 mode.  mode.
 .TP  .It Fl q
 .B \-q  
 Renice  Renice
 .I top  .Nm
 to -20 so that it will run faster.  This can be used when the system is  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.  being very sluggish to improve the possibility of discovering the problem.
 This option can only be used by root.  This option can only be used by root.
 .TP  .It Fl u
 .B \-u  
 Do not take the time to map uid numbers to usernames.  Normally,  Do not take the time to map uid numbers to usernames.  Normally,
 .I top  .Nm
 will read as much of the file \*(lq/etc/passwd\*(rq as is necessary to map  will read as much of the password database as is necessary to map
 all the user id numbers it encounters into login names.  This option  all the user id numbers it encounters into login names.  This option
 disables all that, while possibly decreasing execution time.  The uid  disables all that, while possibly decreasing execution time.  The uid
 numbers are displayed instead of the names.  numbers are displayed instead of the names.
 .TP  .It Fl d Ar count
 .BI \-d count  
 Show only  Show only
 .I count  .Ar count
 displays, then exit.  A display is considered to be one update of the  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  screen.  This option allows the user to select the number of displays he
 wants to see before  wants to see before
 .I top  .Nm
 automatically exits.  For intelligent terminals, no upper limit  automatically exits.  For intelligent terminals, no upper limit
 is set.  The default is 1 for dumb terminals.  is set.  The default is 1 for dumb terminals.
 .TP  .It Fl s Ar time
 .BI \-s time  
 Set the delay between screen updates to  Set the delay between screen updates to
 .I time  .Ar time
 seconds.  The default delay between updates is \nD seconds.  seconds.  The default delay between updates is 5 seconds.
 .TP  .\" .It Fl o Ar field
 .BI \-o field  .\" Sort the process display area on the specified field.  The field name is
 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
 the name of the column as seen in the output, but in lower case.  Likely  .\" values are
 values are \*(lqcpu\*(rq, \*(lqsize\*(rq, \*(lqres\*(rq, and \*(lqtime\*(rq,  .\" .Ar cpu ,
 but may vary on different operating systems.  Note that  .\" .Ar size ,
 not all operating systems support this option.  .\" .Ar res ,
 .TP  .\" and
 .BI \-U username  .\" .Ar time ,
   .\" but may vary on different operating systems.  Note that
   .\" not all operating systems support this option.
   .It Fl U Ar username
 Show only those processes owned by  Show only those processes owned by
 .IR username .  .Ar username .
 This option currently only accepts usernames and will not understand  This option currently only accepts usernames and will not understand
 uid numbers.  uid numbers.
 .PP  .El
   .Pp
 Both  Both
 .I count  .Ar count
 and  and
 .I number  .Ar number
 fields can be specified as \*(lqinfinite\*(rq, indicating that they can  fields can be specified as
 stretch as far as possible.  This is accomplished by using any proper  .Li infinite ,
 prefix of the keywords  indicating that they can stretch as far as possible.  This is accomplished
 \*(lqinfinity\*(rq,  by using any proper prefix of the keywords
 \*(lqmaximum\*(rq,  .Li infinity ,
   .Li maximum ,
 or  or
 \*(lqall\*(rq.  .Li all .
 The default for  The default for
 .I count  .Ar count
 on an intelligent terminal is, in fact,  on an intelligent terminal is, in fact,
 .BI infinity .  .Li infinity .
 .PP  .Pp
 The environment variable  The environment variable
 .B TOP  .Ev TOP
 is examined for options before the command line is scanned.  This enables  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  a user to set his or her own defaults.  The number of processes to display
 can also be specified in the environment variable  can also be specified in the environment variable
 .BR TOP .  .Ev TOP .
   .Pp
 The options  The options
 .BR \-I ,  .Fl I ,
 .BR \-S ,  .Fl S ,
 and  and
 .B \-u  .Fl u
 are actually toggles.  A second specification of any of these options  are actually toggles.  A second specification of any of these options
 will negate the first.  Thus a user who has the environment variable  will negate the first.  Thus a user who has the environment variable
 .B TOP  .Ev TOP
 set to \*(lq\-I\*(rq may use the command \*(lqtop \-I\*(rq to see idle processes.  set to
 .SH "INTERACTIVE MODE"  .Li -I
   may use the command
   .Li top -I
   to see idle processes.
   .Sh INTERACTIVE MODE
 When  When
 .I top  .Nm
 is running in \*(lqinteractive mode\*(rq, it reads commands from the  is running in
 terminal and acts upon them accordingly.  In this mode, the terminal is  .Em interactive mode ,
 put in \*(lqCBREAK\*(rq, so that a character will be  it reads commands from the terminal and acts upon them accordingly.  In this
 processed as soon as it is typed.  Almost always, a key will be  mode, the terminal is put in
 pressed when  .Dv CBREAK ,
 .I top  so that a character will be processed as soon as it is typed.  Almost always,
   a key will be pressed when
   .Nm
 is between displays; that is, while it is waiting for  is between displays; that is, while it is waiting for
 .I time  .Ar time
 seconds to elapse.  If this is the case, the command will be  seconds to elapse.  If this is the case, the command will be
 processed and the display will be updated immediately thereafter  processed and the display will be updated immediately thereafter
 (reflecting any changes that the command may have specified).  This  (reflecting any changes that the command may have specified).  This
 happens even if the command was incorrect.  If a key is pressed while  happens even if the command was incorrect.  If a key is pressed while
 .I top  .Nm
 is in the middle of updating the display, it will finish the update and  is in the middle of updating the display, it will finish the update and
 then process the command.  Some commands require additional information,  then process the command.  Some commands require additional information,
 and the user will be prompted accordingly.  While typing this 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  in, the user's erase and kill keys (as set up by the command
 .IR stty )  .Xr stty 1 )
 are recognized, and a newline terminates the input.  are recognized, and a newline terminates the input.
 .PP  .Pp
 These commands are currently recognized (^L refers to control-L):  These commands are currently recognized (^L refers to control-L):
 .TP  .Bl -tag -width XxXXXX
 .B ^L  .It ^L
 Redraw the screen.  Redraw the screen.
 .IP "\fBh\fP\ or\ \fB?\fP"  .It h or ?
 Display a summary of the commands (help screen).  Display a summary of the commands (help screen).
 .TP  .It q
 .B q  
 Quit  Quit
 .IR top.  .Nm top .
 .TP  .It d
 .B d  
 Change the number of displays to show (prompt for new number).  Change the number of displays to show (prompt for new number).
 Remember that the next display counts as one, so typing  Remember that the next display counts as one, so typing
 .B d1  .Li d1
 will make  will make
 .I top  .Nm
 show one final display and then immediately exit.  show one final display and then immediately exit.
 .TP  .It n or #
 .B n or #  
 Change the number of processes to display (prompt for new number).  Change the number of processes to display (prompt for new number).
 .TP  .It s
 .B s  
 Change the number of seconds to delay between displays  Change the number of seconds to delay between displays
 (prompt for new number).  (prompt for new number).
 .TP  .It k
 .B k  Send a signal
 Send a signal (\*(lqkill\*(rq by default) to a list of processes.  This  .Ns ( Dv TERM
 acts similarly to the command  by default) to a list of processes.  This acts similarly to the command
 .IR kill (1)).  .Xr kill 1 .
 .TP  .It r
 .B r  Change the priority (the
 Change the priority (the \*(lqnice\*(rq) of a list of processes.  .Em nice )
 This acts similarly to the command  of a list of processes.  This acts similarly to the command
 .IR renice (8)).  .Xr renice 8 .
 .TP  .It u
 .B u  
 Display only processes owned by a specific username (prompt for username).  Display only processes owned by a specific username (prompt for username).
 If the username specified is simply \*(lq+\*(rq, then processes belonging  If the username specified is simply
 to all users will be displayed.  .Dq + ,
 .TP  then processes belonging to all users will be displayed.
 .B e  .It e
 Display a list of system errors (if any) generated by the last  Display a list of system errors (if any) generated by the last
 .BR k ill  .Li kill
 or  or
 .BR r enice  .Li renice
 command.  command.
 .TP  .It i or I
 .B i  
 (or  
 .BR I)  
 Toggle the display of idle processes.  Toggle the display of idle processes.
 .SH "THE DISPLAY"  .El
 The actual display varies depending on the specific variant of Unix  .Sh THE DISPLAY
 that the machine is running.  This description may not exactly match  .\" The actual display varies depending on the specific variant of Unix
 what is seen by top running on this particular machine.  Differences  .\" that the machine is running.  This description may not exactly match
 are listed at the end of this manual entry.  .\" what is seen by top running on this particular machine.  Differences
 .PP  .\" are listed at the end of this manual entry.
   .\" .Pp
 The top few lines of the display show general information  The top few lines of the display show general information
 about the state of the system, including  about the state of the system, including
 the last process id assigned to a process (on most systems),  the last process id assigned to a process
   .\" (on most systems),
 the three load averages,  the three load averages,
 the current time,  the current time,
 the number of existing processes,  the number of existing processes,
Line 250 
Line 268 
 and a percentage of time spent in each of the processor states  and a percentage of time spent in each of the processor states
 (user, nice, system, and idle).  (user, nice, system, and idle).
 It also includes information about physial and virtual memory allocation.  It also includes information about physial and virtual memory allocation.
 .PP  .Pp
 The remainder of the screen displays information about individual  The remainder of the screen displays information about individual
 processes.  This display is similar in spirit to  processes.  This display is similar in spirit to
 .IR ps (1)  .Xr ps 1
 but it is not exactly the same.  PID is the process id, USERNAME is the name  but it is not exactly the same.  PID is the process id, USERNAME is the name
 of the process's owner (if  of the process's owner (if
 .B \-u  .Fl u
 is specified, a UID column will be substituted for USERNAME),  is specified, a UID column will be substituted for USERNAME),
 PRI is the current priority of the process,  PRI is the current priority of the process,
 NICE is the nice amount (in the range \-20 to 20),  NICE is the nice amount (in the range -20 to 20),
 SIZE is the total size of the process (text, data, and stack),  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  RES is the current amount of resident memory (both SIZE and RES are
 given in kilobytes),  given in kilobytes),
 STATE is the current state (one of \*(lqsleep\*(rq, \*(lqWAIT\*(rq,  STATE is the current state (one of
 \*(lqrun\*(rq, \*(lqidl\*(rq, \*(lqzomb\*(rq, or \*(lqstop\*(rq),  .Li sleep ,
   .Li WAIT ,
   .Li run ,
   .Li idl ,
   .Li zomb ,
   or
   .Li stop ) ,
 TIME is the number of system and user cpu seconds that the process has used,  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  WCPU, when displayed, is the weighted cpu percentage (this is the same
 value that  value that
 .IR ps (1)  .Xr ps 1
 displays as CPU),  displays as CPU),
 CPU is the raw percentage and is the field that is sorted to determine  CPU is the raw percentage and is the field that is sorted to determine
 the order of the processes, and  the order of the processes, and
 COMMAND is the name of the command that the process is currently running  COMMAND is the name of the command that the process is currently running
 (if the process is swapped out, this column is marked \*(lq<swapped>\*(rq).  (if the process is swapped out, this column is marked
 .SH NOTES  .Li <swapped> ) .
 The \*(lqABANDONED\*(rq state (known in the kernel as \*(lqSWAIT\*(rq) was  .Sh NOTES
 abandoned, thus the name.  A process should never end up in this state.  The
 .SH AUTHOR  .Em ABANDONED
   state (known in the kernel as
   .Em SWAIT
   was abandoned, thus the name.  A process should never end up in this state.
   .Sh AUTHOR
 William LeFebvre, EECS Department, Northwestern University  William LeFebvre, EECS Department, Northwestern University
 .SH ENVIRONMENT  .Sh ENVIRONMENT
 .DT  .Bl -tag -width XxXXXX
 TOP     user-configurable defaults for options.  .It Ev TOP
 .SH FILES  User-configurable defaults for options.
 .DT  .El
 /dev/kmem               kernel memory  .Sh FILES
 .br  .Bl -tag -width XxXXXXXXX -compact
 /dev/mem                physical memory  .It Pa /dev/kmem
 .br  kernel memory
 /bsd                    system image  .It Pa /dev/mem
 .SH BUGS  physical memory
   .It Pa /bsd
   kernel image
   .Sh BUGS
 Don't shoot me, but the default for  Don't shoot me, but the default for
 .B \-I  .Fl I
 has changed once again.  So many people were confused by the fact that  has changed once again.  So many people were confused by the fact that
 .I top  .Nm
 wasn't showing them all the processes that I have decided to make the  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.  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  But to appease folks who can't stand that behavior, I have added the
 ability to set \*(lqdefault\*(rq options in the environment variable  ability to set
 .B TOP  .Li default
 (see the OPTIONS section).  Those who want the behavior that version  options in the environment variable
 3.0 had need only set the environment variable  .Ev TOP
 .B TOP  (see the
 to \*(lq\-I\*(rq.  .Sx OPTIONS
 .PP  section).  Those who want the behavior that version 3.0 had need only set
   the environment variable
   .Ev TOP
   to
   .Li -I .
   .Pp
 The command name for swapped processes should be tracked down, but this  The command name for swapped processes should be tracked down, but this
 would make the program run slower.  would make the program run slower.
 .PP  .Pp
 As with  As with
 .IR ps (1),  .Xr ps 1 ,
 things can change while  things can change while
 .I top  .Nm
 is collecting information for an update.  The picture it gives is only a  is collecting information for an update.  The picture it gives is only a
 close approximation to reality.  close approximation to reality.
 .SH "SEE ALSO"  .Sh SEE ALSO
 kill(1),  .Xr kill 1 ,
 ps(1),  .Xr ps 1 ,
 stty(1),  .Xr stty 1 ,
 mem(4),  .Xr mem 4 ,
 renice(8)  .Xr renice 8 .
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2