Provided by: procps_3.2.8-9ubuntu3_i386 bug

NAME

       top - display Linux tasks

SYNOPSIS

       top -hv | -bcHisS -d delay -n iterations -p pid [, pid ...]

       The traditional switches ’-’ and whitespace are optional.

DESCRIPTION

       The  top program provides a dynamic real-time view of a running system.
       It can display system summary information as well as a  list  of  tasks
       currently  being  managed  by  the  Linux  kernel.  The types of system
       summary information shown and the types, order and size of  information
       displayed  for  tasks  are all user configurable and that configuration
       can be made persistent across restarts.

       The program  provides  a  limited  interactive  interface  for  process
       manipulation  as  well  as a much more extensive interface for personal
       configuration  --  encompassing every aspect  of  its  operation.   And
       while top is referred to throughout this document, you are free to name
       the program anything you wish.  That new name, possibly an alias,  will
       then  be reflected on top’s display and used when reading and writing a
       configuration file.

OVERVIEW

   Documentation
       The remaining Table of Contents
           1. COMMAND-LINE Options
           2. FIELDS / Columns
              a. DESCRIPTIONS of Fields
              b. SELECTING and ORDERING Columns
           3. INTERACTIVE Commands
              a. GLOBAL Commands
              b. SUMMARY Area Commands
              c. TASK Area Commands
              d. COLOR Mapping
           4. ALTERNATE-DISPLAY Mode
              a. WINDOWS Overview
              b. COMMANDS for Windows
           5. FILES
              a. SYSTEM Configuration File
              b. PERSONAL Configuration File
           6. STUPID TRICKS Sampler
              a. Kernel Magic
              b. Bouncing Windows
              c. The Big Bird Window
           7. BUGS, 8. HISTORY Former top, 9. AUTHOR, 10. SEE ALSO

   Operation
       When operating top, the two most important keys are help (’h’  or  ’?’)
       and   quit   (’q’)  key.   Alternatively,  you  could  simply  use  the
       traditional interrupt key (’^C’) when you’re done.

       When you start top for the first time, you’ll  be  presented  with  the
       traditional  screen  elements: 1) Summary Area; 2) Message/Prompt Line;
       3) Columns  Header;  4)  Task  Area.   There  will,  however,  be  some
       differences when compared to the former top.

       Highlighting
          Summary_Area:  There  is  no  highlighting  for load/uptime and only
          values are highlighted for other elements.

          Task_Area: Tasks running (or ready to run) will be highlighted,  and
          bold is only one way of emphasizing such processes.

       Content/Labels
          Summary_Area: The program name is shown, perhaps a symlink or alias.
          The Cpu(s) state label hints at  other  possibilities.   The  memory
          stats use a lower case ’k’.

          Columns_Header: Will show a new field and some changed labels.  More
          new fields will be found as you customize your top.

       Note: the width of top’s display will  be  limited  to  512  positions.
       Displaying  all  fields  requires  a  minimum  of  160 characters.  The
       remaining width could be used for the ’Command’ column.

   Startup Defaults
       The following startup defaults assume no configuration  file,  thus  no
       user customizations.  Even so, items shown with an asterisk (’*’) could
       be overridden through the command-line.

           Global_defaults
              ’A’ - Alt display      Off (full-screen)
            * ’d’ - Delay time       3.0 seconds
              ’I’ - Irix mode        On  (no, ’solaris’ smp)
            * ’p’ - PID monitoring   Off
            * ’s’ - Secure mode      Off (unsecured)
              ’B’ - Bold enable      Off
           Summary_Area_defaults
              ’l’ - Load Avg/Uptime  On  (thus program name)
              ’t’ - Task/Cpu states  On  (1+1 lines, see ’1’)
              ’m’ - Mem/Swap usage   On  (2 lines worth)
              ’1’ - Single Cpu       On  (thus 1 line if smp)
           Task_Area_defaults
              ’b’ - Bold hilite      On  (not ’reverse’)
            * ’c’ - Command line     Off (name, not cmdline)
            * ’H’ - Threads          Off (show all threads)
            * ’i’ - Idle tasks       On  (show all tasks)
              ’R’ - Reverse sort     On  (pids high-to-low)
            * ’S’ - Cumulative time  Off (no, dead children)
              ’x’ - Column hilite    Off (no, sort field)
              ’y’ - Row hilite       On  (yes, running tasks)
              ’z’ - color/mono       Off (no, colors)

