top man page on Ubuntu

Man page or keyword search:  
man Server   6591 pages
apropos Keyword Search (all sections)
Output format
Ubuntu logo
[printable version]

TOP(1)			   Linux User's Manual			   TOP(1)

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 per‐
       sonal configuration  --	encompassing every aspect of  its  opera‐
       tion.   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)  Mes‐
       sage/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' inter‐
	    active 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 infor‐
	    mation  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  associ‐
       ated  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 infor‐
       mation 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 run‐
	  ning 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 'Cumu‐
	  lative 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	 interac‐
	  tive	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  avail‐
	  able.

       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  ('Sys‐
	  tem.map'),  this field will show the name or the address of the
	  kernel function in which the task is currently sleeping.   Run‐
	  ning 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 sup‐
	  pressed.     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 win‐
       dows/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 permit‐
	  ting).   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 corre‐
	  sponding 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 pro‐
	  cesses.

	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 inter‐
	  rupts.

	si  --	Software Interrupts
	  The amount of time the CPU has been servicing	 software  inter‐
	  rupts.

	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.   How‐
	      ever,  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 pro‐
	      vide 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-dis‐
	      play mode.

	 <=> :Exit_Task_Limits
	      Removes  restrictions  on which tasks are shown.	This com‐
	      mand 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 ´cur‐
	      rent' 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  mono‐
	      chrome 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 sec‐
	      ond line.

	 <G> :Choose_Another_Window/Field_Group
	      You will be prompted to enter a number between 1 and 4 des‐
	      ignating	the  window/field  group which should be made the
	      ´current' window.	 You  will  soon  grow	comfortable  with
	      these 4 windows, especially after experimenting with alter‐
	      nate-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 filesys‐
	      tem 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  fol‐
	      lowing 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 com‐
	      mand 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 win‐
	      dows.   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'	 interac‐
       tive 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  ´cur‐
	      rent' 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 por‐
	      tion 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 win‐
       dow, you would be left with just the message line.  In  that  way,
       you will have maximized available task rows but (temporarily) sac‐
       rificed the program name in full-screen mode or the ´current' win‐
       dow 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  alter‐
       nate-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 prob‐
	      ably don't need a constant  visual  reminder  of	the  sort
	      field  and top hopes that you always run with 'column high‐
	      light' 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 dis‐
	      played.  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 rep‐
	      resentation 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 dis‐
	      play.  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 win‐
	      dow'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 dis‐
	      play.  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  cur‐
	      rently  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 vis‐
	 ible 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  dis‐
	      played,  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 dis‐
	      playable.

	      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 reap‐
       ply  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 sum‐
	      mary 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  dis‐
	      play(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 dis‐
	      plays 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 des‐
	      ignating	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 run‐
       ning.  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  maxi‐
	    mize 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  illus‐
	    trate 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 run‐
	    ning 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 mem‐
	    ory;  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 pro‐
	    cesses 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 ´cur‐
	    rent' 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 visi‐
	    ble/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).

Linux			      September 2002			   TOP(1)
[top]

List of man pages available for Ubuntu

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net