The kmem-ps suite of programs for Linux 1.1.18

For news about this version, please see the file NEWS.

Rick Sladkey <jrs@world.std.com>

==============================================================================

Ps for Linux 0.99.10

New in this release / Changes:
- free now also shows total memory use (swap+ram), you can use the -t
  option to show totals only.
- ps now accepts a comma separated list of pid's instead of just one pid.
- The flags field from the long format has been moved to the -X format.
- The STAT field has some new letters:
	x	process is being ptraced
	X	system calls are traced
	s	process is a session leader
	+	process is in the foreground pgrp of the ctty
- fstat/fuser and free updated for dynamic inode/file tables in 0.99.10.


Top was written by Roger Binns, w/uptime is from BSD net-2, both were
modified by me.  Rick Sladkey sent me patches for the new fstat socket
output format, and the new help memu in top is by Marcel Mol.


Installing:

If you want to use ps or any of the other programs in this distribution
you have to compile the Linux kernel yourself, the bootimages don't have
a symbol table, you need the file "linux/tools/system" for this.  Also
important: you must reboot from the kernel you have compiled before you
can use ps.

Edit the ps Makefile if you have your kernel source somewhere else than
/usr/src/linux, then type make in the ps directory. You can install the
programs by typing "make install", this will copy the programs to
/bin and set the file mode and owner right. /dev/kmem and /dev/swap
will also be given the right modes.

After you installed ps, run 'ps -U' to create the psdatabase.

You can specify the system binary and the swap device/file as arguments:

	ps -U /usr/src/linux/tools/system /dev/swap

These two path names are the default ones, you don't have to specify
them if they are the same on your system.  If you use a swapfile, you
can create a symlink '/dev/swap' to this file.  You only have to specify
the path names the first time you run 'ps -U', the names will be stored
in the psdatabase.

Free prints info for all swapfiles/devices, ps and top can read from all
swapfiles but this is just a quick hack: you have to make symlinks from
the swapfiles to /dev/swap[1-7].  The first swapfile can still be
configured with ps -U, the default is still /dev/swap, the others are
hardcoded.  The order in which you call swapon on the different files
is also important:

swapon /dev/swap
swapon /dev/swap1
swapon /dev/swap2
etc..

Ps will still work if the links are wrong, only you will see names of
swapped out processes in parentheses, without command line arguments.


Always run 'ps -U' after you installed a new kernel, also note that
it may be necessary to recompile ps and the other programs when you
upgrade to a new version of Linux.



fstat usage:

Without arguments fstat shows open files for all processes, the file
names are usually unknown, it prints device numbers and inode number, you
can use find(1) to get the filename.  With arguments, fstat only shows
processes that have the files/directories you specified open.

Options:
	-p pid	show pid only
	-u user	show files open by user
	-f	arguments can be mounted file systems (dev or dir)
		only files open on the specified filesystems will be shown
	-n	numeric output for file mode, /dev and /lib will not be
		scanned to find filenames
	-d	directory arguments will be scanned to find the matching names
		for open files, per default fstat will scan /dev and /lib



fuser usage:

fuser is a link to fstat, the -u and -f option are the same as for fstat.
The -k flag (not present in fstat) can be used to kill all processes
that have the specified files open, or (with -f) have files on one of
the specified filesystems open.



Usage summary for top:

There are 24 fields that can be displayed for each process.  These are copies 
of the fields that ps would display.  You can select which fields you want
displayed or not.  Top can save this (to ~/.toprc) and will use it the next
time you run top.

The interval for update can be changed from zero to nine seconds.

Top displays a line giving help for keys.  Longer descriptions:

q	quit
k	kill - send any process a signal (default is SIGKILL)
n	nice - renice any process (default nice value 5)
c	sort processes by cpu usage
m	sort processes by memory usage
0 to 9	change update delay (in seconds)
A to X	toggle display of field
ctrl-W	write update delay, which fields are displayed to .toprc
	top reads this file on startup	
?	display help screen with all available fields, toggle
	fields with a-x
	


Options for the program free:

	Without options free gives memory and swap space usage.

	-m	memory
	-s	swap
	-i	inodes
	-b	buffers
	-d dev	only count buffers for 'dev' (use with -b or -i)
	-f	file descriptors
	-r	requests
	-p	display number of pages instead of kb (only with -m 
		and -s)
	-S #	repeat with delay of # seconds

	The pathname of the swap device or file is taken from the
	psdatabase, or can be specified on the command line.



Tload options:

	-b 	With this option tload will only update a virtual console
		display if it is the foreground console, this way tload
		used almost no cpu-time if it is running in a background
		window.  You can you can run tload in an unused window
		by giving the tty name on the command line:
			tload -b /dev/tty8 &

	-d n	sets the update delay (default 5 seconds, xload uses 10)

	-s n	set the scale (default is 6)



Manpages are included for ps, w and uptime. The files with suffix .0
are the formatted pages. The pages for w and uptime are the unmodified
ones from net-2. Michael Haardt wrote the ps manpage.



Bugs/Notes:

The shared text size (SHRD in -m format) also includes pages shared
with the buffer cache.

WCHAN (-l format) shows the function in which the process is sleeping,
the 'sys_' part is stripped from function names.

%CPU (-u format) shows the cputime/realtime percentage, not a decaying
average as in unix ps. %CPU in top is more like unix, the percentage is
measured between two screen updates.

%MEM, because of shared pages this field can add up to more than 100%
if you run top with TRS, SWAP, SHARE, A, WP or D enabled, this field
should add up to 100%, shared pages are counted less heavily than
unshared pages.

Top uses more cpu time if you enable one or more of the following
fields: TRS, SWAP, SHARE, A, WP, D 

The SIZE and RSS fields don't count the page tables and the
task_struct of a proc, this is at least 16k of memory that is always
resident (20k with shared libraries). SIZE is the virtual size of the
proc (code+data+stack).

Tty names are hard coded: virtual consoles are a1, a2, ...  serial
lines are 00 and 01, pty's are p0, p1 ...


Branko Lankester
branko@hacktic.nl || lankeste@fwi.uva.nl                   Jun 21 1993