1. COMMAND-LINE Options

       The command-line syntax for top consists of:

            -hv | -bcHisS -d delay -n iterations -p pid [,pid...]

       The  typically  mandatory  switches  (’-’)  and  even  whitespace   are
       completely optional.

       -b : Batch mode operation
            Starts  top  in  ’Batch  mode’,  which could be useful for sending
            output from top to other programs or to a file.  In this mode, top
            will  not  accept input and runs until the iterations limit you’ve
            set with the ’-n’ command-line option or until killed.

       -c : Command line/Program name toggle
            Starts top with the last remembered ’c’ state reversed.  Thus,  if
            top was displaying command lines, now that field will show program
            names, and visa  versa.   See  the  ’c’  interactive  command  for
            additional information.

       -d : Delay time interval as:  -d ss.tt (seconds.tenths)
            Specifies  the  delay  between  screen  updates, and overrides the
            corresponding value in one’s personal configuration  file  or  the
            startup  default.   Later  this can be changed with the ’d’ or ’s’
            interactive commands.

            Fractional seconds are honored,  but  a  negative  number  is  not
            allowed.   In  all  cases, however, such changes are prohibited if
            top is running in ’Secure mode’, except for root (unless  the  ’s’
            command-line  option  was  used).   For  additional information on
            ’Secure mode’ see topic 5a. SYSTEM Configuration File.

       -h : Help
            Show library version and the usage prompt, then quit.

       -H : Threads toggle
            Starts top with the last remembered ’H’ state reversed.  When this
            toggle   is   On,   all  individual  threads  will  be  displayed.
            Otherwise, top displays a summation of all threads in a process.

       -i : Idle Processes toggle
            Starts top with the last remembered ’i’ state reversed.  When this
            toggle  is  Off,  tasks  that  are  idled  or  zombied will not be
            displayed.

       -n : Number of iterations limit as:  -n number
            Specifies the maximum number of iterations, or frames, top  should
            produce before ending.

       -u : Monitor by user as:  -u somebody
            Monitor only processes with an effective UID or user name matching
            that given.

       -U : Monitor by user as:  -U somebody
            Monitor only processes with a  UID  or  user  name  matching  that
            given.   This matches real, effective, saved, and filesystem UIDs.

       -p : Monitor PIDs as:  -pN1 -pN2 ...  or  -pN1, N2 [,...]
            Monitor only processes with specified process  IDs.   This  option
            can  be given up to 20 times, or you can provide a comma delimited
            list  with  up  to  20  pids.   Co-mingling  both  approaches   is
            permitted.

            This is a command-line option only.  And should you wish to return
            to normal operation, it is not necessary to quit and  and  restart
            top  --  just issue the ’=’ interactive command.

       -s : Secure mode operation
            Starts  top  with secure mode forced, even for root.  This mode is
            far better controlled through the system configuration  file  (see
            topic 5. FILES).

       -S : Cumulative time mode toggle
            Starts  top  with  the  last  remembered ’S’ state reversed.  When
            ’Cumulative mode’ is On, each process is listed with the cpu  time
            that  it and its dead children have used.  See the ’S’ interactive
            command for additional information regarding this mode.

       -v : Version
            Show library version and the usage prompt, then quit.

