Provided by: procps_3.2.8-1ubuntu3_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.

          VIRT = SWAP + RES.

       p: SWAP  --  Swapped size (kb)
          The swapped out portion of a task’s total virtual memory image.

       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).