Vendor import of top-3.8b1vendor/top/3.8b1vendor/top

Obtained from:	http://www.unixtop.org

1 files changed, 97 insertions, 98 deletions

diff --git a/README b/README
index c8351a843313..e0e7cf3e01c2 100644
--- a/README
+++ b/README
@@ -1,5 +1,5 @@
                              TOP
-                         Version 3.5
+                       Version 3.8beta1
 
                        William LeFebvre
 		     and a cast of dozens
@@ -21,46 +21,47 @@ Version 3 has many bug fixes from version 2.5, and it has also been
 reorganized in a major way to make it easy to port to other platforms.
 All system dependent code is now contained in one file.
 
-Top now includes a configuration script called "Configure".  It helps
-the installer choose the correct parameters for this particular
-installation.  This script MUST be run before attempting to compile top.
-
-Top requires read access to the memory files "/dev/kmem" and "/dev/mem"
-as well as the system image "/vmunix".  Some installations have these
-files protected from general access.  These sites would have to install
-this program in the same way that programs such as "ps" are installed.
-In addition, on those Unix variants that support the proc filesystem
-(such as SVR4 and Solaris 2), top requires read access to all the files
-in /proc: typically dictating that top be installed setuid to root.
+Starting with version 3.6, top includes a "configure" script generated
+by Gnu's autoconf.  This script MUST be run before attempting to
+compile top.  It will explore the system and generate approriate
+contents for Makefile, config.h, and top.1.
+
+On some systems, top requires read access to the memory files
+"/dev/kmem" and "/dev/mem" as well as the system's kernel image.  Most
+installations have these files protected from general access.  These
+sites would have to install this program in the same way that programs
+such as "ps" are installed.  On most systems with a /proc file system,
+top will try to read everything it can from /proc, but may need extra
+permissions to do so.  The configure script will determine the
+permissions needed by the top binary, and a "make install" as root
+will get the binary installed correctly.  Sometimes this requires that
+the binary be installed with set-group-id privileges and, in rare
+cases, set-user-id to root.
 
 CAVEAT: version 3 of top has internal commands that kill and renice
 processes.  Although I have taken steps to insure that top makes
 appropriate checks with these commands, I cannot guarantee that these
-internal commands are totally secure.  IF YOU INSTALL top as a SETUID
-program, you do so AT YOUR OWN RISK!  I realize that some operating
-systems will require top to run setuid, and I will do everything I can
-to make sure that top is a secure setuid program.
-
-Configure will ask you to input values for certain parameters.  Before
-each parameter, Configure will display a description of what the
-parameter does.  Read the description and choose an appropriate value.
-Sometimes a default will appear in brackets.  Typing just return will
-choose the default.
-
-System support now takes the form of "modules".  Adding support for
-a different architecture requires only adding a module.  Configure
-asks which module to use when it is configuring top.  See the file
-"Porting" for a description of how to write your own module.
+internal commands are totally secure.  IF YOU INSTALL top SET-USER-ID
+TO ROOT, YOU DO SO AT YOUR OWN RISK!  I realize that some operating
+systems will require top to run setuid root, and I will do everything
+I can to make sure that top is a secure setuid program.
+
+System support now takes the form of "modules".  Adding support for a
+different architecture requires only adding a module.  These modules
+are contained in the subdirectory "machine".  The "configure" script
+automatically determines which module is approproate.  However, it may
+not be able to determine what the correct module is.  This can happen
+either because it doesn't know about the system or there is no module
+to support the system.  In the former case, if you know which module
+to use, you can force "configure" to choose a particular module with
+the option "--with-module".  For example, if you want to force the use
+of the svr4 module (which appears as "machine/m_svr4.c") then use
+"configure --with-module=svr4" to generate the correct Makefile.  See
+the file "Porting" for a description of how to write your own module.
 
 To compile and install "top", read the file "INSTALL" and follow the
 directions and advice contained therein.
 
-Once you have created a binary for one particular type of machine, you
-can reconfigure for another type with "./Configure modulename" where
-"modulename" is replaced with the appropriate module name.  All other
-parameter values are kept the same.  Note that in some cases this may
-not be appropriate.
-
 If you make any kind of change to "top" that you feel would be
 beneficial to others who use this program, or if you find and fix a bug,
 please send me the change.
@@ -69,33 +70,50 @@ Be sure to read the FAQ enclosed with the distrubution.  It contains
 answers to the most commonly asked questions about the configuration,
 installation, and operation of top.
 
+COLOR
+
+Version 3.6 incorporated the idea of using ANSI color sequences to
+enhance information on the screen.  By default, no color is used.  But
+you can configure the use of color through the environment variable
+TOPCOLORS (or, for compatibility, TOPCOLOURS).  The interface is
+identical to the one first implemented by chris@spang.uk.eu.org, but
+the implementation is entirely different.  The option -C can be used
+to diable the feature entirely.
+
+Any information at the top of the screen can be enhanced with color.
+However, due to implementation difficulties, the per-process area
+cannot be color-enhanced.  A complete description of color support can
+be found in the man page.  References for ANSI color codes can be
+found all over the Internet, but if you want a handy reference, look
+in color.h.
+
 
 AVAILABILITY
 
-The latest version of "top" is now being made available via anonymous
-FTP from the host "ftp.groupsys.com" in the directory "/pub/top".
-Additional modules will be made available in the directory
-"/pub/top/m".  The site "eecs.nwu.edu" will continue to house copies
-of the distribution as well.
+Note that top is now a sourceforge project!  Its project name is
+"unixtop" and you can access its project page here:
+
+http://sourceforge.net/projects/unixtop
 