2. FIELDS / Columns

   2a. DESCRIPTIONS of Fields
       Listed below are top’s available fields.  They  are  always  associated
       with  the  letter  shown,  regardless  of  the  position  you  may have
       established for them with the ’o’ (Order fields) interactive command.

       Any field is selectable as the sort field, and you control whether they
       are  sorted  high-to-low or low-to-high.  For additional information on
       sort provisions see topic 3c. TASK Area Commands.

       a: PID  --  Process Id
          The task’s unique process ID, which periodically wraps, though never
          restarting at zero.

       b: PPID  --  Parent Process Pid
          The process ID of a task’s parent.

       c: RUSER  --  Real User Name
          The real user name of the task’s owner.

       d: UID  --  User Id
          The effective user ID of the task’s owner.

       e: USER  --  User Name
          The effective user name of the task’s owner.

       f: GROUP  --  Group Name
          The effective group name of the task’s owner.

       g: TTY  --  Controlling Tty
          The  name  of  the controlling terminal.  This is usually the device
          (serial port, pty, etc.) from which the  process  was  started,  and
          which  it  uses  for  input  or output.  However, a task need not be
          associated with a terminal, in which case you’ll see ’?’  displayed.

       h: PR  --  Priority
          The priority of the task.

       i: NI  --  Nice value
          The  nice  value  of  the  task.  A negative nice value means higher
          priority, whereas a positive nice value means lower priority.   Zero
          in  this  field  simply  means  priority  will  not  be  adjusted in
          determining a task’s dispatchability.

       j: P  --  Last used CPU (SMP)
          A number representing the  last  used  processor.   In  a  true  SMP
          environment  this  will  likely  change  frequently since the kernel
          intentionally uses weak affinity.  Also, the very act of running top
          may break this weak affinity and cause more processes to change CPUs
          more often (because of the extra demand for cpu time).

       k: %CPU  --  CPU usage
          The task’s share of the elapsed  CPU  time  since  the  last  screen
          update,  expressed as a percentage of total CPU time.  In a true SMP
          environment, if ’Irix mode’ is Off, top  will  operate  in  ’Solaris
          mode’  where  a task’s cpu usage will be divided by the total number
          of CPUs.  You toggle ’Irix/Solaris’ modes with the  ’I’  interactive
          command.

       l: TIME  --  CPU Time
          Total CPU time the task has used since it started.  When ’Cumulative
          mode’ is On, each process is listed with the cpu time  that  it  and
          its  dead children has used.  You toggle ’Cumulative mode’ with ’S’,
          which is a command-line option and an interactive command.  See  the
          ’S’  interactive  command  for additional information regarding this
          mode.

       m: TIME+  --  CPU Time, hundredths
          The  same  as  ’TIME’,  but  reflecting  more  granularity   through
          hundredths of a second.

       n: %MEM  --  Memory usage (RES)
          A task’s currently used share of available physical memory.

       o: VIRT  --  Virtual Image (kb)
          The  total  amount  of virtual memory used by the task.  It includes
          all code, data and  shared  libraries  plus  pages  that  have  been
          swapped out and pages that have been mapped but not used.

       p: SWAP  --  Swapped size (kb)
          Memory  that  is  not  resident  but  is present in a task.  This is
          memory that has been swapped out but could include  additional  non-
          resident  memory.  This column is calculated by subtracting physical
          memory from virtual memory.

       q: RES  --  Resident size (kb)
          The non-swapped physical memory a task has used.

       r: CODE  --  Code size (kb)
          The amount of virtual memory devoted to executable code, also  known
          as the ’text resident set’ size or TRS.

       s: DATA  --  Data+Stack size (kb)
          The  amount of virtual memory devoted to other than executable code,
          also known as the ’data resident set’ size or DRS.

       t: SHR  --  Shared Mem size (kb)
          The amount of shared memory used by  a  task.   It  simply  reflects
          memory that could be potentially shared with other processes.

       u: nFLT  --  Page Fault count
          The  number  of  major page faults that have occurred for a task.  A
          page fault occurs when a process attempts to read from or write to a
          virtual  page that is not currently present in its address space.  A
          major page fault is when backing storage access (such as a disk)  is
          involved in making that page available.

       v: nDRT  --  Dirty Pages count
          The  number  of  pages  that have been modified since they were last
          written to disk.  Dirty pages must be written  to  disk  before  the
          corresponding  physical  memory  location can be used for some other
          virtual page.

       w: S  --  Process Status
          The status of the task which can be one of:
             ’D’ = uninterruptible sleep
             ’R’ = running
             ’S’ = sleeping
             ’T’ = traced or stopped
             ’Z’ = zombie

          Tasks shown as running should be more properly thought of as  ’ready
          to  run’   --   their task_struct is simply represented on the Linux
          run-queue.  Even without a true SMP machine, you  may  see  numerous
          tasks  in  this  state  depending  on  top’s delay interval and nice
          value.

       x: Command  --  Command line or Program name
          Display the command line used to start a task or  the  name  of  the
          associated  program.   You toggle between command line and name with
          ’c’, which is both a command-line option and an interactive command.

          When  you’ve  chosen  to  display command lines, processes without a
          command line (like kernel threads)  will  be  shown  with  only  the
          program name in parentheses, as in this example:
                ( mdrecoveryd )

          Either  form  of  display is subject to potential truncation if it’s
          too long to fit in this field’s current width.  That  width  depends
          upon  other  fields  selected,  their  order  and the current screen
          width.

          Note: The ’Command’ field/column is unique, in that it is not fixed-
          width.   When displayed, this column will be allocated all remaining
          screen width (up to the maximum 512 characters) to provide  for  the
          potential growth of program names into command lines.

       y: WCHAN  --  Sleeping in Function
          Depending on the availability of the kernel link map (’System.map’),
          this field will show the name or the address of the kernel  function
          in which the task is currently sleeping.  Running tasks will display
          a dash (’-’) in this column.

          Note: By displaying this  field,  top’s  own  working  set  will  be
          increased  by over 700Kb.  Your only means of reducing that overhead
          will be to stop and restart top.

       z: Flags  --  Task Flags
          This column represents the task’s current scheduling flags which are
          expressed  in hexadecimal notation and with zeros suppressed.  These
          flags are officially documented  in  <linux/sched.h>.   Less  formal
          documentation  can  also  be found on the ’Fields select’ and ’Order
          fields’ screens.

   2b. SELECTING and ORDERING Columns
       After pressing the interactive commands  ’f’  (Fields  select)  or  ’o’
       (Order fields) you will be shown a screen containing the current fields
       string followed by names and descriptions for all fields.

       Here is a sample fields string from one  of  top’s  four  windows/field
       groups and an explanation of the conventions used:

       -  Sample fields string:
             ANOPQRSTUVXbcdefgjlmyzWHIK

       -  The  order  of  displayed  fields  corresponds  to  the order of the
          letters in that string.

       -  If the letter is upper case the corresponding field itself will then
          be  shown  as  part  of  the task display (screen width permitting).
          This will also be indicated by a leading asterisk (’*’), as in  this
          excerpt:
              ...
              * K: %CPU       = CPU usage
                l: TIME       = CPU Time
                m: TIME+      = CPU Time, hundredths
              * N: %MEM       = Memory usage (RES)
              * O: VIRT       = Virtual Image (kb)
              ...

       Fields select screen  --  the ’f’ interactive command
          You   toggle   the  display  of  a  field  by  simply  pressing  the
          corresponding letter.

       Order fields screen  --  the ’o’ interactive command
          You move a field to the left by  pressing  the  corresponding  upper
          case letter and to the right with the lower case letter.

   2c. CPU States
       The  CPU states are shown in the Summary Area. They are always shown as
       a percentage and are for the time between now and the last refresh.

        us  --  User CPU time
          The time the CPU has spent running users’  processes  that  are  not
          niced.

        sy  --  System CPU time
          The time the CPU has spent running the kernel and its processes.

        ni  --  Nice CPU time
          The  time  the  CPU has spent running users’ proccess that have been
          niced.

        wa  --  iowait
          Amount of time the CPU has been waiting for I/O to complete.

        hi  --  Hardware IRQ
          The amount of time the CPU has been servicing hardware interrupts.

        si  --  Software Interrupts
          The amount of time the CPU has been servicing software interrupts.

        st  --  Steal Time
          The amount  of  CPU  ’stolen’  from  this  virtual  machine  by  the
          hypervisor   for  other  tasks  (such  as  running  another  virtual
          machine).

