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