Commit bc66647b authored by William LeFebvre's avatar William LeFebvre

[svn] Create release 3.6.1

parents
This diff is collapsed.
TOP
Version 3.6.1
William LeFebvre
with much help from others
Frequently Asked Questions and their Answers
GENERAL
1. What is top?
Top provies the user with a regularly updated display showing
information about the system and its top cpu-using processes. Think
of it as a full-screen "ps" output that gets updated at regular
intervals.
2. Where do I get the latest version of top?
The official site for top is "ftp.unixtop.org" in the directory
"/pub/top". Top is also a SourceForge project, and the most recent
releases are available on any of the SourceForge mirrors. The
SourceForge project page is at
http://sourceforge.net/projects/unixtop.
3. Is there a web page for top?
Yes. Point your browser at http://www.unixtop.org. It includes all
documentation, a nice interactive display which describes the various
components of the output of top, web-based retrieval of the package,
year 2000 information, and other neat stuff.
4. Is there a mailing list or on-line bulletin board for top?
There is a mailing list used for general announcements regarding top,
including new releases. This mailing list is available to sourceforge
members and can be accessed from the unixtop sourceforge project
page. Visit SourceForge and search for the project "unixtop", then
click on "mailing lists". There are also on-line forums available
through SourceForge where members can post questions and comments.
5. What about Year 2000 compliance?
Top did not experience any problems with the transition to the year
2000. A full statement concerning top and the year 2000 can be found
in the file "Y2K" included with the distribution.
6. Will there be another major release of top? Will there be a top
version 4?
I have some great ideas for the next major release of top, and I very
much want to make those ideas a reality. What I don't have much of
these days is free time. But I will keep poking at it and I hope to
have top version 4.0 ready by the fall of 2006.
7. Does top really support multi-processor systems?
On platforms that support multiple processors, top is able to detect
and correctly summarize the information about those processors. What
top does not do is break down the cpu states summary (the third line
of the display) by cpu. Instead it collects the cpu state information
from all processors and combines them in to a single line. Some
vendors include a modified version of top that presents this
information for each cpu. Top 3.7 may have this functionality but it
is not present in the standard top 3.6 release.
8. Is top under CVS control? Can I access the sources via SourceForge
CVS or Subversion?
I maintain top using subversion, not CVS. Although I utilize my own
private subversion repository, it is regularly mirrored in to the
SourceForge Subversion repository. You can access the SourceForge
repository here: https://svn.sourceforge.net/svnroot/unixtop.
COMPILING
9. We just upgraded our operating system to a new version and top broke.
What should we do?
Recompile it. Top is very sensitive to changes in internal kernel
data structures. It is not uncommon for a new version of the
operating system to include changes to kernel data structures.
RUNNING
10. I just finished compiling top and it works fine for root, but when I
try to run it as a regular user it either complains about files it
can't open or it doesn't display all the information it should. Did I
do something wrong?
Well, you're just not done. On many operating systems today, access
to many of the kernel memory devices and other system files is
restricted to either root or a particular group. The configure script
figures this out (usually) and makes sure that the "install" rule in
the Makefile will install top so that anyone can run it successfully.
However, you have to *install* it first. Do this with the command
"make install".
11. Top is (not) displaying idle processes and I don't (do) want it to.
This default has only changed about a dozen times, and I finally got
tired of people whining about it. Go read the manual page for the
current version and pay special attention to the description of the
"TOP" environment variable.
12. We have so much memory in our machine that the memory status display
(the fourth line) ends up being longer than 80 characters. This
completely messes up top's output. Is there a patch?
Most modules have been changed to use new memory formatting functions
which will display large values in terms of megabytes instead of
kilobytes. This should fix all occurences of this problem. Also note
that newer versions of top can use columns beyond 79, and understand
window resizes. So you can always make your window wider.
13. I tried to compile top with gcc and it doesn't work. I get
compilation errors in the include files, or I get an executable that
dumps core, or top displays incorrect numbers in some of the
displays. What's wrong?
Gnu CC likes very much to use its own include files. Not being a gcc
expert, I can't explain why it does this. But I can tell you that if
you upgrade your operating system (say from Solaris 2.6 to Solaris
2.7) after installing gcc, then the include files that gcc uses will
be incorrect, especially those found in the "sys" directory. Your
choices are: (1) rebuild and reinstall the "standard" include files
for gcc (look for scripts in the distribution called "fixincludes"
and "fixinc.svr4"), (2) compile machine.c with
"CFLAGS=-I/usr/include" then make the rest of the object files
normally, or (3) use a different compiler.
14. The cpu state percentages are all wrong, indicating that my machine
is using 95% system time when it is clearly idle. What's wrong?
This can happen if you compiled with gcc using the wrong include
files. See the previous question.
MACOSX PROBLEMS
15. I tried to configure top on my Mac OSX system and I got an error
claiming "macosx not supported". What up?
Since I don't have full time root access to a Mac OSX system I cannot
provide effective support for the platform. MacOSX 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".
SUNOS PROBLEMS
16. I tried compiling top under SunOS version 4.1.x and it got compile
time errors or run time errors. Is there a patch?
If you try compiling top in a "System V environment" under SunOS
(that is, /usr/5bin is before /usr/bin on your path) then the
compilation may fail. This is mostly due to the fact that top thinks
its being compiled on a System V machine when it really isn't. The
only solution is to put /usr/bin and /usr/ucb before /usr/5bin on
your path and try again.
SOLARIS PROBLEMS
NOTE: the most common source of problems with top under Solaris is
the result of compiling it with the wrong front end. Make sure that
/usr/ucb is not on your path before attempting to compile top under
Solaris.
17. Is there somewhere I can get a pre-compiled package?
Yes. Although I don't provide pre-compiled binaries, you can get a
Sun-style package from www.sunfreeware.com.
18. Under Solaris 2, when I type "make", the system says "language
optional software package not installed." What's going on?
You tried to compile with /usr/ucb/cc. Make sure /usr/ucb is not on
your path. Furthermore, you do not have a Sun compiler installed on
your system. You need a compiler to make top. Either Sun's C compiler
or the Gnu C compiler will work fine.
19. Under Solaris 2, when I run top as root it only shows root processes,
or it only shows processes with a PID less than 1000. It refuses to
show anything else. What do I do?
You probably compiled it with /usr/ucb/cc instead of the real C
compiler. /usr/ucb/cc is a cc front end that compiles programs in BSD
source-level compatability mode. You do not want that. Make sure that
/usr/ucb is not on your path and try compiling top again.
20. Under Solaris 2, I compiled top using what I am sure is the correct
compiler but when I try to run it it complains about missing dynamic
libraries. What is wrong?
Check to see if you have LD_LIBRARY_PATH defined in your shell. If
you do, make sure that /usr/ucblib is not on the path anywhere. Then
try compiling top again.
21. Under Solaris 2, when I try to run top it complains that it can't
open the library "libucb.so.1". So I changed the LIBS line in
m_sunos5.c to include -R/usr/ucblib to make sure that the dynamic
linker will look there when top runs. I figured this was just an
oversight. Was I right?
No, you were not right. As distributed, top requires no alterations
for successful compilation and operations under any release of
Solaris 2. You probably compiled top with /usr/ucb/cc instead of the
real C compiler. See FAQ 22 for more details.
22. On my 64-bit system some processes show up with incorrect information
(such as zero memory).
If you are running a 64-bit system, then you will want to make a
64-bit top binary. Top's configure script attempts to detect 64-bit
systems, and will adjust the compilation options accordingly. If you
configure and make a binary on a 32-bit system it will still run on a
64-bit system, but may not produce the correct results. The same will
happen if you configure your distribution on a 32-bit system then
compile with that configuration on a 64-bit system. You must
configure and compile on the same system.
23. Can I install both 32-bit and 64-bit binaries on a central file
server and have machines which mount it automatically use the correct
one?
Yes. First, compile a 32-bit version and name it top32. Then compile
a 64-bit version (see FAQ #22) and name it top64. Make sure each
binary has the correct ownership and mode. Choose your bin directory
(we will refer to that as $BIN). In $BIN make sure there are
subdirectories named "sparcv7" and "sparcv9". If they don't exist
then create them. Copy "top32" to "$BIN/sparcv7/top" and "top64" to
"$BIN/sparcv9/top". Finally copy (do not link) the binary
/usr/lib/isaexec to "$BIN/top". When a user runs "top" she will
actually be running a copy of isaexec. This tool will automatically
determine the kernel type and run the top "binary" out of the correct
subdirectory.
24. This version of top show less available swap space than previous
versions. Why does it no longer match the output of the swap summary
produced with "swap -s"?
Starting with version 3.6 of top, the amount of swap space reported
by top has been changed to reflect only disk-based swap space. The
swap summary produced with "swap -s" also include memory-based swap
space. This changed was mae for several reasons. It makes the display
under Solaris more like those of other operating systems. The display
is more what users expect (except those used to previous versions of
top). Most importantly, "swap -s" gets its data via an undocumented
system interface. Now that top no longer displays that data it can
use publically documented and maintained system interfaces to
retrieve its data.
SVR4-DERIVED PROBLEMS
25. When I run top on my SVR4-derived operating system, it displays all
the system information at the top but does not display any process
information (or only displays process information for my own
processes). Yet when I run it as root, everything works fine. What's
wrong?
Your system probably uses the pseudo file system "/proc", which is by
default only accessible by root. Top needs to be installed setuid
root on such systems if it is going to function correctly for normal
users.
SVR42 PROBLEMS
26. The memory display doesn't work right. Why?
This is a known bug with the svr42 module. 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.
STILL STUCK
27. I'm still stuck. To whom do I report problems with top?
The most common problems are caused by top's sensitivity to internal
kernel data structures. So make sure that you are using the right
include files, and make sure that you test out top on the same
machine where you compiled it. Sun's BSD Source Compatability Mode is
also a common culprit. Make sure you aren't using either /usr/ucb/cc
or any of the libraries in /usr/ucblib. Finally, make sure you are
using the correct module. If there does not appear to be one
appropriate for your computer, then top probably will not work on
your system.
If after reading all of this file and checking everything you can you
are still stuck, then please use SourceForge to submit a support
request or a bug. Top is supported by the SourceForge project named
"unixtop". On SourceForge you will find defect tracking, a mailing
list, and on-line forums. You can also contact the author through
SourceForge.
TOP
Version 3.6.1
William LeFebvre
and a cast of many
INSTALLATION
Configuration and installation of top is easy. Top version 3.6
comes with a configure script generated by gnu autoconf. After
unpacking the tar file, simply run "./configure". The script will
automatically perform a series of checks on the system and determine
what settings are appropriate for the Makefile and certain include
files. Once configure completes, simply type "make install" and
top will be compiled and installed. By default, the installation
location is /usr/local/bin. You can change the destination location
with the --prefix option to configure.
In addition to the standard options, top's configure script supports
the following:
--with-module=name
Force the use of a particular module. Modules are located
in the subdirectory "machine". A module's name is derived
from the file's basename without the leading "m_".
--with-ext=name
Compile with the extension "name", found in the subdirectory
"ext". At the present time, there are no extensions in the
standard distribution.
--enable-debug
--disable-debug
Default off. Include debugging output in the compilation,
which can be seen with the -D switch.
--enable-color
--disable-color
Default on. Include code that allows for the use of color
in the output display. Use --disable-color if you do not
want this feature compiled in to the code. The configure
script also recognizes the spelling "colour".
--enable-kill
--disable-kill
Default on. Include code that allows for renicing and sending
signals to processes from within top (the 'kill' and 'renice'
commands). Use --disable-kill if you do not want this feature
compiled in to the code.
Copyright (c) 2005, William LeFebvre
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
* Neither the name of William LeFebvre nor the names of other
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
README
INSTALL
FAQ
LICENSE
Y2K
Changes
Porting
Makefile.in
configure
configure.ac
config.guess
config.sub
install-sh
top.c
color.c
commands.c
display.c
screen.c
username.c
utils.c
version.c
getopt.c
boolean.h
color.h
commands.h
config.h.in
display.h
help.h
layout.h
loadavg.h
machine.h
message.h
os.h
screen.h
top.h
username.h
utils.h
version.h
sigconv.awk
top.1.in
machine/*.c
machine/*.h
machine/*.man
ext/*.c
ext/*.libs
# Makefile
#
# This makefile was generated by configure from a Makefile.in definition.
PROGRAM=top
SRC=color.c commands.c display.c screen.c top.c username.c utils.c version.c @SRC@
OBJ=color.o commands.o display.o screen.o top.o username.o utils.o version.o @OBJ@
MANPAGE=top.1
CLEAN_SRC=sigdesc.h
srcdir=@srcdir@
prefix=@prefix@
exec_prefix=@exec_prefix@
bindir=@bindir@
mandir=@mandir@
VPATH=@srcdir@
PACKAGE_NAME=@PACKAGE_NAME@
SIGNAL=@SIGNAL_H@
AWK=@AWK@
CC=@CC@
CFLAGS=$(DEFS) $(DEFAULT_INCLUDES) @CFLAGS@
CFLAGSONLY=@CFLAGS@
CPPFLAGS=@CPPFLAGS@
DEFS=@DEFS@
LDFLAGS=@LDFLAGS@
LIBS=@LIBS@
INSTALL=@INSTALL@
INSTALL_PROGRAM=@INSTALL_PROGRAM@
INSTALL_DATA=@INSTALL_DATA@
INSTALL_OPTS_PROG=@INSTALL_OPTS_PROG@
INSTALL_OPTS_DATA=
DEFAULT_INCLUDES = -I. -I$(srcdir)
COMPILE = $(CC) $(CPPFLAGS) $(CFLAGS)
LINK = $(CC) $(CFLAGS) $(LDFLAGS) -o $@
all: $(PROGRAM)
$(PROGRAM): $(OBJ)
$(LINK) $(OBJ) $(LIBS)
# explicit dependency for the module appropriate to this machine
m_@MODULE@.o: $(srcdir)/machine/m_@MODULE@.c
$(COMPILE) -o $@ -c $(srcdir)/machine/m_@MODULE@.c
sigdesc.h: sigconv.awk $(SIGNAL)
$(AWK) -f $(srcdir)/sigconv.awk $(SIGNAL) >sigdesc.h
install: $(PROGRAM) install-man
mkdir -p $(DESTDIR)$(bindir)
$(INSTALL_PROGRAM) $(INSTALL_OPTS_PROG) \
$(PROGRAM) $(DESTDIR)$(bindir)/$(PROGRAM)
install-man: $(MANPAGE)
mkdir -p $(DESTDIR)$(mandir)/man1
$(INSTALL_DATA) $(INSTALL_OPTS_DATA) \
$(MANPAGE) $(DESTDIR)$(mandir)/man1/$(MANPAGE)
clean:
-rm -f $(PROGRAM) $(OBJ) $(CLEAN_SRC)
distclean: clean
-rm -f Makefile config.status config.cache config.log config.h
configure: configure.ac
autoheader
autoconf
commands.o: os.h config.h sigdesc.h top.h boolean.h utils.h version.h help.h
display.o: os.h config.h top.h machine.h screen.h layout.h \
display.h boolean.h utils.h color.h
screen.o: os.h config.h top.h screen.h boolean.h
top.o: os.h config.h top.h machine.h commands.h display.h \
screen.h boolean.h username.h utils.h version.h color.h
username.o: top.h utils.h
utils.o: top.h os.h config.h utils.h
version.o: top.h
m_@MODULE@.o: config.h top.h machine.h loadavg.h
To prepare a new release:
Update the version number in the following files: configure.ac, INSTALL, README, top.faq
Update Changes
Make sure MANIFEST is up to date
make configure
./makefaq
cp top.faq.shtml top.faq.toc.html /www/unixtop
syncweb unixtop
svn update
test the release:
cd ../tarballs; ./mktar current
cd ../test; tar xvf ../tarballs/top-current.tar
cd top-current; ./configure; make
chdir to the top level (top-3)
svn copy trunk release/<version>
svn commit -m "Creating release <version>"
cd tarballs; ./mktar <version>
cp <version>.tar.* /www/unixtop/dist
modify /www/unixtop/download.shtml to point to new version
ftp tar files to upload.sourceforge.net (bin, passive, hash) in /incoming
Add release to project (release name: top-<version>)
Use "./fmtchanges Changes" to get a cut-n-paste version of the changelog
chdir to top level (top-3)
svn update
./svnmirror
go to sourceforge and submit request to update svn
Instructions for porting top to other architectures.
This is still a preliminary document. Suggestions for improvement are
most welcome.
Before you embark on a port, please send me a mail message telling me
what platform you are porting top to. There are three reasons for
this: (1) I may already have a port, (2) module naming needs to be
centralized, (3) I want to loosely track the various porting efforts.
You do not need to wait for an "okay", but I do want to know that you
are working on it. And of course, once it is finished, please send me
the module files so that I can add them to the main distribution!
----------
There is one set of functions which extract all the information that
top needs for display. These functions are collected in to one file.
To make top work on a different architecture simply requires a
different implementation of these functions. The functions for a
given architecture "foo" are stored in a file called "m_foo.c". The
Configure script looks for these files and lets the configurer choose
one of them. This file is called a "module". The idea is that making
top work on a different machine only requires one additional file and
does not require changes to any existing files.
A module template is included in the distribution, called "m-template".
To write your own module, it is a good idea to start with this template.
If you architecture is similar to one for which a module already
exists, then you can start with that module instead. If you do so,
remember to change the "AUTHOR" section at the top!
The first comment in a module contains information which is extracted
and used by Configure. This information is marked with words in all
capitals (such as "SYNOPSIS:" and "LIBS:"). Go look at m-template: it
is fairly self-explanatory. The text after "LIBS:" (on the same line)
is extracted and included in the LIBS definition of the Makefile so
that extra libraries which may be necessary on some machines (such as
"-lkvm") can be specified in the module. The text after "CFLAGS:"
<