3. INTERACTIVE Commands

       Listed below is a brief index  of  commands  within  categories.   Some
       commands  appear  more  than  once  --  their meaning or scope may vary
       depending on the context in which they are issued.

         3a. GLOBAL_Commands
               <Ret/Sp> ?, =, A, B, d, G, h, I, k, q, r, s, W, Z
         3b. SUMMARY_Area_Commands
               l, m, t, 1
         3c. TASK_Area_Commands
               Appearance:  b, x, y, z
               Content:     c, f, H, o, S, u
               Size:        #, i, n
               Sorting:     <, >, F, O, R
         3d. COLOR_Mapping
               <Ret>, a, B, b, H, M, q, S, T, w, z, 0 - 7
         4b. COMMANDS_for_Windows
               -, _, =, +, A, a, G, g, w

   3a. GLOBAL Commands
       The  global  interactive  commands  are  always   available   in   both
       full-screen  mode  and  alternate-display mode.  However, some of these
       interactive commands are not available when running in ’Secure mode’.

       If you wish to know in  advance  whether  or  not  your  top  has  been
       secured,  simply ask for help and view the system summary on the second
       line.

         <Enter> or <Space> :Refresh_Display
              These commands do nothing, they are  simply  ignored.   However,
              they  will  awaken  top  and  following receipt of any input the
              entire display will be repainted.

              Use either of these keys if you have a large delay interval  and
              wish to see current status,

         <?> or <h> :Help
              There  are  two help levels available.  The first will provide a
              reminder of all the  basic  interactive  commands.   If  top  is
              secured, that screen will be abbreviated.

              Typing  ’h’ or ’?’ on that help screen will take you to help for
              those interactive commands applicable to alternate-display mode.

         <=> :Exit_Task_Limits
              Removes  restrictions  on  which  tasks are shown.  This command
              will reverse any ’i’ (idle tasks) and ’n’ (max  tasks)  commands
              that  might  be active.  It also provides for an ’exit’ from PID
              monitoring.  See the ’-p’ command-line option for  a  discussion
              of PID monitoring.

              When  operating  in  alternate-display  mode  this command has a
              slightly broader meaning.

         <A> :Alternate_Display_Mode_toggle
              This  command  will  switch   between   full-screen   mode   and
              alternate-display mode.  See topic 4. ALTERNATE-DISPLAY Mode and
              the ’G’ interactive command for insight into  ´current’  windows
              and field groups.

         <B> :Bold_Disable/Enable_toggle
              This   command   will  influence  use  of  the  ’bold’  terminfo
              capability and alters both the summary area and  task  area  for
              the  ´current’  window.   While it is intended primarily for use
              with dumb terminals, it can be applied anytime.

              Note: When this toggle is On and top is operating in  monochrome
              mode,  the  entire  display  will  appear as normal text.  Thus,
              unless  the  ’x’  and/or  ’y’  toggles  are  using  reverse  for
              emphasis,  there  will  be  no visual confirmation that they are
              even on.

       * <d> or <s> :Change_Delay_Time_interval
              You will be prompted  to  enter  the  delay  time,  in  seconds,
              between display updates.

              Fractional  seconds  are  honored,  but a negative number is not
              allowed.  Entering 0 causes (nearly) continuous updates, with an
              unsatisfactory  display as the system and tty driver try to keep
              up  with  top’s  demands.   The   delay   value   is   inversely
              proportional to system loading, so set it with care.

              If  at  any time you wish to know the current delay time, simply
              ask for help and view the system summary on the second line.

         <G> :Choose_Another_Window/Field_Group
              You will  be  prompted  to  enter  a  number  between  1  and  4
              designating  the  window/field  group  which  should be made the
              ´current’ window.  You will soon grow comfortable with  these  4
              windows,  especially  after experimenting with alternate-display
              mode.

         <I> :Irix/Solaris_Mode_toggle
              When operating in ’Solaris mode’ (’I’ toggled Off), a task’s cpu
              usage  will  be  divided  by  the  total  number of CPUs.  After
              issuing this command, you’ll be informed of  the  new  state  of
              this toggle.

         <u> :select a user
              You  will  be  prompted  for  a  UID or username. Only processes
              belonging to the selected user will be  displayed.  This  option
              matches on the effective UID.

         <U> :select a user
              You  will  be  prompted  for  a  UID or username. Only processes
              belonging to the selected user will be  displayed.  This  option
              matches on the real, effective, saved, and filesystem UID.

       * <k> :Kill_a_task
              You will be prompted for a PID and then the signal to send.  The
              default  signal,  as  reflected  in  the  prompt,  is   SIGTERM.
              However, you can send any signal, via number or name.

              If  you  wish to abort the kill process, do one of the following
              depending on your progress:
                 1) at the pid prompt, just press <Enter>
                 2) at the signal prompt, type 0

         <q> :Quit

       * <r> :Renice_a_Task
              You will be prompted for a PID and then the value to nice it to.
              Entering a positive value will cause a process to lose priority.
              Conversely, a negative value will cause a process to  be  viewed
              more favorably by the kernel.

         <W> :Write_the_Configuration_File
              This  will save all of your options and toggles plus the current
              display mode and delay  time.   By  issuing  this  command  just
              before  quitting  top, you will be able restart later in exactly
              that same state.

         <Z> :Change_Color_Mapping
              This key will take you to a separate screen where you can change
              the  colors  for  the ´current’ window, or for all windows.  For
              details regarding this interactive command see topic  3d.  COLOR
              Mapping.

       *  The  commands  shown  with  an  asterisk  (’*’) are not available in
          ’Secure mode’, nor will they be shown on the level-1 help screen.

   3b. SUMMARY Area Commands
       The summary area interactive commands  are  always  available  in  both
       full-screen mode and alternate-display mode.  They affect the beginning
       lines of your display and will determine the position of  messages  and
       prompts.

       These  commands  always  impact  just the ´current’ window/field group.
       See topic 4. ALTERNATE-DISPLAY Mode and the ’G’ interactive command for
       insight into ´current’ windows and field groups.

         <l> :Toggle_Load_Average/Uptime  --  On/Off
              This  is  also the line containing the program name (possibly an
              alias) when operating  in  full-screen  mode  or  the  ´current’
              window name when operating in alternate-display mode.

         <m> :Toggle_Memory/Swap_Usage  --  On/Off
              This command affects two summary area lines.

         <t> :Toggle_Task/Cpu_States  --  On/Off
              This  command  affects  from  2  to  many  summary  area  lines,
              depending on the state of the ’1’ toggle and whether or not  top
              is running under true SMP.

         <1> :Toggle_Single/Separate_Cpu_States  --  On/Off
              This command affects how the ’t’ command’s Cpu States portion is
              shown.   Although  this  toggle  exists   primarily   to   serve
              massively-parallel  SMP machines, it is not restricted to solely
              SMP environments.

              When you see ’Cpu(s):’ in the summary area, the ’1’ toggle is On
              and   all   cpu  information  is  gathered  in  a  single  line.
              Otherwise, each cpu is displayed  separately  as:  ’Cpu0,  Cpu1,
              ...’

       Note:  If  the entire summary area has been toggled Off for any window,
       you would be left with just the message line.  In that  way,  you  will
       have  maximized  available  task  rows but (temporarily) sacrificed the
       program name in full-screen mode or the ´current’ window name  when  in
       alternate-display mode.

   3c. TASK Area Commands
       The  task area interactive commands are always available in full-screen
       mode.

       The  task  area   interactive   commands   are   never   available   in
       alternate-display  mode if the ´current’ window’s task display has been
       toggled Off (see topic 4. ALTERNATE-DISPLAY Mode).

       APPEARANCE of task window
         The following commands will also be influenced by the  state  of  the
         global ’B’ (bold disable) toggle.

         <b> :Bold/Reverse_toggle
              This  command  will  impact  how  the  ’x’  and  ’y’ toggles are
              displayed.  Further, it will only be available when at least one
              of those toggles is On.

         <x> :Column_Highlight_toggle
              Changes  highlighting  for the current sort field.  You probably
              don’t need a constant visual reminder of the sort field and  top
              hopes  that  you  always run with ’column highlight’ Off, due to
              the cost in path-length.

              If you forget which field is being sorted this command can serve
              as a quick visual reminder.

         <y> :Row_Highlight_toggle
              Changes   highlighting  for  "running"  tasks.   For  additional
              insight into this task state,  see  topic  2a.  DESCRIPTIONS  of
              Fields, Process Status.

              Use  of  this  provision  provides  important  insight into your
              system’s health.  The only costs will be a  few  additional  tty
              escape sequences.

         <z> :Color/Monochrome_toggle
              Switches  the  ´current’  window  between  your  last used color
              scheme and the older form of black-on-white  or  white-on-black.
              This  command will alter both the summary area and task area but
              does not affect the state of the ’x’, ’y’ or ’b’ toggles.

       CONTENT of task window
         <c> :Command_Line/Program_Name_toggle
              This command will be honored whether or not the ’Command’ column
              is  currently visible.  Later, should that field come into view,
              the change you applied will be seen.

         <f> and <o> :Fields_select or Order_fields
              These keys display separate screens where you can  change  which
              fields   are   displayed   and   their  order.   For  additional
              information  on  these  interactive  commands  see   topic   2b.
              SELECTING and ORDERING Columns.

         <S> :Cumulative_Time_Mode_toggle
              When   this  toggle  is  On,  all  individual  threads  will  be
              displayed.  Otherwise, top displays a summation of  all  threads
              in a process.

         ´S´ :Cumulative_Time_Mode_toggle
              When  ’Cumulative  mode’  is On, each process is listed with the
              cpu time that it and its dead children have used.

              When Off, programs that  fork  into  many  separate  tasks  will
              appear less demanding.  For programs like ’init’ or a shell this
              is appropriate but for  others,  like  compilers,  perhaps  not.
              Experiment with two task windows sharing the same sort field but
              with different ’S’  states  and  see  which  representation  you
              prefer.

              After  issuing this command, you’ll be informed of the new state
              of this toggle.  If you wish to know in advance whether  or  not
              ’Cumulative mode’ is in effect, simply ask for help and view the
              window summary on the second line.

         <u> :Show_Specific_User_Only
              You will be prompted to enter the name of the user  to  display.
              Thereafter,  in that task window only matching User ID’s will be
              shown, or possibly no tasks will be shown.

              Later, if you wish to monitor all  tasks  again,  re-issue  this
              command  but just press <Enter> at the prompt, without providing
              a name.

       SIZE of task window
         <i> :Idle_Processes_toggle
              Displays all tasks or just active tasks.  When  this  toggle  is
              Off, idled or zombied processes will not be displayed.

              If  this  command  is  applied  to the last task display when in
              alternate-display mode, then it will  not  affect  the  window’s
              size, as all prior task displays will have already been painted.

         <n> or <#> :Set_Maximum_Tasks
              You will be prompted to enter the number of  tasks  to  display.
              The  lessor  of  your  number  and available screen rows will be
              used.

              When used in alternate-display mode, this is  the  command  that
              gives  you  precise  control  over  the  size  of each currently
              visible task display, except for the very  last.   It  will  not
              affect  the  last window’s size, as all prior task displays will
              have already been painted.

              Note: If you wish to increase the size of the last visible  task
              display when in alternate-display mode, simply decrease the size
              of the task display(s) above it.

       SORTING of task window
         For compatibility, this top supports most  of  the  former  top  sort
         keys.   Since  this is primarily a service to former top users, these
         commands do not appear on any help screen.
            command   sorted field                  supported
              A         start time (non-display)      No
              M         %MEM                          Yes
              N         PID                           Yes
              P         %CPU                          Yes
              T         TIME+                         Yes

         Before using any of the following sort provisions, top suggests  that
         you temporarily turn on column highlighting using the ’x’ interactive
         command.  That will help ensure  that  the  actual  sort  environment
         matches your intent.

         The  following  interactive  commands  will  only be honored when the
         current sort field is visible.  The sort field might not  be  visible
         because:
              1) there is insufficient Screen Width
              2) the ’f’ interactive command turned it Off

         <<> :Move_Sort_Field_Left
              Moves  the sort column to the left unless the current sort field
              is the first field being displayed.

         <>> :Move_Sort_Field_Right
              Moves the sort column to the right unless the current sort field
              is the last field being displayed.

         The  following interactive commands will always be honored whether or
         not the current sort field is visible.

         <F> or <O> :Select_Sort_Field
              These keys display a separate screen where you can change  which
              field is used as the sort column.

              If a field is selected which was not previously being displayed,
              it will be forced  On  when  you  return  to  the  top  display.
              However,  depending upon your screen width and the order of your
              fields, this sort field may not be displayable.

              This interactive command can  be  a  convenient  way  to  simply
              verify  the  current  sort  field,  when running top with column
              highlighting turned Off.

         <R> :Reverse/Normal_Sort_Field_toggle
              Using this interactive command you can alternate  between  high-
              to-low and low-to-high sorts.

         Note:  Field  sorting  uses  internal  values,  not  those  in column
         display.  Thus, the TTY and WCHAN fields will  violate  strict  ASCII
         collating sequence.

   3d. COLOR Mapping
       When  you issue the ’Z’ interactive command, you will be presented with
       a separate screen.  That screen can be used to  change  the  colors  in
       just  the  ´current’  window or in all four windows before returning to
       the top display.

       Available interactive commands
           4 upper case letters to select a target
           8 numbers to select a color
           normal toggles available
               ’B’       :bold disable/enable
               ’b’       :running tasks "bold"/reverse
               ’z’       :color/mono
           other commands available
               ’a’/’w’   :apply, then go to next/prior
               <Enter>   :apply and exit
               ’q’       :abandon current changes and exit

       If your use ’a’ or ’w’ to cycle the  targeted  window,  you  will  have
       applied  the color scheme that was displayed when you left that window.
       You can, of course, easily return to any window and  reapply  different
       colors or turn colors Off completely with the ’z’ toggle.

       The  Color  Mapping  screen  can  also  be used to change the ´current’
       window/field group in  either  full-screen  mode  or  alternate-display
       mode.   Whatever  was  targeted when ’q’ or <Enter> was pressed will be
       made current as you return to the top display.

