[net.sources] Reposting of SPS for 4.[12]bsd Vaxen - Shar 1 of 4

robert@hslrswi.UUCP (Robert Ward) (07/11/85)

The original posting of SPS seems to have been damaged on its
travels around the Usenet. Here, then, is a reposting.

SPS is intended to be a replacement for ps(1). Its advantages over ps
include the facts that it prints its information in a more
comprehensible format and that it is faster.

User-names are listed, rather than user-ids. Similarly, wait channels
are depicted symbolically rather than as hexadecimal numbers.
Processes are sorted so that their relationship is depicted in an
obvious manner. A child process, for instance, is listed immediately
under its corresponding parent ; the output is indented to show the
precise relationship.

SPS accepts a multitude of options to control its output. Listed
processes may be selected on the basis of ownership, process number or
controlling tty or whether the process is considered "busy" or not.
The output may be repeated with an arbitrary delay between listings.
SPS can also be made to list or to suppress the environment strings
of each process.

SPS must be initialised (with the "-i" option) before it can be used.
SPS then creates an "information file" summarising necessary kernel
addresses and user names. This means that SPS can avoid having to do an
expensive nlist() each time it is run. It does mean that it must be
reinitialised if users are added or removed from the passwd file or if
a new version of unix is installed.

To install SPS, unload the contents of the four shell archive files.
(If you are running a 4.1bsd system, you then need to change the line
the file DOIT so that the correct Makefile is linked to "Makefile").
Then run sh on the file DOIT. This should make SPS and test it out.  If
that works, it can then be installed in /bin/sps and reinitialised.

Please send comments, suggestions, bug reports, bug fixes, etc. to me.

*******************************************************************************

Robert Ward, Hasler AG, Abt. 34, Belpstrasse 23, CH-3000 Bern 14, Switzerland.
(... mcvax!cernvax!hslrswi!robert)

*******************************************************************************

This is a sh(1) archive.
In order to extract the contents of this shar, use an editor to place
the contents of this file from the dotted line onwards into a second,
temporary file. Then run sh on that second file.

--------------------------------- C U T --- H E R E ---------------------------
#! /bin/sh
echo Extracting DOIT
cat > DOIT << '---END-OF-DOIT---'
#! /bin/sh
echo Linking Makefile.4.2 to Makefile
ln Makefile.4.2 Makefile
echo Making SPS ...
make
echo Initialising \(Ignore any error message here\) ...
./sps i -j spsinfo
echo Testing \(Sps should now report verbosely about all processes\) ...
./sps va -j spsinfo
echo If that worked now type \"make install\" and reinitialise SPS
---END-OF-DOIT---
echo Extracting Makefile.4.1
cat > Makefile.4.1 << '---END-OF-Makefile.4.1---'
# Makefile for SPS (4.1BSD UNIX Version)

PROG	=	sps
OBJS	=	filecount.o findtty.o flagdecode.o flagsetup.o \
		getcmd.o getupage.o globals1.o globals2.o hashuid.o \
		initialise.o initsymbols.o inittty.o main.o mktree.o \
		needed.o openfiles.o percentmem.o prcmd.o prcpu.o \
		prheader.o printall.o printproc.o prsummary.o readstatus.o \
		selectproc.o selecttty.o termwidth.o ttystatus.o waitingfor.o

INCS	=	sps.h
LIBS	=	-ltermlib
CFLAGS	=	-I/usr/src/sys -DCHAOS

all:		$(PROG)
.c.o:
		cc $(CFLAGS) -c -O -R $<
globals1.o waitingfor.o:
		cc $(CFLAGS) -c -O $<

$(OBJS):	$(INCS)

$(PROG):	$(OBJS)
		cc -o $@ $(OBJS) $(LIBS)

install:	$(PROG)
		strip $(PROG)
		mv $(PROG) /bin/$(PROG)
		/etc/chown root /bin/$(PROG)
		chmod 4711 /bin/$(PROG)

lint:
		lint -x -b $(CFLAGS) *.c
clean:
		rm -f $(OBJS) $(PROG)
---END-OF-Makefile.4.1---
echo Extracting Makefile.4.2
cat > Makefile.4.2 << '---END-OF-Makefile.4.2---'
# Makefile for SPS (4.2BSD UNIX Version)

