-----------> Documentation for BOBGUNIX (UNIX Version 6.8+) <----------------

	Bobgunix works almost exactly like version 6.7 unix; most of the
changes to it can only be accessed through new system calls. The one
major exception is that writing 0 characters on a pipe now has very
special meaning--one's code should be checked to see that it disallow
all writes of 0 characters unless really desired.


			1. New System Calls

		a. numb = gprocs(buf);  [assembly code: buf in r0]
		   struct proc buf[NPROCS];

	The gprocs system call copies out the current monitor process
table into the user-supplied buffer. It returns the number of slots in
the table (NPROCS in /usr/sys/param.h). The only possible error is if
buf is a bad address.

		b. sfork();

	The sfork system call is similar to fork() with this exception:
the child process and all of its descendants are inhibited from receiving
a <DEL> or <CTRL/FS> signal generated from the terminal. They will,
however, receive direct signals (e.g. kill(pid,2)) and signals from a
kill(0,sig).
	Using this system call, a program can catch and interpret
the teletype quit and interrupt signals without fear of disturbing
any backround jobs that its created.

		c. spipe(fd,pipedscs);  [assembly code: fd in r1]
		   int fd, pipedscs[2];

	The spipe system call is similar to pipe(pipedscs) except that,
if an stty/gtty is legal on the supplied file descriptor (fd), that
file descriptor is associated with the pipe such that all stty/gtty
calls on either end of the pipe are the equivilent of the same stty/gtty
call on the supplied file descriptor. In other words, after doing an
spipe(0,pipedscs), any stty's on that pipe (even if done by a child
process) are the equivilent of an stty on fd 0 of the process that created
the pipe. Note: fd must be a character device or another pipe created
by an spipe or it will be ignored.
	This feature is useful for filters that feed a main program but
don't use teletype input themselves, proto being an excellent example.


			2. New Feature: EOFs on Pipes

	The pipe I/O routines have been modified to allow single end-of-files
to be transmitted. It works as follows: a write of 0 characters
guarantees that, after the real data is read, the next read on the pipe will
return with 0 characters. Further writes may be done after writing an
EOF, but they will be suspended until the EOF actually gets read.


			3. Changes and Additions to /lib/libc.a

		a. Added: gproc.o, spipe.o, sfork.o

	C-interface routines for the above system calls.

		b. Added: skill.o

	This subroutine is called as skill(pid,sig) exactly like the
kill system call. It sends the specified signal to the specified
process and all its (still connected) descendants, youngest to oldest.
Descendants whose parents have died are not caught as they are now
adopted by the init process.
	Skill returns 0 for success and 1 if at least one of the kills
failed (a process not found or not owned by the killer). Given the
gprocs system call, skill will never return -1 as it used to if it
couldn't read the process table.

		c. To be added: alive.o

	The alive subroutine has two calling formats: alive(pid) and
alive(0). In the former case, alive returns +1 if the specified process
is still running, -1 if it has died, and 0 if it is not found. In the
latter case, alive returns -1 if at least 1 child has died and is
waiting to be cleaned up, otherwise the number of living children.
Note what alive(0) implies about doing a wait: -1 implies the wait
will immediately return with a dead child, 0 implies the wait will
immediately return with a no-children error, and >0 implies the process
doing the wait will hang.

		d. Corrected: setex.o, pipe.o

	Setexit/reset has been fixed so that it properly saves and
restores the registers and does not mess up the stack causing core
dumps.
	The pipe C-interface routine has been corrected so that it
doesn't smash r2.


			3. Changes in other software

	Proto, opser and master have all been changed to reflect the
new features. Details will be published separately. The next version
of RITA will also reflect the changes. The network is also being
reviewed for possible modification.


			4. Implementation (technical details)

		a. gprocs

	Pretty trivial--the gprocs routine just copies out the
proc table using suword.

		b. spipe

	The file structure has been expanded by one word. When FTTY is
set in f_flag, this additional word (f_tty) contains a device number
for a character device. Thus, sgtty need only check for the FTTY flag
and, if on, use the given device number rather than going to the file's
inode. The spipe call simply uses the pipe code and then checks to
see if the given file descriptor either refers to a character device
(checks inode) or has an FTTY bit of its own. If either case is true,
the indicated device number and FTTY bit is copied into both of the
file descriptors just created by the pipe call. Note: the flag and
extra word really belong in the inode structure, not in the file one, but
the former is too sensitive to change.

		c. sfork

	Sfork uses the fork code, except that it sets the SNOSIG bit
in the p_flag part of the child's proc table entry. This SNOSIG bit is
copied across forks (and thus to all descendants). Finally, the
signal subroutine, when scanning the proc table for all processes
with a given controlling teletype, simply bypasses any processes
with the SNOSIG bit set.


Note: these calls use trap numbers 61, 60, and 62 respectively; empty
uses 63. There is a minor bug in Unix that assumes trap 63 is never
used; I plan to fix it.


		d. EOFs on pipes

	A bit (IEOFP) was added to the i_flag part of an inode. When set,
it indicates that an EOF is waiting to be read on the inode. When
writep is called to write on a pipe, the count is checked. If 0, and
if the IEOFP is not set, the code sets the bit, wakes up any readers,
and returns. If an EOF is already pending, the writer goes to sleep
on the inode address+6. When reading, if the pipe buffer is empty and
IEOFP is set, the reader returns with 0 charcters, clears the IEOFP
bit, and wakes up any writers so that further writes are allowed.
All changes were made in pipe.c except that closef was also modified
to wake up the inode+6 address. Note: the only reason to have a
write-EOF wait on a different address than a normal write is so that
it need be awakened only when the pipe empties (including the pending
EOF), and not just when it is read.
