contrib/top/README

   1                              TOP
   2                          Version 3.5
   3
   4                        William LeFebvre
   5                      and a cast of dozens
   6
   7
   8 If you do not want to read this entire file, then at least read
   9 the section at the end entitled "KNOWN PROBLEMS".
  10
  11 If you are having any problems getting top to work, please read the
  12 file "FAQ" *before* contacting me.  Thank you.
  13
  14 "top" is a program that will give continual reports about the state of
  15 the system, including a list of the top cpu using processes.  Version 3
  16 of "top" has three primary design goals: provide an accurate snapshot of
  17 the system and process state, not be one of the top processes itself, be
  18 as portable as possible.
  19
  20 Version 3 has many bug fixes from version 2.5, and it has also been
  21 reorganized in a major way to make it easy to port to other platforms.
  22 All system dependent code is now contained in one file.
  23
  24 Top now includes a configuration script called "Configure".  It helps
  25 the installer choose the correct parameters for this particular
  26 installation.  This script MUST be run before attempting to compile top.
  27
  28 Top requires read access to the memory files "/dev/kmem" and "/dev/mem"
  29 as well as the system image "/vmunix".  Some installations have these
  30 files protected from general access.  These sites would have to install
  31 this program in the same way that programs such as "ps" are installed.
  32 In addition, on those Unix variants that support the proc filesystem
  33 (such as SVR4 and Solaris 2), top requires read access to all the files
  34 in /proc: typically dictating that top be installed setuid to root.
  35
  36 CAVEAT: version 3 of top has internal commands that kill and renice
  37 processes.  Although I have taken steps to insure that top makes
  38 appropriate checks with these commands, I cannot guarantee that these
  39 internal commands are totally secure.  IF YOU INSTALL top as a SETUID
  40 program, you do so AT YOUR OWN RISK!  I realize that some operating
  41 systems will require top to run setuid, and I will do everything I can
  42 to make sure that top is a secure setuid program.
  43
  44 Configure will ask you to input values for certain parameters.  Before
  45 each parameter, Configure will display a description of what the
  46 parameter does.  Read the description and choose an appropriate value.
  47 Sometimes a default will appear in brackets.  Typing just return will
  48 choose the default.
  49
  50 System support now takes the form of "modules".  Adding support for
  51 a different architecture requires only adding a module.  Configure
  52 asks which module to use when it is configuring top.  See the file
  53 "Porting" for a description of how to write your own module.
  54
  55 To compile and install "top", read the file "INSTALL" and follow the
  56 directions and advice contained therein.
  57
  58 Once you have created a binary for one particular type of machine, you
  59 can reconfigure for another type with "./Configure modulename" where
  60 "modulename" is replaced with the appropriate module name.  All other
  61 parameter values are kept the same.  Note that in some cases this may
  62 not be appropriate.
  63
  64 If you make any kind of change to "top" that you feel would be
  65 beneficial to others who use this program, or if you find and fix a bug,
  66 please send me the change.
  67
  68 Be sure to read the FAQ enclosed with the distrubution.  It contains
  69 answers to the most commonly asked questions about the configuration,
  70 installation, and operation of top.
  71
  72
  73 AVAILABILITY
  74
  75 The latest version of "top" is now being made available via anonymous
  76 FTP from the host "ftp.groupsys.com" in the directory "/pub/top".
  77 Additional modules will be made available in the directory
  78 "/pub/top/m".  The site "eecs.nwu.edu" will continue to house copies
  79 of the distribution as well.
  80
  81 Here are HTML links for the four best "top" archive sites:
  82
  83 <A HREF="ftp://ftp.groupsys.com/pub/top">Top archive (groupsys.com)</A>
  84 <A HREF="ftp://eecs.nwu.edu/pub/top">Top archive (eecs.nwu.edu)</A>
  85 <A HREF="ftp://pharos.dgim.doc.ca/packages/top"> Top mirror (dgim.doc.ca)</A>
  86 <A HREF="ftp://uiarchive.uiuc.edu/pub/packages/top/">Top mirror (uiuc.edu)</A>
  87
  88 New releases will be posted to comp.sources.unix as they become
  89 available.  Sites which arhive that newsgroup will also contain copies
  90 of the distribution.
  91
  92 Announcements about availability will be made to the mailing list
  93 "top-announce@groupsys.com".  This is an open list maintained by
  94 majordomo.  To join the list, send a message containing the word
  95 "subscribe" to "top-announce-request@groupsys.com".  Addresses of
  96 subscribers to this list are kept confidential and will never be used
  97 for any purpose other than as recipients of announements concerning
  98 this software.
  99
 100
 101 KNOWN PROBLEMS:
 102
 103 Gnu CC
 104
 105 Compiling via Gnu CC continued to be the source of most of the
 106 questions I receive.  By far the most common mistake made by those
 107 attempting to compile top with Gnu CC is out of date include files.
 108 When the operating system is upgraded, the include files that are part
 109 of the gcc package MUST also be updated.  Gcc maintains its own
 110 include files.  Even a minor OS upgrade can involve changes to some of
 111 the kernel's internal data structures, which are defined in include
 112 files in "sys".  Top is very sensitive to these changes.  If you are
 113 compiling with gcc and experience any sort of strange problems, please
 114 make sure the include files you are using are up to date BEFORE
 115 sending me a bug report.  Look in the gcc source distribution for the
 116 shell script "fixincludes".
 117
 118 HP/UX 10.10
 119
 120 In their infinite wisdom, the folks at HP have decided that mere mortals
 121 such as you and I don't need to know what the kernel's proc structure looks
 122 like.  To that end, they have removed all useful content from the include
 123 file <sys/proc.h> in version 10.10.  As a result, top will not compile
 124 under 10.10.  What HP is trying to accomplish with this move is to force
 125 iconoclasts such as myself to use "pstat" for collecting all process
 126 information.  I have no immediate solution for this problem, but hope to
 127 obtain a sufficiently complete definition of "struct proc" at some point in
 128 the near future.  Stay tuned.
 129
 130 DIGITAL UNIX 4.0 (DECOSF/1 V4.0)
 131
 132 A user has reported that idle processes are not displayed regardless
 133 of the flags used when invoking top.  We have not had time to track
 134 this problem down.
 135
 136 DECOSF/1 V3.0
 137
 138 There is a bug either in the module, in utils.c, or in DEC's optimizer that
 139 is tickled by the decosf1 module when compiled under V3.0 (and perhaps
 140 earlier versions).  Top compiled using DEC's compiler with optimization
 141 will consistently produce a segmentation fault (in format_next_process
 142 while calling sprintf).  To work around this problem, either compile top
 143 with gcc or turn off optimization (compile without -O).  We think that
 144 one of the bugs fixed in utils.c fixed this problem as well, but we are
 145 not certain.
 146
 147
 148 System V R 4.2
 149
 150 Load average and memory displays do not work.  The problem has been
 151 traced down to a potential bug in the "mem" driver.  The author
 152 of the svr42 module is working on a fix.
 153
 154
 155
 156 GRATITUDE
 157
 158 My perpetual thanks to all the people who have helped me support top
 159 on so many platforms.  Without these people, top would not be what it
 160 is.  Here is a partial list of contributors and other individuals.
 161
 162         Robert Boucher          <boucher@sofkin.ca>
 163         Marc Cohen              <marc@aai.com>
 164         David Cutter            <dpc@grail.com>
 165         Casper Dik              <Casper.Dik@Sun.COM>
 166         Charles Hedrick         <hedrick@geneva.rutgers.edu>
 167         Andrew Herbert          <andrew@werple.apana.org.au>
 168         Jeff Janvrin            <jeff.janvrin@columbiasc.ncr.com>
 169         Torsten Kasch           <torsten@techfak.uni-bielefeld.de>
 170         Petri Kutvonen          <kutvonen@cs.helsinki.fi>
 171         William L. Jones        <jones@chpc>
 172         Tim Pugh                <tpugh@oce.orst.edu>
 173         Steve Scherf            <scherf@swdc.stratus.com>
 174         Phillip Wu              <pwu01@qantek.com.au>
 175
 176 (My apologies if I missed anyone.)
 177
 178
 179 AUTHOR
 180
 181                 William LeFebvre
 182                 Group sys Consulting
 183                 wnl@groupsys.com
 184
 185
 186                 U.S. Mail address:
 187                     William LeFebvre
 188                     Group sys Consulting
 189                     11585 Jones Bridge Road
 190                     Suite 420-139
 191                     Alpharetta, GA  30022
 192                     (770) 813-3224