Changeset View
Changeset View
Standalone View
Standalone View
contrib/top/README
Property | Old Value | New Value |
---|---|---|
svn:keywords | FreeBSD=%H \ No newline at end of property | null |
TOP | TOP | ||||
Version 3.5 | Version 3.8beta1 | ||||
William LeFebvre | William LeFebvre | ||||
and a cast of dozens | and a cast of dozens | ||||
If you do not want to read this entire file, then at least read | If you do not want to read this entire file, then at least read | ||||
the section at the end entitled "KNOWN PROBLEMS". | the section at the end entitled "KNOWN PROBLEMS". | ||||
If you are having any problems getting top to work, please read the | If you are having any problems getting top to work, please read the | ||||
file "FAQ" *before* contacting me. Thank you. | file "FAQ" *before* contacting me. Thank you. | ||||
"top" is a program that will give continual reports about the state of | "top" is a program that will give continual reports about the state of | ||||
the system, including a list of the top cpu using processes. Version 3 | the system, including a list of the top cpu using processes. Version 3 | ||||
of "top" has three primary design goals: provide an accurate snapshot of | of "top" has three primary design goals: provide an accurate snapshot of | ||||
the system and process state, not be one of the top processes itself, be | the system and process state, not be one of the top processes itself, be | ||||
as portable as possible. | as portable as possible. | ||||
Version 3 has many bug fixes from version 2.5, and it has also been | 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. | reorganized in a major way to make it easy to port to other platforms. | ||||
All system dependent code is now contained in one file. | All system dependent code is now contained in one file. | ||||
Top now includes a configuration script called "Configure". It helps | Starting with version 3.6, top includes a "configure" script generated | ||||
the installer choose the correct parameters for this particular | by Gnu's autoconf. This script MUST be run before attempting to | ||||
installation. This script MUST be run before attempting to compile top. | compile top. It will explore the system and generate approriate | ||||
contents for Makefile, config.h, and top.1. | |||||
Top requires read access to the memory files "/dev/kmem" and "/dev/mem" | On some systems, top requires read access to the memory files | ||||
as well as the system image "/vmunix". Some installations have these | "/dev/kmem" and "/dev/mem" as well as the system's kernel image. Most | ||||
files protected from general access. These sites would have to install | installations have these files protected from general access. These | ||||
this program in the same way that programs such as "ps" are installed. | sites would have to install this program in the same way that programs | ||||
In addition, on those Unix variants that support the proc filesystem | such as "ps" are installed. On most systems with a /proc file system, | ||||
(such as SVR4 and Solaris 2), top requires read access to all the files | top will try to read everything it can from /proc, but may need extra | ||||
in /proc: typically dictating that top be installed setuid to root. | 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 | CAVEAT: version 3 of top has internal commands that kill and renice | ||||
processes. Although I have taken steps to insure that top makes | processes. Although I have taken steps to insure that top makes | ||||
appropriate checks with these commands, I cannot guarantee that these | appropriate checks with these commands, I cannot guarantee that these | ||||
internal commands are totally secure. IF YOU INSTALL top as a SETUID | internal commands are totally secure. IF YOU INSTALL top SET-USER-ID | ||||
program, you do so AT YOUR OWN RISK! I realize that some operating | TO ROOT, 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 | systems will require top to run setuid root, and I will do everything | ||||
to make sure that top is a secure setuid program. | I can to make sure that top is a secure setuid program. | ||||
Configure will ask you to input values for certain parameters. Before | System support now takes the form of "modules". Adding support for a | ||||
each parameter, Configure will display a description of what the | different architecture requires only adding a module. These modules | ||||
parameter does. Read the description and choose an appropriate value. | are contained in the subdirectory "machine". The "configure" script | ||||
Sometimes a default will appear in brackets. Typing just return will | automatically determines which module is approproate. However, it may | ||||
choose the default. | 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. | |||||
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. | |||||
To compile and install "top", read the file "INSTALL" and follow the | To compile and install "top", read the file "INSTALL" and follow the | ||||
directions and advice contained therein. | 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 | 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, | beneficial to others who use this program, or if you find and fix a bug, | ||||
please send me the change. | please send me the change. | ||||
Be sure to read the FAQ enclosed with the distrubution. It contains | Be sure to read the FAQ enclosed with the distrubution. It contains | ||||
answers to the most commonly asked questions about the configuration, | answers to the most commonly asked questions about the configuration, | ||||
installation, and operation of top. | 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 | AVAILABILITY | ||||
The latest version of "top" is now being made available via anonymous | Note that top is now a sourceforge project! Its project name is | ||||
FTP from the host "ftp.groupsys.com" in the directory "/pub/top". | "unixtop" and you can access its project page here: | ||||
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. | |||||
Here are HTML links for the four best "top" archive sites: | http://sourceforge.net/projects/unixtop | ||||
<A HREF="ftp://ftp.groupsys.com/pub/top">Top archive (groupsys.com)</A> | On the project page you can find more information and access the | ||||
<A HREF="ftp://eecs.nwu.edu/pub/top">Top archive (eecs.nwu.edu)</A> | official bug and feature request trackers. If you find a bug, | ||||
<A HREF="ftp://pharos.dgim.doc.ca/packages/top"> Top mirror (dgim.doc.ca)</A> | want to request a feature, or need help, please submit a request | ||||
<A HREF="ftp://uiarchive.uiuc.edu/pub/packages/top/">Top mirror (uiuc.edu)</A> | to the appropriate tracker on sourceforge. Thank you. | ||||
New releases will be posted to comp.sources.unix as they become | Subversion access is also provided by Sourceforge. If Subversion is | ||||
available. Sites which arhive that newsgroup will also contain copies | installed on your system you can check out the project with the | ||||
of the distribution. | following command: | ||||
Announcements about availability will be made to the mailing list | svn co https://svn.sourceforge.net/svnroot/unixtop unixtop | ||||
"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: | KNOWN PROBLEMS: | ||||
Gnu CC | Gnu CC | ||||
Compiling via Gnu CC continued to be the source of most of the | Compiling via Gnu CC continued to be the source of most of the | ||||
questions I receive. By far the most common mistake made by those | questions I receive. By far the most common mistake made by those | ||||
attempting to compile top with Gnu CC is out of date include files. | attempting to compile top with Gnu CC is out of date include files. | ||||
When the operating system is upgraded, the include files that are part | When the operating system is upgraded, the include files that are part | ||||
of the gcc package MUST also be updated. Gcc maintains its own | of the gcc package MUST also be updated. Gcc maintains its own | ||||
include files. Even a minor OS upgrade can involve changes to some of | include files. Even a minor OS upgrade can involve changes to some of | ||||
the kernel's internal data structures, which are defined in include | the kernel's internal data structures, which are defined in include | ||||
files in "sys". Top is very sensitive to these changes. If you are | files in "sys". Top is very sensitive to these changes. If you are | ||||
compiling with gcc and experience any sort of strange problems, please | compiling with gcc and experience any sort of strange problems, please | ||||
make sure the include files you are using are up to date BEFORE | 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 | sending me a bug report. Look in the gcc source distribution for the | ||||
shell script "fixincludes". | 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 | HP/UX 10.10 | ||||
In their infinite wisdom, the folks at HP have decided that mere mortals | In their infinite wisdom, the folks at HP have decided that mere mortals | ||||
such as you and I don't need to know what the kernel's proc structure looks | such as you and I don't need to know what the kernel's proc structure looks | ||||
like. To that end, they have removed all useful content from the include | like. To that end, they have removed all useful content from the include | ||||
file <sys/proc.h> in version 10.10. As a result, top will not compile | file <sys/proc.h> in version 10.10. As a result, top will not compile | ||||
under 10.10. What HP is trying to accomplish with this move is to force | under 10.10. What HP is trying to accomplish with this move is to force | ||||
iconoclasts such as myself to use "pstat" for collecting all process | iconoclasts such as myself to use "pstat" for collecting all process | ||||
information. I have no immediate solution for this problem, but hope to | information. I have no immediate solution for this problem, but hope to | ||||
obtain a sufficiently complete definition of "struct proc" at some point in | obtain a sufficiently complete definition of "struct proc" at some point in | ||||
the near future. Stay tuned. | 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 | GRATITUDE | ||||
My perpetual thanks to all the people who have helped me support top | 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 | on so many platforms. Without these people, top would not be what it | ||||
is. Here is a partial list of contributors and other individuals. | is. Here is a partial list of contributors and other individuals. | ||||
Robert Boucher <boucher@sofkin.ca> | Robert Boucher, Marc Cohen, David Cutter, Casper Dik, | ||||
Marc Cohen <marc@aai.com> | Charles Hedrick, Andrew Herbert, Jeff Janvrin, Torsten Kasch, | ||||
David Cutter <dpc@grail.com> | Petri Kutvonen, William L. Jones, Tim Pugh, Steve Scherf, | ||||
Casper Dik <Casper.Dik@Sun.COM> | Phillip Wu | ||||
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> | |||||
(My apologies if I missed anyone.) | (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 | AUTHOR | ||||
If you wish to contact me, please send a message to the sourceforge | |||||
username "wnl". | |||||
William LeFebvre | William LeFebvre | ||||
Group sys Consulting | |||||
wnl@groupsys.com | |||||
U.S. Mail address: | U.S. Mail address: | ||||
William LeFebvre | William LeFebvre | ||||
Group sys Consulting | |||||
11585 Jones Bridge Road | 11585 Jones Bridge Road | ||||
Suite 420-139 | Suite 420 PMB 139 | ||||
Alpharetta, GA 30022 | Alpharetta, GA 30202 | ||||
(770) 813-3224 |