PROG	=	sps
OBJS	=	filecount.o findtty.o flagdecode.o flagsetup.o \
		getcmd.o getupage.o globals1.o globals2.o hashuid.o \
		initialise.o initsymbols.o inittty.o main.o mktree.o \
		needed.o openfiles.o percentmem.o prcmd.o prcpu.o \
		prheader.o printall.o printproc.o prsummary.o readstatus.o \
		selectproc.o selecttty.o termwidth.o ttystatus.o waitingfor.o
INCS	=	sps.h
CC	=	cc
CFLAGS	=	-DBSD42 -I/sys
LIBS	=	-ltermlib

all:		$(PROG)
.c.o:
		$(CC) $(CFLAGS) -c -O -R $<
globals1.o waitingfor.o:
		$(CC) $(CFLAGS) -c -O $<

$(OBJS):	$(INCS)

$(PROG):	$(OBJS)
		$(CC) -o $@ $(OBJS) $(LIBS)

install:	$(PROG)
		strip $(PROG)
		mv $(PROG) /bin/$(PROG)
		/etc/chown root /bin/$(PROG)

lint:
		lint -x -b $(CFLAGS) *.c
clean:
		rm -f $(OBJS) $(PROG)
---END-OF-Makefile.4.2---
echo Extracting README
cat > README << '---END-OF-README---'
		SPS - Show Process Status
		=========================
To compile, install and test, type the following commands (as super-user):
	% make			# Compile SPS
	% make install		# Install SPS into /bin/sps
	% sps i			# Initialise SPS
	% sps va		# Run SPS
********************************************************************************
The files in this directory are for the 4.[12]BSD / VAX-11 version of SPS.
Compiler options are as follows -
	-DCHAOS		if the Chaos network is incorporated into 4.xbsd
	-DTRACE		for testing/debugging purposes
	-DBSD42		compile SPS for 4.2bsd.
			Otherwise, SPS is compiled for 4.1bsd.
