contrib/top/README

   1                              TOP
   2                        Version 3.8beta1
   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 Starting with version 3.6, top includes a "configure" script generated
  25 by Gnu's autoconf.  This script MUST be run before attempting to
  26 compile top.  It will explore the system and generate approriate
  27 contents for Makefile, config.h, and top.1.
  28
  29 On some systems, top requires read access to the memory files
  30 "/dev/kmem" and "/dev/mem" as well as the system's kernel image.  Most
  31 installations have these files protected from general access.  These
  32 sites would have to install this program in the same way that programs
  33 such as "ps" are installed.  On most systems with a /proc file system,
  34 top will try to read everything it can from /proc, but may need extra
  35 permissions to do so.  The configure script will determine the
  36 permissions needed by the top binary, and a "make install" as root
  37 will get the binary installed correctly.  Sometimes this requires that
  38 the binary be installed with set-group-id privileges and, in rare
  39 cases, set-user-id to root.
  40
  41 CAVEAT: version 3 of top has internal commands that kill and renice
  42 processes.  Although I have taken steps to insure that top makes
  43 appropriate checks with these commands, I cannot guarantee that these
  44 internal commands are totally secure.  IF YOU INSTALL top SET-USER-ID
  45 TO ROOT, YOU DO SO AT YOUR OWN RISK!  I realize that some operating
  46 systems will require top to run setuid root, and I will do everything
  47 I can to make sure that top is a secure setuid program.
  48
  49 System support now takes the form of "modules".  Adding support for a
  50 different architecture requires only adding a module.  These modules
  51 are contained in the subdirectory "machine".  The "configure" script
  52 automatically determines which module is approproate.  However, it may
  53 not be able to determine what the correct module is.  This can happen
  54 either because it doesn't know about the system or there is no module
  55 to support the system.  In the former case, if you know which module
  56 to use, you can force "configure" to choose a particular module with
  57 the option "--with-module".  For example, if you want to force the use
  58 of the svr4 module (which appears as "machine/m_svr4.c") then use
  59 "configure --with-module=svr4" to generate the correct Makefile.  See
  60 the file "Porting" for a description of how to write your own module.
  61
  62 To compile and install "top", read the file "INSTALL" and follow the
  63 directions and advice contained therein.
  64
  65 If you make any kind of change to "top" that you feel would be
  66 beneficial to others who use this program, or if you find and fix a bug,
  67 please send me the change.
  68
  69 Be sure to read the FAQ enclosed with the distrubution.  It contains
  70 answers to the most commonly asked questions about the configuration,
  71 installation, and operation of top.
  72
  73 COLOR
  74
  75 Version 3.6 incorporated the idea of using ANSI color sequences to
  76 enhance information on the screen.  By default, no color is used.  But
  77 you can configure the use of color through the environment variable
  78 TOPCOLORS (or, for compatibility, TOPCOLOURS).  The interface is
  79 identical to the one first implemented by chris@spang.uk.eu.org, but
  80 the implementation is entirely different.  The option -C can be used
  81 to diable the feature entirely.
  82
  83 Any information at the top of the screen can be enhanced with color.
  84 However, due to implementation difficulties, the per-process area
  85 cannot be color-enhanced.  A complete description of color support can
  86 be found in the man page.  References for ANSI color codes can be
  87 found all over the Internet, but if you want a handy reference, look
  88 in color.h.
  89
  90
  91 AVAILABILITY
  92
  93 Note that top is now a sourceforge project!  Its project name is
  94 "unixtop" and you can access its project page here:
  95
  96 http://sourceforge.net/projects/unixtop
  97
  98 On the project page you can find more information and access the
  99 official bug and feature request trackers.  If you find a bug,
 100 want to request a feature, or need help, please submit a request
 101 to the appropriate tracker on sourceforge.  Thank you.
 102
 103 Subversion access is also provided by Sourceforge.  If Subversion is
 104 installed on your system you can check out the project with the
 105 following command:
 106
 107         svn co https://svn.sourceforge.net/svnroot/unixtop unixtop
 108
 109 There is also a web site dedicated to the project, and it is here:
 110
 111 http://www.unixtop.org
 112
 113 The latest version of "top" is available as a download through
 114 sourceforge.  Start here to access the downloadable files:
 115
 116 http://sourceforge.net/project/showfiles.php?group_id=72892
 117
 118
 119 KNOWN PROBLEMS:
 120
 121 Gnu CC
 122
 123 Compiling via Gnu CC continued to be the source of most of the
 124 questions I receive.  By far the most common mistake made by those
 125 attempting to compile top with Gnu CC is out of date include files.
 126 When the operating system is upgraded, the include files that are part
 127 of the gcc package MUST also be updated.  Gcc maintains its own
 128 include files.  Even a minor OS upgrade can involve changes to some of
 129 the kernel's internal data structures, which are defined in include
 130 files in "sys".  Top is very sensitive to these changes.  If you are
 131 compiling with gcc and experience any sort of strange problems, please
 132 make sure the include files you are using are up to date BEFORE
 133 sending me a bug report.  Look in the gcc source distribution for the
 134 shell script "fixincludes".
 135
 136 MacOS X
 137
 138 Since I don't have full time root access to a MacOS X system I cannot
 139 provide effective support for the platform.  MacOS X uses Mach, and it
 140 is very difficult to extract accurate system and process information
 141 from the system.  It takes a lot of trial and error, along with root
 142 access.  I have included the most up-to-date version of the macosx module
 143 in the distribution, but I do not claim that it works.  If you want to
 144 try to use it, you can configure with "./configure --with-module=macosx".
 145
 146 HP/UX 10.10
 147
 148 In their infinite wisdom, the folks at HP have decided that mere mortals
 149 such as you and I don't need to know what the kernel's proc structure looks
 150 like.  To that end, they have removed all useful content from the include
 151 file <sys/proc.h> in version 10.10.  As a result, top will not compile
 152 under 10.10.  What HP is trying to accomplish with this move is to force
 153 iconoclasts such as myself to use "pstat" for collecting all process
 154 information.  I have no immediate solution for this problem, but hope to
 155 obtain a sufficiently complete definition of "struct proc" at some point in
 156 the near future.  Stay tuned.
 157
 158
 159 GRATITUDE
 160
 161 My perpetual thanks to all the people who have helped me support top
 162 on so many platforms.  Without these people, top would not be what it
 163 is.  Here is a partial list of contributors and other individuals.
 164
 165         Robert Boucher, Marc Cohen, David Cutter, Casper Dik,
 166         Charles Hedrick, Andrew Herbert, Jeff Janvrin, Torsten Kasch,
 167         Petri Kutvonen, William L. Jones, Tim Pugh, Steve Scherf,
 168         Phillip Wu
 169
 170 (My apologies if I missed anyone.)
 171
 172
 173 LICENSE
 174
 175 Top is distributed free of charge under the same terms as the BSD
 176 license.  For an official statement, please refer to the file "LICENSE"
 177 which should be included with the source distribution.
 178
 179
 180 AUTHOR
 181
 182 If you wish to contact me, please send a message to the sourceforge
 183 username "wnl".
 184
 185                 William LeFebvre
 186
 187                 U.S. Mail address:
 188                     William LeFebvre
 189                     11585 Jones Bridge Road
 190                     Suite 420 PMB 139
 191                     Alpharetta, GA  30202