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

Thanks to all the people who have helped write programs and
documentation for this suite of /proc programs.  This should be the
final BETA release -- if this release shows few or no bugs, it will be
re-released in bug-free (hah) form as version 1.0.  Note that Charles
Blake has taken over the /proc suite in lieu of Michael's rise to
power (and fall from free time :-) as the editor of Linux Journal.

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.3x 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:

*PS*
ps can now be given a comma or space delimited list of PID's to report
on.  Thanks to Michael Shields.

Multiple format specifications no longer result in an error.  The last
one specified is used.

Some annoying printf format warnings were dealt with.  (really libproc
not ps, oh well...).  Compilation should be generally a little less
noisy.

ps now can sort its output in any way you wish, with as many as 15
different sort keys.  The command line argument handling has been
improved.  Thanks to Charles Blake for this new functionality.  We
hope there are no bugs that have been introduced with this new
functionality; please tell me if you find any.

The sort keys are subject to change while we experiment with them.
If you have any opinions, please tell us.  We will try to have the
choices of keys stabilized by version 1.0 of procps.

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

A new command line option, -t, has been added, that prints a "Total:"
line at the bottom.  I'd like to hear opinions on whether this should
be the default behavior or not.

I'm also thinking of adding a -b option to include a "Buffer adjusted:"
line giving the amount of free memory + buffers and the amount
of used memory - buffers.  If you're like me, you're often doing this
computation in your head anyway, may as well have another output line.


*W AND UPTIME*
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.


*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).

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

*PSTREE*
pstree shows the currently running processes as a tree.  Thanks again...

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.


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