devfsctl - Cleanup of usage() and its callers

[dragonfly.git] / contrib / top / FAQ

                             TOP
                          Version 3.5
                        Beta Release 11

                       William LeFebvre
                  with much help from others


FREQUENTLY ASKED QUESTIONS AND THEIR ANSWERS

This FAQ is broken out in to several topics.


GENERAL

 1.  "Where do I get the latest version of top?"

The official site for top is "ftp.groupsys.com" in the directory
"/pub/top".  It is also available from the following mirror sites:
"pharos.dgim.doc.ca" in /packages/top, "uiarchive.uiuc.edu" in
/pub/packages/top, "sunsite.auc.dk" in /pub/unix/top.  European
users should consider using the Denmark (dk) site.
 
 2.  "Is there a web page for top?"

Yes.  Point your browser at http://www.groupsys.com/top.  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 pointers to the mailing list.

 3.  "Is there a mailing list for top?"

The official list for announcements is "top-announce@groupsys.com".
This list is managed by "majordomo@groupsys.com".  Announcements of
importance to all top users will be sent to this list, including new
releases, availability of beta test versions, emergency revisions and
patches, etc.  Anyone is welcome to join top-announce.  This is a
read-only list.  The list of subscribers will not (intentionally) be
made available, and postings to the list are limited.

In addition, there is a top developers mailing list that is used by
beta testers and other people who help me port the program to various
machines.  Membership to this list is solely at my discretion.  If you
feel qualified to act as a beta tester, or if you are doing development
work on top (such as porting to a new platform), you may submit a
request by sending a message to "top-spinners-request@groupsys.com"
containing the word "subscribe".  I will contact you within a few days,
as my schedule permits.

 4.  "What about Year 2000 compliance"?

Top should 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.


 5.  "Why does it take so long for a new version of top to go through the
      beta test process?"

This is completely my fault.  I have just not had the time to give top
the attention it deserves.  I thank everyone for their patience, and I
hope that with the recent changes in the direction of my career that I
can spend more time on this.

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


CONFIGURING

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

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

They are.  :-)  I'll probably be rewriting the Configure script for the
next release, or switching to something like Gnu configure.


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 "intsall" 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.  If you encounter a system where 
this large memory display overflow is still occurring, please let me know 
(send mail to <wnl@groupsys.com>).  Also note that newer versions of top can 
use columns beyond 79, and understand window resizes.  So you can always 
make your window bigger.

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.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".
Solaris 2.6 users should also consult FAQ #20.

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.


SUNOS PROBLEMS

15.  "I tried compiling top under SunOS version 4.1.x and it got compile 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

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

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

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

19.  "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 #10 for more details.

20.  "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 #13.
      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 #1 or FAQ #2.


SCO PROBLEMS

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

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

23.  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 send mail to "wnl@groupsys.com".  I will answer your mail 
when I have time.  Please bear with me in that regard!  If it looks like the 
problem is machine-specific, I will forward the report along to the module's 
author.  If you would like to converse directly with the module author, the 
authors' names are listed at the beginning of the module .c file in the 
"machine" directory.