README revision 24139
1 TOP 2 Version 3.4 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 72AVAILABILITY 73 74The latest version of "top" is now being made available via anonymous 75FTP from the host "ftp.groupsys.com" in the directory "/pub/top". 76Additional modules will be made available in the directory 77"/pub/top/m". The site "eecs.nwu.edu" will continue to house copies 78of the distribution as well. 79 80Here are HTML links for the two best "top" archive sites: 81 82<A HREF="ftp://ftp.groupsys.com/pub/top>Top archive (groupsys.com)</A> 83<A HREF="ftp://eecs.nwu.edu/pub/top>Top archive (eecs.nwu.edu)</A> 84 85New releases will be posted to comp.sources.unix as they become 86available. Sites which arhive that newsgroup will also contain copies 87of the distribution. 88 89KNOWN PROBLEMS: 90 91Gnu CC 92 93Compiling via Gnu CC continued to be the source of most of the 94questions I receive. By far the most common mistake made by those 95attempting to compile top with Gnu CC is out of date include files. 96When the operating system is upgraded, the include files that are part 97of the gcc package MUST also be updated. Gcc maintains its own 98include files. Even a minor OS upgrade can involve changes to some of 99the kernel's internal data structures, which are defined in include 100files in "sys". Top is very sensitive to these changes. If you are 101compiling with gcc and experience any sort of strange problems, please 102make sure the include files you are using are up to date BEFORE 103sending me a bug report. Look in the gcc source distribution for the 104shell script "fixincludes". 105 106HP/UX 10.10 107 108In their infinite wisdom, the folks at HP have decided that mere mortals 109such as you and I don't need to know what the kernel's proc structure looks 110like. To that end, they have removed all useful content from the include 111file <sys/proc.h> in version 10.10. As a result, top will not compile 112under 10.10. What HP is trying to accomplish with this move is to force 113iconoclasts such as myself to use "pstat" for collecting all process 114information. I have no immediate solution for this problem, but hope to 115obtain a sufficiently complete definition of "struct proc" at some point in 116the near future. Stay tuned. 117 118DIGITAL UNIX 4.0 (DECOSF/1 V4.0) 119 120A user has reported that idle processes are not displayed regardless 121of the flags used when invoking top. We have not had time to track 122this problem down. 123 124DECOSF/1 V3.0 125 126There is a bug either in the module, in utils.c, or in DEC's optimizer that 127is tickled by the decosf1 module when compiled under V3.0 (and perhaps 128earlier versions). Top compiled using DEC's compiler with optimization 129will consistently produce a segmentation fault (in format_next_process 130while calling sprintf). To work around this problem, either compile top 131with gcc or turn off optimization (compile without -O). We think that 132one of the bugs fixed in utils.c fixed this problem as well, but we are 133not certain. 134 135 136System V R 4.2 137 138Load average and memory displays do not work. The problem has been 139traced down to a potential bug in the "mem" driver. The author 140of the svr42 module is working on a fix. 141 142 143 144GRATITUDE 145 146My perpetual thanks to all the people who have helped me support top 147on so many platforms. Without these people, top would not be what it 148is. Here is a partial list of contributors and other individuals. 149 150 Robert Boucher <boucher@sofkin.ca> 151 Marc Cohen <marc@aai.com> 152 David Cutter <dpc@grail.com> 153 Casper Dik <casper@fwi.uva.nl> 154 Charles Hedrick <hedrick@geneva.rutgers.edu> 155 Andrew Herbert <andrew@werple.apana.org.au> 156 Jeff Janvrin <jeff.janvrin@columbiasc.ncr.com> 157 Torsten Kasch <torsten@techfak.uni-bielefeld.de> 158 Petri Kutvonen <kutvonen@cs.helsinki.fi> 159 William L. Jones <jones@chpc> 160 Tim Pugh <tpugh@oce.orst.edu> 161 Steve Scherf <scherf@swdc.stratus.com> 162 Phillip Wu <pwu01@qantek.com.au> 163 164(My apologies if I missed anyone.) 165 166 167AUTHOR 168 169 William LeFebvre 170 Group sys Consulting 171 wnl@groupsys.com 172 173 174 U.S. Mail address: 175 William LeFebvre 176 170 Colton Crest Drive 177 Alpharetta, GA 30202 178 (770) 813-3224 179