-Here are HTML links for the four best "top" archive sites:
+On the project page you can find more information and access the
+official bug and feature request trackers.  If you find a bug,
+want to request a feature, or need help, please submit a request
+to the appropriate tracker on sourceforge.  Thank you.
 
-<A HREF="ftp://ftp.groupsys.com/pub/top">Top archive (groupsys.com)</A>
-<A HREF="ftp://eecs.nwu.edu/pub/top">Top archive (eecs.nwu.edu)</A>
-<A HREF="ftp://pharos.dgim.doc.ca/packages/top"> Top mirror (dgim.doc.ca)</A>
-<A HREF="ftp://uiarchive.uiuc.edu/pub/packages/top/">Top mirror (uiuc.edu)</A>
+Subversion access is also provided by Sourceforge.  If Subversion is
+installed on your system you can check out the project with the
+following command:
 
-New releases will be posted to comp.sources.unix as they become
-available.  Sites which arhive that newsgroup will also contain copies
-of the distribution.
+	svn co https://svn.sourceforge.net/svnroot/unixtop unixtop
 
-Announcements about availability will be made to the mailing list
-"top-announce@groupsys.com".  This is an open list maintained by
-majordomo.  To join the list, send a message containing the word
-"subscribe" to "top-announce-request@groupsys.com".  Addresses of
-subscribers to this list are kept confidential and will never be used
-for any purpose other than as recipients of announements concerning
-this software.
+There is also a web site dedicated to the project, and it is here:
+
+http://www.unixtop.org
+
+The latest version of "top" is available as a download through
+sourceforge.  Start here to access the downloadable files:
+
+http://sourceforge.net/project/showfiles.php?group_id=72892
 
 
 KNOWN PROBLEMS:
@@ -115,6 +133,16 @@ make sure the include files you are using are up to date BEFORE
 sending me a bug report.  Look in the gcc source distribution for the
 shell script "fixincludes".
 
+MacOS X
+
+Since I don't have full time root access to a MacOS X system I cannot
+provide effective support for the platform.  MacOS X uses Mach, and it
+is very difficult to extract accurate system and process information
+from the system.  It takes a lot of trial and error, along with root
+access.  I have included the most up-to-date version of the macosx module
+in the distribution, but I do not claim that it works.  If you want to
+try to use it, you can configure with "./configure --with-module=macosx".
+
 HP/UX 10.10
 
 In their infinite wisdom, the folks at HP have decided that mere mortals
@@ -127,31 +155,6 @@ information.  I have no immediate solution for this problem, but hope to
 obtain a sufficiently complete definition of "struct proc" at some point in
 the near future.  Stay tuned.
 
-DIGITAL UNIX 4.0 (DECOSF/1 V4.0)
-
-A user has reported that idle processes are not displayed regardless
-of the flags used when invoking top.  We have not had time to track
-this problem down.
-
-DECOSF/1 V3.0
-
-There is a bug either in the module, in utils.c, or in DEC's optimizer that
-is tickled by the decosf1 module when compiled under V3.0 (and perhaps
-earlier versions).  Top compiled using DEC's compiler with optimization
-will consistently produce a segmentation fault (in format_next_process
-while calling sprintf).  To work around this problem, either compile top
-with gcc or turn off optimization (compile without -O).  We think that
-one of the bugs fixed in utils.c fixed this problem as well, but we are
-not certain.
-
-
-System V R 4.2
-
-Load average and memory displays do not work.  The problem has been
-traced down to a potential bug in the "mem" driver.  The author
-of the svr42 module is working on a fix.
-
-
 
 GRATITUDE
 
@@ -159,34 +162,30 @@ My perpetual thanks to all the people who have helped me support top
 on so many platforms.  Without these people, top would not be what it
 is.  Here is a partial list of contributors and other individuals.
 
-	Robert Boucher		<boucher@sofkin.ca>
-	Marc Cohen 		<marc@aai.com>
-	David Cutter		<dpc@grail.com>
-	Casper Dik		<Casper.Dik@Sun.COM>
-	Charles Hedrick 	<hedrick@geneva.rutgers.edu>
-	Andrew Herbert		<andrew@werple.apana.org.au>
-	Jeff Janvrin		<jeff.janvrin@columbiasc.ncr.com>
-	Torsten Kasch 		<torsten@techfak.uni-bielefeld.de>
-	Petri Kutvonen		<kutvonen@cs.helsinki.fi>
-	William L. Jones 	<jones@chpc>
-	Tim Pugh 		<tpugh@oce.orst.edu>
-	Steve Scherf		<scherf@swdc.stratus.com>
-	Phillip Wu		<pwu01@qantek.com.au>
+	Robert Boucher, Marc Cohen, David Cutter, Casper Dik,
+	Charles Hedrick, Andrew Herbert, Jeff Janvrin, Torsten Kasch,
+	Petri Kutvonen, William L. Jones, Tim Pugh, Steve Scherf,
+	Phillip Wu
 
 (My apologies if I missed anyone.)
 
 
+LICENSE
+
+Top is distributed free of charge under the same terms as the BSD
+license.  For an official statement, please refer to the file "LICENSE"
+which should be included with the source distribution.
+
+
 AUTHOR
 
-		William LeFebvre
-		Group sys Consulting
-		wnl@groupsys.com
+If you wish to contact me, please send a message to the sourceforge
+username "wnl".
 
+		William LeFebvre
 
 		U.S. Mail address:
 		    William LeFebvre
-		    Group sys Consulting
 		    11585 Jones Bridge Road
-		    Suite 420-139
-		    Alpharetta, GA  30022
-		    (770) 813-3224
+		    Suite 420 PMB 139
+		    Alpharetta, GA  30202