4. ALTERNATE-DISPLAY Mode

   4a. WINDOWS Overview
       Field Groups/Windows:
              In full-screen mode there is a single window represented by  the
              entire  screen.   That  single  window  can  still be changed to
              display 1 of 4 different field groups (see the  ’G’  interactive
              command,  repeated  below).   Each  of  the 4 field groups has a
              unique  separately  configurable  summary  area  and   its   own
              configurable task area.

              In  alternate-display  mode, those 4 underlying field groups can
              now be  made  visible  simultaneously,  or  can  be  turned  Off
              individually at your command.

              The  summary  area  will  always  exist,  even  if it’s only the
              message line.  At any given time only one summary  area  can  be
              displayed.   However, depending on your commands, there could be
              from zero to four separate task displays  currently  showing  on
              the screen.

       Current Window:
              The  ´current’  window is the window associated with the summary
              area and the window to which task related  commands  are  always
              directed.   Since  in  alternate-display mode you can toggle the
              task display Off, some commands  might  be  restricted  for  the
              ´current’ window.

              A  further  complication  arises when you have toggled the first
              summary area line Off.  With the loss of the  window  name  (the
              ’l’  toggled  line),  you’ll  not easily know what window is the
              ´current’ window.

   4b. COMMANDS for Windows
         <-> and <_> :Show/Hide_Window(s)_toggles
              The ’-’ key turns the ´current’ window’s  task  display  On  and
              Off.  When On, that task area will show a minimum of the columns
              header you’ve established with the ’f’  and  ’o’  commands.   It
              will  also  reflect  any  other task area options/toggles you’ve
              applied yielding zero or more tasks.

              The ’_’ key does the same  for  all  task  displays.   In  other
              words, it switches between the currently visible task display(s)
              and any task display(s) you had toggled  Off.   If  all  4  task
              displays  are  currently  visible, this interactive command will
              leave the summary area as the only display element.

       * <=> and <+> :Equalize_(re-balance)_Window(s)
              The ’=’ key forces the ´current’ window’s  task  display  to  be
              visible.   It  also  reverses  any ’i’ (idle tasks) and ’n’ (max
              tasks) commands that might be active.

              The ’+’ key does the  same  for  all  windows.   The  four  task
              displays  will  reappear,  evenly balanced.  They will also have
              retained any customizations you had previously  applied,  except
              for the ’i’ (idle tasks) and ’n’ (max tasks) commands.

       * <A> :Alternate_Display_Mode_toggle
              This   command   will   switch   between  full-screen  mode  and
              alternate-display mode.

              The first time you issue this command, all  four  task  displays
              will  be  shown.  Thereafter when you switch modes, you will see
              only the task display(s) you’ve chosen to make visible.

       * <a> and <w> :Next_Window_Forward/Backward
              This will change the ´current’ window, which in turn changes the
              window  to  which  commands  are  directed.  These keys act in a
              circular fashion so you can reach any desired  ´current’  window
              using either key.

              Assuming  the  window  name is visible (you have not toggled ’l’
              Off),   whenever   the   ´current’   window   name   loses   its
              emphasis/color,  that’s  a  reminder the task display is Off and
              many commands will be restricted.

       * <G> :Choose_Another_Window/Field_Group
              You will  be  prompted  to  enter  a  number  between  1  and  4
              designating  the  window/field  group  which  should be made the
              ´current’ window.

              In full-screen mode, this command  is  necessary  to  alter  the
              ´current’  window.   In  alternate-display  mode, it is simply a
              less convenient alternative to the ’a’ and ’w’ commands.

         <g> :Change_Window/Field_Group_Name
              You will be prompted for  a  new  name  to  be  applied  to  the
              ´current’  window.   It does not require that the window name be
              visible (the ’l’ toggle to be On).

       *  The interactive commands shown  with  an  asterisk  (’*’)  have  use
          beyond alternate-display mode.
              ’=’, ’A’, ’G’  are always available
              ’a’, ’w’       act the same when color mapping