********************************************************************************
If you want to tell SPS about a new type of device, then add a new line to
the symbol table (see globals2.c),after ensuring that there is sufficient
room in the `info' structure. (NWAITSTATE may need to be increased in sps.h).
********************************************************************************
SPS understands if the size of internal kernel tables are changed under VMUNIX,
but must be recompiled if major modifications are made to the kernel.
---END-OF-README---
echo Extracting sps.ms
cat > sps.ms << '---END-OF-sps.ms---'
.if n .pl 66
.TH SPS LOCAL
.SH NAME
sps \ \ \-\ \ \ show process status
.SH SYNOPSIS
\fBsps\ \fP \ [ \fB-defgijkoqrslvwyABDFNPSTUWZ\fP ]\ \ [
\fIprocess\. |\. tty\. |\. user\. .\ .\ .\ .\ .\fP ]
.SH DESCRIPTION
\fISps\fP reports information concerning system processes.
It shows the current state of any process by
listing information such as ownership, CPU time usage, memory usage
and disc activity.
.PP
\fISps\fP should be used in preference to \fIps\fP(1)
as it is faster and the output is easier to understand.
.SH OPTIONS
By default, \fIsps\fP prints basic information about one's own processes.
The various options described below select other processes or make
\fIsps\fP more verbose.
.PP
Upper case options select processes to be described.
Lower case options specify the format of the output.
For instance, the options \fBBv\fP specify that \fIsps\fP
should list "busy" processes in a verbose format.
Unless there is any conflict, lower case options may be used
instead of upper case options, and vice versa.
.PP
The following options specify the format of the listed output -
.TP 8
\fB-d\fP
List output reflecting how each process affects the
disc and paging activity of the system.
.TP
\fB-e\fP
List the environment passed to each process.
.TP
\fB-f\fP
Include the process-id of the parent of each process.
.TP
\fB-g\fP
Include the process group of each process.
.TP
\fB-o\fP
Avoid looking at the swap device (/dev/drum). This tends to make \fIsps\fP
run faster, although no information concerning swapped processes
can be obtained.
.TP
\fB-q\fP
By default, \fIsps\fP
lists the sum of the user plus system times under the
\fITime\fP and \fIChild\fP fields.  This option forces \fIsps\fP
to list only the user times.
.TP
\fB-r\fP
Repeat the output indefinitely.
If the next argument is numeric, \fIsps\fP repeats the output with that
many seconds delay between each repetition.
Otherwise the output is repeated with no delay.
.TP
\fB-l\fP
.br
.ns
.TP
\fB-v\fP
List additional information in a verbose format. See below.
.TP
\fB-w\fP
List output in a wide format.  This option forces \fIsps\fP
to print all the command arguments, even if doing so extends the output
beyond one line.
.TP
\fB-y\fP
Show the status of each terminal line.
.PP
The following options specify which processes are to be described -
.TP 8
\fB-A\fP
List all processes.
.TP
\fB-B\fP
List busy processes.  A process is considered to be busy
if it is immediately runnable or awaiting a fast event such as disc I/O.
.TP
\fB-D\fP
List detached processes.
.TP
\fB-F\fP
List foreground processes.
.TP
\fB-N\fP
Show no processes at all. Only the summary line is printed.
.TP
\fB-P\fP
List only processes whose identifiers are specified in the following arguments.
.TP
\fB-S\fP
List stopped processes.
.TP
\fB-T\fP
List only processes attached to the following specified terminals.
.TP
\fB-U\fP
List only processes belonging to the following specified users.
.TP
\fB-W\fP
List waiting processes.
.TP
\fB-Z\fP
List zomby (exiting) processes.
.PP
The following are miscellaneous options -
.TP 8
\fB-i\fP
Initialise \fIsps\fP.
This is necessary if new users are added to the password file,
or if a new version of UNIX is installed.
Sps builds a new information file summarising pertinent information
read from the password file (/etc/passwd), the executable kernel image
(/vmunix) and the directory of tty devices (/dev).
See also the \fB-j\fP and \fB-s\fP options.
.TP
\fB-j\fP
Specify an information file other than the default (/etc/spsinfo).
The next argument is taken to be the name of a suitable information file.
If the \fB-i\fP flag is also specified, \fIsps\fP builds a
new information file with the given name.
Otherwise, \fBsps\fP reads previously created summarising information
from that file.
.TP
\fB-k\fP
Use a specific disc file rather than the default physical memory (/dev/mem)
and kernel virtual memory (/dev/kmem) files. The next argument is taken
to be the name of a suitable memory dump file.
This flag automatically sets the \fB-o\fP flag.
.TP
\fB-s\fP
This option is used in conjunction with the \fB-i\fP option.
The next argument is taken to be the name of a suitable kernel executable
file, rather than the default (/vmunix).
\fISps\fP looks at the symbol table of this file to determine
the virtual addresses of various kernel structures.
.SH OUTPUT
\fISps\fP produces output in the following fields -
.TP 8
\fITy\fP
The terminal identifier to which the process is attached.
.IP
If this is followed by an underscore, the process is detached.
If it is followed by a period, the process is running in the foreground.
Otherwise the process is running in the background but is still
attached to a terminal.
.TP
\fIUser\fP
The symbolic name of the process' effective user-id (see \fIexec\fP(2)
and \fIsetuid\fP(2)).
This name is defined by the system password file (/etc/passwd)
when \fIsps\fP was last initialised.
Otherwise, an asterisk (*) or vertical bar (|) appearing in this
column denotes that the process is an immediate relative of the
preceding process.
A bar is listed, rather than an asterisk, if both processes belong
to the same process group.
In this case, a user name is listed only if the effective user-id
differs from that of the preceding process.
.TP
\fIProc#\fP
The unique process identifier.
.TP
\fIPpid#\fP
The process-id of the process' parent.
.TP
\fIPgrp#\fP
The process group to which the process belongs.
.TP
\fICommand\fP
The command arguments obtained from the process' own address space.
(If the command name appears in parentheses, \fIsps\fP
was unable to locate the arguments in user space and so reports
the system's idea of the command name.)
.PP
The following additional fields are listed when \fIsps\fP
is invoked with one of the \fB-l\fP or \fB-v\fP options -
.TP 8
\fIStatus\fP
The process' current state.
If this field is listed in upper-case letters, the process is currently
loaded in real memory space ; otherwise it has been swapped out.
The status field may contain one of the following descriptions -
.RS 8
.TP 16
\fIrun\fP
The process can be run immediately.
.TP
\fIstop\fP
The process is stopped (see \fIsigsys\fP(2) or \fIsigvec\fP(2)).
.TP
\fIexit\fP
The process is a zomby.
.RE
.IP
Any other entry in the status field indicates the process is
waiting for some external event to occur.
This is usually for one of the reasons listed below.
(If \fIsps\fP does not know why a process is waiting, it lists
the hexadecimal address of the process' wait channel,
with the initial 80000000 trimmed off.)
A process may be waiting for one of the following reasons -
.RS 8
.TP 16
\fIchild\fP
The process is waiting for a child to terminate (see \fIwait\fP(2)).
.TP
\fIpause\fP
Waiting for a signal to be received (see \fIpause\fP(2)).
.TP
\fIswap\fP
Waiting for a page to be swapped in.
.TP
\fIrswbuf\fP
Waiting for a read from the swap device
\fB/dev/drum.\fP
.TP
\fIdiscio\fP
Waiting for a disc read or write operation.
.TP
\fIrpipe\fP
.br
.ns
.TP
\fIwpipe\fP
Waiting for a read from an empty pipe.  Alternatively, the process
is waiting to write to a full pipe (see pipe\fI(2)\fP).
.TP
\fIrsockt\fP
.br
.ns
.TP
\fIwsockt\fP
Waiting for a read from an empty socket.
Alternatively, the process is waiting to write to a full socket (4.2bsd only).
.TP
\fIsocket\fP
Waiting for a time-out event on a socket (4.2bsd only).
.TP
\fIselect\fP
Blocked by a \fIselect\fP(2) system call (4.2bsd only).
.TP
\fIrmux\fP
Waiting for a read from a multiplexor file (4.1bsd only).
.TP
\fIinode\fP
Waiting for an inode to be allocated or unlocked.
.TP
\fIexlock\fP
.br
.ns
.TP
\fIshlock\fP
Waiting for a file to become unlocked (see flock\fI(2)\fP).
.TP
\fIrtty??\fP
.br
.ns
.TP
\fIwtty??\fP
.br
.ns
.TP
\fIotty??\fP
Waiting for a read or write to the specified terminal, or for the terminal
to be switched on (see \fItty\fP(4)).
Alternatively, waiting for a read or write to the
specified slave pty device (see \fIpty\fP(4)).
.TP
\fIrpty??\fP
.br
.ns
.TP
\fIwpty??\fP
Waiting for a read or write to the specified master pty device
(see \fIpty\fP(4)).
.TP
\fIptrace\fP
This is a parent process tracing its child.
.TP
\fIvfork\fP
This is a vforking parent process waiting for its child to relinquish
memory resources (see \fIvfork\fP(2)).
.TP
\fIfloppy\fP
.br
.ns
.TP
\fIprintr\fP
.br
.ns
.TP
\fIvarian\fP
.br
.ns
.TP
\fIr??buf\fP
Waiting for the specified device to complete an I/O operation.
.RE
.TP 8
\fIFl\fP
Flags associated with the current state of the process.
These flags may be any of the following -
.RS 8
.TP 16
\fIU\fP
The process is a UNIX system process.
.TP
\fIT\fP
The process is being traced or debugged.
.TP
\fIV\fP
The process is a child currently being vforked (see \fIvfork\fP(2)).
.TP
\fII\fP
The process is undergoing physical I/O.
.TP
\fIA\fP
The system has detected, or the user has warned of
anomalous paging behaviour (see \fIvadvise\fP(2)).
.RE
.TP 8
\fINice\fP
The "niceness" of the process (see \fInice\fP(2)).
.TP
\fIVirtual\fP
The virtual memory size of the process in kilobytes.
The first figure indicates the sum of the data and stack segments,
the second figure that of the text segment.
.TP
\fIResident\fP
The resident memory size of the process in kilobytes, representing
the real memory devoted to the process.
.TP
\fI%M\fP
The percentage of available real memory allocated to this process.
.TP
\fITime\fP
The total CPU time accumulated by this process.
(This is the sum of the system plus user times, unless the \fB-q\fP
flag is specified in which case only the user time is listed.)
.TP
\fIChild\fP
The total CPU time accumulated by the process' children.
(This is the sum of the system plus user times, unless the \fB-q\fP
flag is specified.)
.TP
\fI%C\fP
The percentage of available CPU time devoted to the process.
This figure is a decaying average, computed over the past second.
.PP
The following fields are listed when \fIsps\fP is invoked with the
\fB-d\fP option -
.TP 8
\fIFiles\fP
The number of open files for this process.
.TP
\fIPageFaults\fP
The number of major and minor page faults incurred by the process.
.TP
\fISwap\fP
The number of swaps incurred by the process.
.TP
\fIBlockI/O\fP
The number of block read or write operations performed
on behalf of the process.
.TP
\fIKbytesecs\fP
The integral of real memory usage over time.
Thus, if a process uses 60 kilobytes of real memory for 3 seconds,
this figure is incremented by 180.
.PP
The following fields are listed when \fIsps\fP is invoked with the
\fB-y\fP option -
.TP 8
\fIDev\fP
The major and minor device numbers of the terminal.
.TP
\fIAddr\fP
The virtual address of the associated \fBstruct tty\fP in /dev/kmem.
.TP
\fIRawq\fP
.br
.ns
.TP
\fICanq\fP
.br
.ns
.TP
\fIOutq\fP
The number of characters in the terminal I/O queues.
These refer to the raw input queue, the canonical input queue
and the output queue.
.TP
\fIPgrp\fP
The process group associated with the terminal.
.PP
After listing the requested output, \fIsps\fP prints a summary line.
This indicates the number and total virtual memory size of all processes,
the number and total virtual size of busy processes,
the number and real memory size of loaded processes
and the number and real size of swapped processes.
.SH DIAGNOSTICS
\fISps\fP reports a self-explanatory message if it is given an
invalid argument list.
The program also complains if it cannot find necessary system information.
.PP
At initialisation, \fIsps\fP complains if it cannot find the addresses of
requisite system structures in the kernel symbol file.
This is usually the case because the system is rarely configured to support
all known devices.
\fISps\fP also complains if more than one user shares the same user-id
in the password file (/etc/passwd).
.SH EXAMPLES
\fBsps vb\fP
.PP
\fISps\fP describes all busy processes in a verbose manner.
.PP
\fBsps dtg 9 h1 co\fP
.PP
\fISps\fP lists processes associated with terminals 9, h1 and the console.
The output reflects the disc activity caused by these processes.
The process group of each process is also included in the output.
.PP
\fBsps weu robert graham -r 2\fP
.PP
\fISps\fP reports processes belonging to the specified users.
It lists the environment as well as all the command arguments in a wide format.
The output is produced indefinitely, with a delay of two seconds between
each listing.
.PP
\fBsps is /vmunix.new\fP
.PP
\fISps\fP is initialised. It reads its symbol information from the
specified file.
.SH FILES
.ta 2.5i
.nf
/dev/console	Console
/dev/tty??	Terminal and pty devices
/dev/kmem	Kernel virtual memory
/dev/mem	Physical memory
/dev/drum	Paging and swap device
/etc/passwd	Password file
/etc/spsinfo	Information file
/vmunix	Symbol file of /dev/kmem addresses
/etc/termcap	To determine the output terminal width
.fi
.ta
.SH SEE ALSO
\fIiostat\fP(1), \fIkill\fP(1), \fIps\fP(1),
\fIvmstat\fP(1), \fIexec\fP(2),
\fIflock\fP(2), \fInice\fP(2), \fIpause\fP(2), \fIselect\fP(2), \fIsetuid\fP(2),
\fIsigsys\fP(2), \fIsigvec\fP(2), \fIvadvise\fP(2), \fIvfork\fP(2),
\fIvlimit\fP(2), \fIvtimes\fP(2), \fIwait\fP(2),
\fIpty\fP(4),\fItty\fP(4), \fIpstat\fP(8).
.SH AUTHORS
Several. In particular, J. E. Kulp and J. Robert Ward.
.SH BUGS
Because the system is continually changing, the information reported by
\fIsps\fP is only an approximation to reality.
\fISps\fP renices itself to -20 in an attempt to run as
fast as possible.
.PP
\fISps\fP recognises the sizes and addresses of internal kernel
tables whenever it is invoked. However, it must be recompiled
if major modifications are made to the kernel.
.PP
\fISps\fP does not list all the detailed information shown by \fIps\fP(1).
Nor are all the options supported by \fIps\fP(1) available from \fIsps\fP.
.PP
\fISps\fP does not understand all the possible
reasons why a process may be sleeping.
.PP
The number of options to \fIsps\fP is ridiculous.
---END-OF-sps.ms---