source: trunk/third/top/README @ 16185

Revision 16185, 7.8 KB checked in by ghudson, 24 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r16184, which included commits to RCS files with non-trunk default branches.
Line 
1                             TOP
2                         Version 3.5
3
4                       William LeFebvre
5                     and a cast of dozens
6
7
8If you do not want to read this entire file, then at least read
9the section at the end entitled "KNOWN PROBLEMS".
10
11If you are having any problems getting top to work, please read the
12file "FAQ" *before* contacting me.  Thank you.
13
14"top" is a program that will give continual reports about the state of
15the system, including a list of the top cpu using processes.  Version 3
16of "top" has three primary design goals: provide an accurate snapshot of
17the system and process state, not be one of the top processes itself, be
18as portable as possible.
19
20Version 3 has many bug fixes from version 2.5, and it has also been
21reorganized in a major way to make it easy to port to other platforms.
22All system dependent code is now contained in one file.
23
24Top now includes a configuration script called "Configure".  It helps
25the installer choose the correct parameters for this particular
26installation.  This script MUST be run before attempting to compile top.
27
28Top requires read access to the memory files "/dev/kmem" and "/dev/mem"
29as well as the system image "/vmunix".  Some installations have these
30files protected from general access.  These sites would have to install
31this program in the same way that programs such as "ps" are installed.
32In 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
34in /proc: typically dictating that top be installed setuid to root.
35
36CAVEAT: version 3 of top has internal commands that kill and renice
37processes.  Although I have taken steps to insure that top makes
38appropriate checks with these commands, I cannot guarantee that these
39internal commands are totally secure.  IF YOU INSTALL top as a SETUID
40program, you do so AT YOUR OWN RISK!  I realize that some operating
41systems will require top to run setuid, and I will do everything I can
42to make sure that top is a secure setuid program.
43
44Configure will ask you to input values for certain parameters.  Before
45each parameter, Configure will display a description of what the
46parameter does.  Read the description and choose an appropriate value.
47Sometimes a default will appear in brackets.  Typing just return will
48choose the default.
49
50System support now takes the form of "modules".  Adding support for
51a different architecture requires only adding a module.  Configure
52asks 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
55To compile and install "top", read the file "INSTALL" and follow the
56directions and advice contained therein.
57
58Once you have created a binary for one particular type of machine, you
59can reconfigure for another type with "./Configure modulename" where
60"modulename" is replaced with the appropriate module name.  All other
61parameter values are kept the same.  Note that in some cases this may
62not be appropriate.
63
64If you make any kind of change to "top" that you feel would be
65beneficial to others who use this program, or if you find and fix a bug,
66please send me the change.
67
68Be sure to read the FAQ enclosed with the distrubution.  It contains
69answers to the most commonly asked questions about the configuration,
70installation, and operation of top.
71
72
73AVAILABILITY
74
75The latest version of "top" is now being made available via anonymous
76FTP from the host "ftp.groupsys.com" in the directory "/pub/top".
77Additional modules will be made available in the directory
78"/pub/top/m".  The site "eecs.nwu.edu" will continue to house copies
79of the distribution as well.
80
81Here 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
88New releases will be posted to comp.sources.unix as they become
89available.  Sites which arhive that newsgroup will also contain copies
90of the distribution.
91
92Announcements about availability will be made to the mailing list
93"top-announce@groupsys.com".  This is an open list maintained by
94majordomo.  To join the list, send a message containing the word
95"subscribe" to "top-announce-request@groupsys.com".  Addresses of
96subscribers to this list are kept confidential and will never be used
97for any purpose other than as recipients of announements concerning
98this software.
99
100
101KNOWN PROBLEMS:
102
103Gnu CC
104
105Compiling via Gnu CC continued to be the source of most of the
106questions I receive.  By far the most common mistake made by those
107attempting to compile top with Gnu CC is out of date include files.
108When the operating system is upgraded, the include files that are part
109of the gcc package MUST also be updated.  Gcc maintains its own
110include files.  Even a minor OS upgrade can involve changes to some of
111the kernel's internal data structures, which are defined in include
112files in "sys".  Top is very sensitive to these changes.  If you are
113compiling with gcc and experience any sort of strange problems, please
114make sure the include files you are using are up to date BEFORE
115sending me a bug report.  Look in the gcc source distribution for the
116shell script "fixincludes".
117
118HP/UX 10.10
119
120In their infinite wisdom, the folks at HP have decided that mere mortals
121such as you and I don't need to know what the kernel's proc structure looks
122like.  To that end, they have removed all useful content from the include
123file <sys/proc.h> in version 10.10.  As a result, top will not compile
124under 10.10.  What HP is trying to accomplish with this move is to force
125iconoclasts such as myself to use "pstat" for collecting all process
126information.  I have no immediate solution for this problem, but hope to
127obtain a sufficiently complete definition of "struct proc" at some point in
128the near future.  Stay tuned.
129
130DIGITAL UNIX 4.0 (DECOSF/1 V4.0)
131
132A user has reported that idle processes are not displayed regardless
133of the flags used when invoking top.  We have not had time to track
134this problem down.
135
136DECOSF/1 V3.0
137
138There is a bug either in the module, in utils.c, or in DEC's optimizer that
139is tickled by the decosf1 module when compiled under V3.0 (and perhaps
140earlier versions).  Top compiled using DEC's compiler with optimization
141will consistently produce a segmentation fault (in format_next_process
142while calling sprintf).  To work around this problem, either compile top
143with gcc or turn off optimization (compile without -O).  We think that
144one of the bugs fixed in utils.c fixed this problem as well, but we are
145not certain.
146
147
148System V R 4.2
149
150Load average and memory displays do not work.  The problem has been
151traced down to a potential bug in the "mem" driver.  The author
152of the svr42 module is working on a fix.
153
154
155
156GRATITUDE
157
158My perpetual thanks to all the people who have helped me support top
159on so many platforms.  Without these people, top would not be what it
160is.  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
179AUTHOR
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
Note: See TracBrowser for help on using the repository browser.