			   UUSTAT UTILITY version 1.0
			       FOR COHERENT 3.2.1
				 by Romel Aranas
				 Copyright 1992
					

	File: README

	DISCLAIMER:
	This software is provided as is and without warranty of any kind,
	even without the implied warranty of merchantability or fitness
	for a particular purpose.  Use this software at your own risk.

	CREDITS:
	This software is Copyright 1992 by Romel Aranas.

	Parts of this program depend on directory i/o routines (in the file
	dir-io.c) kindly provided by Herb Alcorn and are included with his
	permission.  The routines were taken directly from his PCLIST
	program and are used without modification, except for the inclusion
	of some comments I added to the beginning of the source file.

	You may use, copy, redistribute or modify this software without
	any fee as long as you don't try to sell it or distribute it or
	any part of it as your own.  If you distribute or copy this
	program, all the original files MUST be included as part of the
	distribution.

	NOTE:
	This program was designed to run as setuid root or setuid uucp.
	I know some people are paranoid about running an unknown program
	as setuid anything (I'm one of those people), but to be able to
	do it's job, this utility has to have access to some privileged
	files (specifically, the L.sys file--see the section on HOW IT 
	WORKS).  I am currently running it as setuid uucp as I don't like 
	to run anything as root unless it MUST be root.


	GENERAL
	I wrote this utility for two reasons: 1)  to learn more about
	programming in the UNIX environment and 2) the more I used
	Coherent, the more I found myself having type in the full path
	names of the uucp spool directories or to su in order to delete
	jobs.  This utility is my answer to these needs.  It displays a
	list of pending jobs, along with the job ids and the related
	files and remote commands, if any.  The user may also rejuvenate
	or kill a job, assuming he/she has permission to do so and if a
	job is killed by the uucp administrator or root, mail is sent to
	the owner.  I've included a man page that is basically modeled
	after a System V man page.  This utility is not as complete as
	compared to a corresponding command one would find on System V
	(such as performance data, length of time in the queue, etc.) but
	I didn't need such output.

	This is my first attempt at writing a program for UNIX and I must
	admit that I could have done a better job of designing the
	program, especially in the area of maintainability.  When I have
	to go in and start making major changes, I will find out just how
	maintainable it really is (or isn't).  Speed and size were not
	major concerns during development.  However, it seems to perform
	well enough but I am running Coherent on a 486.  I've tried to
	keep the program as modular as possible, with just about one
	function per file.  If there is a problem with performance on the
	older CPUs and there is enough interest, I will try and improve
	it, although the program is small and straight-forward enough (I
	hope!!!) for most people to be able to figure out its structure
	in order to modify it.

	I designed this program around the man pages of a UNIX System V
	machine and a Sun SPARC SLC (I think).  If I missed any features
	that you think are important, please let me know.  If you find
	any bugs or have any comments or suggestions, please let me know.
	My email address is raa@chinet.chi.il.us or romel@vger.chi.il.us.


	BUILDING UUSTAT
	The header file uustat.h assumes the following:
	     The uucp spool directories are in /usr/spool/uucp
	     The log files are in /usr/spool/uucp/.Log/uucico
	     The L.Sys file is in /usr/lib/uucp
	     The mail program is /etc/mail
	If your setup is different, change the appropriate #define before
	compiling:
		spool directories: SPOOLDIR
		logfiles: LOGDIR
		L.sys file: SYSTEMS
		mail program: MAILCMD

	To build uustat, simple issue the make command without any
	options.  You should not see any warnings or errors (at least 
	for version 3.2.1, which is what I wrote it on).


	INSTALLING UUSTAT
	After uustat is built, you should put it in a public directory
	and set it's owner to uucp or root (uucp is recommended).  Then
	change the file permissions to 6111.  This will allow anyone to
	execute it, and it will run setuid.  
	
	You can have the makefile do this or do it by hand.  If you use
	the makefile, make sure you look it over carefully before using
	it to make sure it won't screw up anything in your system.  Login
	as root or give the 'su' command (this is required to give uustat
	setuid permission).  Then modify the BINDIR variable (which 
	specifies the directory to install uustat) in the makefile to 
	point to the directory in which you want to install uustat and 
	type 'make install'.


	HOW IT WORKS
	To build a list of jobs that are waiting for uucp, uustat builds
	a list of machines that are known to uucp by querying the L.sys
	file (this is why it must be run as uucp or root.  uucp is
	acceptable because the L.sys file is owned by uucp (Well, at
	least it is on my system)).

	uustat then looks in the uucp spool directory for each machine
	for any "control" files that signify uucp jobs (the spool
	directory is built by appending the remote machine's name to
	'/usr/spool/uucp'.  Therefore, the spool directory for a machine
	named 'vger' is '/usr/spool/uucp/vger' and the control files are
	'/usr/spool/uucp/vger/C.*').  These "control" files have names
	that always begin with 'C." and are followed by the jobid.
	uustat then goes through each one of these "control" files,
	reading relevant information and displaying it to the user.

	Many times, there are other files that are associated with a
	particular job.  These files may be data files from a uucp
	command or a message from a mail command.  These are also
	described in the "control" file and when uustat finds any
	references to other files, it will obtain information from those
	files, if appropriate.

	If the -q option is given, uustat just counts the number of
	control files for each system, calculates the age of the oldest control
	file, and obtains the date and status message from log file for each
	remote system.

	When killing or rejuvinating a job, uustat expects a jobid on the command
	line and immediately looks for this job in the uucp spool directories.
	Since the system name is part of the jobid, uustat can determine which
	directory the file resides in.  With the exception of uucp and root,
	only the owner of a file can kill or rejuvinate a job.  When uupc or
	root kill or rejuvinate a job, mail is sent to the owner informing
	him/her of the action.

	Options
	If a system name is given on the command line, then uustat only
	looks in the spool directory for that machine, not bothering to
	build the list of known remote machines.

	If a user name is included on the command line, operation will
	proceed as normal but only jobs that were created by the given
	user are displayed.  If no user name appears on the command line,
	then uustat displays only the jobs issued by the user who issued
	the uustat command.

	If the kill or rejuvinate option is given, then uustat builds a
	pathname to the control file (by appending the given jobid to
	'/usr/spool/uucp/machine/C.').  uustat then checks that the user
	has permission to perform this action and if so, performs it and
	displays the result.  Only the owner of a job can issue a kill or
	rejuvinate command, except for root or uucp.  If a job is kill by
	root or uucp and is not owned by either, mail is sent to the
	owner.

	The -q option provides information on the status of each remote
	machine, listing each known system, the number of jobs in the queue,
	and its current status (taken from the last line in the log file
	of that system).
	
	In addition, if any control files are older than
	one day, the age of the oldest file is shown in parenthesis after
	the number of control files found.  The way the age is calculated is
	as follows:
		The mtime of the file is subtracted from the current time
		The result is divided by the number of seconds in one day
		and truncated (cast to int).
		
	Therefore, a file must be at least 24 hours old before it is considered
	by uustat to be another day older.  This is in contrast to taking midnight
	as the point in which a file becomes another day older, whether or
	not it is older than 24 hours.


	Please remember, this is my first attempt at writing anything for
	Coherent so if you have any questions, problems or suggestions on
	how uustat should work or how I should have written it, please let
	me know.

	Hope you find it useful!
	

	Romel Aranas
	raa@chinet.chi.il.us	(either one will do)
	romel@vger.chi.il.us
