                                    TOP
                                Version 3.5

                             William LeFebvre
                        with much help from others


               Frequently Asked Questions and their Answers

SECTIONS

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.  Visit
     SourceForge and search for the project "unixtop".  European users may
     also consider using the Denmark (dk) mirror site sunsite.auc.dk.

 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.  "Top is not written in ANSI C.  Do you ever plan to change that?"

     Top predates ANSI C by about 5 years.  Yeah, it'll get "fixed"
     eventually.  Probably in the next major release.

 7.  "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 end of 2004.

 8.  "What about the current major release, version 3?"

     Top version 3.5 has been stuck in beta for years, primarily due to a
     lack of time and energy on my part.  This package marks the final
     official release of version 3.5.  As I focus more time on version 4,
     I expect that the only changes I will be making to version 3 are bug
     fixes and contributed modules.  There may be some feature enhancements
     to future releases of version 3, but don't expect too many.

 9.  "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 dop 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.6 may have this functionality but it is not present
     in the standard top 3.5 release.


     Configuring

10.  "Configure said that it saw /proc and is recommending that I install
     top setuid root.  Is there any way around this?  Is it safe?"

     There is no way around it.  Complain to POSIX.  Every effort has been
     made to make top a secure setuid program.  However, we cannot
     guarantee that there are no security problems associated with this
     configuration.  The places where top is most vulnerable are the
     builtin kill and renice commands.  There is no internal top command
     that causes top to start a shell as a subprocess.  Some SVR4 systems
     may contain a bug that enables a user to renice his own processes
     downward (to lower nice values that are more favorable for the
     process).  This problem has been fixed for the Solaris 2.x modules,
     but may still exist in others.  We will hopefully fix this up in the
     next release.

11.  "Why is Configure a c-shell script?  I thought c-shell scripts were 
     evil?"

     They are.  :-)  The next major release of top will use Gnu configure.
     But it is not worth the effort at this point to try to integrate Gnu
     configure in to the top 3 code base.


     Compiling

12.  "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

13.  "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".

14.  "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.

15.  "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 bigger.

16.  "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.4 to Solaris
     2.5) 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 "cc".

17.  "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.


     SunOS Problems

18.  "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.


     SVR4-derived Problems

19.  "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 displayes process information for my own
     processes).  Yet when I run it as root, everything works fine."

     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.


     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.

20.  "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.

21.  "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.

22.  "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.

23.  "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.

24.  "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.

25.  "When I try to compile top under Solaris 2.6 using gcc I get compile
     time errors.  There appear to be problems with the include files,
     such as 'u_rlimit has incomplete type' and/or 'u_saved_rlimit has
     incomplete type'.  I've already run fixinc.svr4 as per FAQ 16.
     Why didn't that fix it?"

     Only top versions 3.5 and later are compatible with Solaris 2.6.  Make
     sure you are using the most up-to-date version.  Earlier beta release
     copies of version 3.5 had additional problems when compiled with gcc.
     Retrieve the official version 3.5 (non-beta) release from one of the
     sites listed in FAQ 2.

26.  "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.  You can do this with Sun's C compiler and with a
     recent version of Gnu's C compiler.  Top's configure script attempts
     to detect 64-bit systems, and will adjust the default choice for
     "Compiler options" accordingly.  However, if you are on a 32-bit
     system and need to create 64-bit images, Configure will not choose
     the correct defaults.  For Sun's C compiler, set the compiler 
     options to "-xO4 -xarch=v9".  For gcc, set the compiler options
     to "-O -m64".

27.  "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 26) 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.


     SCO Problems

28.  "When I try to run Configure, it complains about a syntax error."

     Some versions of SCO's csh do not understand the syntax "$<".  Earlier
     releases of top depended on this syntax to read input from the
     installer's terminal during the installation process.  Version 3.5
     fixes this.


     SVR42 Problems

29.  "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

30.  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.