5. FILES

   5a. SYSTEM Configuration File
       The  presence  of  this file will influence which version of the ’help’
       screen is shown to an ordinary user.  More importantly, it  will  limit
       what  ordinary  users are allowed to do when top is running.  They will
       not be able to issue the following commands.
          k         Kill a task
          r         Renice a task
          d or s    Change delay/sleep interval

       The system configuration file is  not  created  by  top.   Rather,  you
       create this file manually and place it in the /etc directory.  Its name
       must be ’toprc’ and must have no leading ’.’ (period).   It  must  have
       only two lines.

       Here is an example of the contents of /etc/toprc:
          s         # line 1: ’secure’ mode switch
          5.0       # line 2: ’delay’  interval in seconds

   5b. PERSONAL Configuration File
       This  file  is written as ’$HOME/.your-name-4-top’ + ’rc’.  Use the ’W’
       interactive command to create it or update it.

       Here is the general layout:
          global    # line 1: the program name/alias notation
            "       # line 2: id,altscr,irixps,delay,curwin
          per ea    # line a: winname,fieldscur
          window    # line b: winflags,sortindx,maxtasks
            "       # line c: summclr,msgsclr,headclr,taskclr

       If the $HOME variable is  not  present,  top  will  try  to  write  the
       personal  configuration  file  to  the  current  directory,  subject to
       permissions.

