README for version 0.97 of procps
=================================
Read this, really.
==================

Thanks to all the people who have helped write programs and documentation for
this suite of /proc programs.  I still have a few things I want to do with top
before I go 1.0 on the suite.  `ps' is starting to look really complete now
though.

Please send any comments, patches, bug reports, etc. to cblake@ucsd.edu.

IMPORTANT: The kernel has changed in how it reports tty device numbers in the
/proc/*/stat files.  If you have a newer kernel uncomment the TTY_FULL_DEVNO
in Makefile, or you'll get meaningless tty information. Note that Linus is
thinking about releasing a late 1.1.5x kernel as a 1.2.0 feature-stable
kernel.  At that point I will probably reverse the assumption about this
behavior -- full device numbers will be the default and people with older
kernel versions will have to uncomment a constant.

Note: If you want to compile these programs under SLS 1.03, you are on your
own.  The SLS 1.03 kernel sources are broken.  There are also some broken
1.1.3x kernel header files.  They should be mostly fixed by 1.1.36 or so.  If
you just *can't stand* getting new kernel sources before trying to compile,
you can add -D__KERNEL__ to CFLAGS and it should mostly work -- but I don't
guarantee that subtle problems won't corrupt the behavior of the programs.

Note 2: The default installation directory has been changed from /bin to
/usr/bin in an attempt to follow the draft FSSTND standard.  Please make sure
that you remove any old copies of these programs that are still in /bin.
Warnings will be printed when you run "make install" if any of the programs
have copies in /bin.  Also, psupdate now goes in /sbin instead of /etc.  'ps'
itself is the only program which goes in /bin.  Also note, if you want to
install the proc ps utilities and man pages with a prefix to their names (e.g.
ps -> procps) check out the "prefix" variable at the top of the Makefile.

Note 3: Please ignore any warnings about "`rcsid' defined but not used".

Here are the notes for the individual programs:

*MAKEFILE*
The makefile now uses `install' instead of `cp'.
If you don't have install you can get it from the GNU `fileutil' package --
prep.ai.mit.edu:/pub/gnu/fileutils-3.9.tar.gz.

See the top of the makefile for things like the MANOWNER, BINOWNER, etc. Also,
shadow password users, I've added $(LIBS) to the end of all the link lines so
just uncomment the -lshadow at the top to get shadow support (I think :-).


*LIBPROC*
Modularized some of the routines and fixed some long standing bugs.  Replaced
the regex() recognition of /proc/PID with a simple check of the first
character of the filename being numerical.


*PS*
The 'e' environment printing option has been implemented.  I personally think
the output is quite ugly.  Any suggestions for an alternative which 1) takes
advantage of most of the space available after the command line and 2) looks
bettern than the current output will be most appreciated.

Read the new man page for full details on what ps can do.  In short since a
couple releases ago, we have very flexible listing by sets of PIDs, sorting,
and forest representation. The sort keys are still subject to change if anyone
has any suggestions.

Although procps suggests using the : character in the option list, you can
actually use any single character you want.  GNU uses =, but apparantly some
shells (e.g. rc) don't like that.  Take your pick...

In order to get WCHAN output for ps, you must update the psdatabase for each
new kernel.  Unlike with kmemps, no version checking is done at this time, so
if you forget to update the database, you'll get funny addresses.  There is no
"ps -U" option for updating the psdatabase; instead, a psupdate program is
included.  It defaults to installing in /sbin/psupdate, and can be put in your
/etc/rc so that it is called on boot, or in your /etc/lilo/install script (if
you have one).  Your choice.  Alternate namelist support is not available.  If
you want that, use kmemps.

Oh, yeah, psupdate is not suid root, and so you must be root to run it.  If
you like, make it suid root, and then anyone can run it.  I don't guarantee
that it is a safe suid program, but I don't know anything in it to be unsafe,
either.

If you don't want to deal with a psdatabase, you can safely ignore this, and
not create the psdatabase.  ps will simply default back to numeric addresses
in the WCHAN field.

The /etc/psupdate distributed in /procps is still not very good.  If you want
to use both procps and kmemps, *use kmemps* to create the /etc/psdatabase.
THIS IS IMPORTANT.  /etc/psupdate makes a file which, though it is mostly
compatible, might cause problems on some systems, maybe.

If you get extremely bogus numbers for the RSS for X (or other memory mapping
programs), upgrade your kernel.  With .12 and .13 I got RSS sizes of about
5-10 times physical memory (if I recall correctly) in my machine.  RSS seems
to be reported correctly in the 1.0.x and 1.1.x kernels.


*TOP*
A few option parsing things have been cleaned up.

top now includes the much-wanted q command-line option.  This causes redisplay
to happen without pause, and, if you are superuser, it also causes top to run
at the highest possible priority.

top is now much more robust in its input handling.  It should also handle more
terminals than it used to.  It also supports an 'i' command which ignores idle
processes.

top also supports a default signal and default renice value if you don't enter
one.

Now thanks to Michael Shields, there is a "secure" mode for top which disables
some of the more dangerous interactive features.  He has also substantially
re-written and beautified the man page for top and added some nice error
checking features.  We hope no bugs have crept into top as it has undergone
some substantial modifications/improvements.  Stress test it, read the new man
page, suggest new features.