6. STUPID TRICKS Sampler

       Many of these ’tricks’ work best when you give top a scheduling  boost.
       So  plan  on starting him with a nice value of -10, assuming you’ve got
       the authority.

   6a. Kernel Magic
       For these stupid tricks, top needs full-screen mode.

       -*-  The  user  interface,  through  prompts  and  help,  intentionally
            implies  that the delay interval is limited to tenths of a second.
            However, you’re free to set any desired delay.  If you want to see
            Linux  at his scheduling best, try a delay of .09 seconds or less.

            For this experiment, under x-windows open an  xterm  and  maximize
            it.  Then do the following:
              . provide a scheduling boost and tiny delay via:
                  nice -n -10 top -d.09
              . keep sorted column highlighting Off to minimize
                path length
              . turn On reverse row highlighting for emphasis
              . try various sort columns (TIME/MEM work well),
                and normal or reverse sorts to bring the most
                active processes into view

            What  you’ll  see is a very busy Linux doing what he’s always done
            for you, but there was no program available to illustrate this.

       -*-  Under an xterm using ’white-on-black’ colors,  try  setting  top’s
            task  color  to black and be sure that task highlighting is set to
            bold, not reverse.  Then set  the  delay  interval  to  around  .3
            seconds.

            After  bringing  the  most active processes into view, what you’ll
            see are the ghostly images of just the currently running tasks.

       -*-  Delete the existing rcfile, or create a new symlink.   Start  this
            new  version  then type ’T’ (a secret key, see topic 3c. TASK Area
            Commands, Sorting) followed by ’W’ and ’q’.  Finally, restart  the
            program with -d0 (zero delay).

            Your  display  will  be  refreshed  at three times the rate of the
            former top, a 300%  speed  advantage.   As  top  climbs  the  TIME
            ladder,  be  as patient as you can while speculating on whether or
            not top will ever reach the top.

   6b. Bouncing Windows
       For these stupid tricks, top needs alternate-display mode.

       -*-  With 3 or 4 task displays visible, pick any window other than  the
            last  and turn idle processes Off.  Depending on where you applied
            ’i’, sometimes several task displays are  bouncing  and  sometimes
            it’s like an accordion, as top tries his best to allocate space.

       -*-  Set  each  window’s summary lines differently: one with no memory;
            another with no states; maybe one with nothing at  all,  just  the
            message  line.  Then hold down ’a’ or ’w’ and watch a variation on
            bouncing windows  --  hopping windows.

       -*-  Display all 4 windows and for each, in turn, set idle processes to
            Off.  You’ve just entered the "extreme bounce" zone.

   6c. The Big Bird Window
       This stupid trick also requires alternate-display mode.

       -*-  Display  all  4  windows and make sure that 1:Def is the ´current’
            window.  Then, keep increasing window size until the all the other
            task displays are "pushed out of the nest".

            When    they’ve   all   been   displaced,   toggle   between   all
            visible/invisible windows.  Then ponder this:
               is top fibbing or telling honestly your imposed truth?

7. BUGS

       Send bug reports to:
          Albert D. Cahalan, <albert@users.sf.net>

8. HISTORY Former top

       The  original  top  was  written  by  Roger  Binns,  based  on   Branko
       Lankester’s <lankeste@fwi.uva.nl> ps program.

       Robert  Nation  <nation@rocket.sanders.lockheed.com> adapted it for the
       proc file system.

       Helmut Geyer  <Helmut.Geyer@iwr.uni-heidelberg.de>  added  support  for
       configurable fields.

       Plus many other individuals contributed over the years.

9. AUTHOR

       This entirely new and enhanced replacement was written by:
          Jim / James C. Warner, <warnerjc@worldnet.att.net>

       With invaluable help from:
          Albert D. Cahalan, <albert@users.sf.net>
          Craig Small, <csmall@small.dropbear.id.au>

10. SEE ALSO

       free(1), ps(1), uptime(1), atop(1), slabtop(1), vmstat(8), w(1).