*TLOAD*
tload is included.  This is now based on the kmem ps one.  I have also
included a different version with a slightly different display, called
tload2.c.  I have not included an entry in the makefile, but if you want to
play with it, be my guests.  Please tell me what you think, and why, if you
have any strong opinions on the subject.


*FREE*
The default behavior of free is now to output a line underneath the first
which "adjusts" the free/used memory by adding/subtracting the buffers.  This
is to satify two purposes: 1) clue in newbies that buffers are only
sorta-kinda used memory and 2) perform arithmetic that lots of us often do in
our heads anyway.  A command line flag to turn this new behavior off is
included.

New command line options have been added for continual looping with a delay
and for megabyte reporting.  See the updated and beautified man page.

Also, Linus's free has been replaced with one that has slightly nicer
formating.  Linus's free has been renamed free.old.c, so if you prefer the old
style, simply "mv free.old.c free.c", "make free"


*W AND UPTIME*
Some bugs in w have been fixed and the uptime man page clean up.

w has been updated to include an optional remote hostname field, called
"from", and the "what bug" has been fixed, so that you will now see the
correct program in the "what" field again.  The man page is updated.  As of
version 0.92, the "from" field is not displayed by default, but you can change
the default by removing a single comment character in the Makefile, so that
the "from" field is displayed by default.  The -f flag is now a toggle which
turns display of the "from" field on and off.  I hope everyone is satisfied
now...  Also, the bug where numbers weren't printed in the "from" field is
gone.  I fixed the isnice() function, for those who want to know what I did...

Another version of w, which doesn't always work right, is provided in w2.c.
Use at your own risk.  It seems to work on systems where utmp is always
maintained in perfect condition.


                        ----- PSMISC PROGRAMS -----

If you find any bugs in fuser, killall, or pstree, please contact Werner. His
email address is almesber@bernina.ethz.ch.  I won't fix these programs myself
because I want to keep in sync with Werner.

GENERAL: fixed generation of signal list to include SIGUSR[12], minor updates
CHANGES  and improvements to man pages, display an error message if /proc has
         no process entries (i.e. if it is not mounted)

*FUSER*
Instead of documenting limitations, as the SunOS version does, Werner fixed
them while writing this version.  Fuser identifies processes using files
(similar to Sun's or SGI's fuser).
         FROM CHANGES
  suppresses m(map) if file is e(xecuted),
  now also accepts signal numbers,
  doesn't kill itself.

*KILLALL*
killall kills processes by name, e.g. "killall -HUP named".  Thanks, Werner!

This killall does not provide the behavior that the SysVinit wants. However,
that package does provide a program called killal.  Use it instead.
         FROM CHANGES
  more detailed usage output, added killing by file, doesn't kill itself

*PSTREE*
pstree shows the currently running processes as a tree.  Thanks again...
         FROM CHANGES
  -h didn't work because of incorrect termcap usage
  changed branch drawing from --- to -+-
                                 \-     `-
  added -a to display command line arguments
  fixed indentation inside compacted subtrees


*X PROGRAMS*
If you want xload, please "make xload".  Ditto for xmem and XConsole. To make
all of the X programs, "make xprogs".  Because not everyone has X, it is not
part of the make all target.  The install target now installs the application
default files for both of these programs, if the programs exist.

XConsole reads and displays messages from /proc/kmsg, and it also displays the
time, date, and kernel version number.  It needs to be run suid root to read
/proc/kmsg, and won't run otherwise.  DON'T USE THIS IF YOU ARE USING ANY
OTHER SYSLOG PACKAGE!!!!!!!!!!!!!!!!!!!!!! THIS IS VITALLY IMPORTANT -- I
WOULDN'T YELL OTHERWISE...


*BUGLETS*
Also, I know that the Makefile created by the Imakefile is not yet used to its
best advantage -- I am not a real X hacker, and all the X programs were
donated by someone else.  In the mean time, I apologize for any damaged
sensibilities.  If you are too offended, I encourage you to send me a fixed
version, preferably as a patch.  If you are *really* offended, but don't want
to fix them yourself, I'll do it myself if you'll send me a copy of the
O'Reilly book on imake...


*GNU FINGER PATCH*
I have included a patch for gnu finger, in the file gfinger.patch.  It allows
gnu finger to get its information from the proc filesystem.


*TO MAKE THE PACKAGE*
You will probably want to examine the instdir, xinstdir, and xdefinstdir
variables, and change them if necessary.  You will also have to be root to run
`make install', as it chowns the executables to root.  Note that they are
*not* suid, though, except for Xconsole.


Oh, and as a reward for reading this README files through, here's how to
compile and install the whole package, using all the default programs and
directories:
	make
	su
	make xprogs
	make install
	exit
	make clean

Leave out the make xprogs if you don't have X installed.  Don't worry too much
about the su before make xprogs, as only XConsole is made suid root, and that
is pretty safe.  It doesn't accept input of any kind, and only reads
/proc/kmsg.  Indeed, reading /proc/kmsg is the only reason why it is suid
root.  See the warning above (under *X PROGRAMS*) about XConsole

The utmp program is just for debugging.  Don't worry about it unless you are
having problems with any of these programs, you mail me, and I ask you to run
it.
