Initial commit

5 files changed, 401 insertions, 0 deletions

diff --git a/sys/etc/doc/Proc.hlp b/sys/etc/doc/Proc.hlp
new file mode 100644
index 00000000..023a5316
--- /dev/null
+++ b/sys/etc/doc/Proc.hlp
@@ -0,0 +1,22 @@
+			        Process Control
+
+Connected Subprocesses
+
+	     pid = propen (process, in, out)
+	   stat = prclose (pid)
+	 stat = prgetline (in, lbuf)
+		  prredir (pid, stream, new_fd)
+		 prsignal (pid, signal)
+		 prupdate (message)
+
+	    pid = propcpr (process, in, out)
+	   stat = prclcpr (pid)
+
+
+
+Detached Processes
+
+	    job = propdpr (process, bkgfile)
+	   stat = prcldpr (job)
+	     y/n = prdone (job)
+		   prkill (job)
diff --git a/sys/etc/doc/error.hlp b/sys/etc/doc/error.hlp
new file mode 100644
index 00000000..7776093f
--- /dev/null
+++ b/sys/etc/doc/error.hlp
@@ -0,0 +1,51 @@
+
+.help error, fatal, errchk, erract, iferr 2 "Error Handling Strategy"
+.sh
+ERROR HANDLING
+
+    A recoverable error condition is asserted with ERROR.  An irrecoverable
+error condition is asserted with FATAL.  Error recovery is implemented
+using the IFERR and IFNOERR statements in the preprocessor language.
+ERRACT may be called in an IFERR statement to cause a warning to be issued,
+or to cause a particular error action to be taken.  ERRCODE returns either
+OK or the integer code of the posted error.
+
+Language support includes the IFERR and IFNOERR statements and the ERRCHK
+declaration.  The IFERR statement is grammatically equivalent to the IF
+statement.  Note that the condition to be tested in an IFERR statement may
+be a procedure call or assignment statement, while the IF statement tests
+a boolean expression.
+
+
+.nf
+	errchk	proc1, proc2, ...		# errchk declaration
+
+	iferr (procedure call or assignment statement)
+	    <error_action_statement>
+
+	iferr {
+	    <any statements, including IFERR>
+	} then
+	    <error_action_statement>
+
+
+Library procedures (ERROR and FATAL cause a RETURN):
+
+	  error (errcode, error_message)
+	  fatal (errcode, error_message)
+	 erract (severity)
+  val = errcode ()
+
+
+ERRACT severity codes (<error.h>):
+
+	EA_WARN			# issue a warning message
+	EA_ERROR		# assert recoverable error
+	EA_FATAL		# assert fatal error
+.fi
+
+
+An arithmetic exception (X_ARITH) will be trapped by an IFERR statement,
+provided the posted handler(s) return without causing error restart.
+X_INT and X_ACV may only be caught by posting an exception handler with
+XWHEN.
diff --git a/sys/etc/doc/etc.hd b/sys/etc/doc/etc.hd
new file mode 100644
index 00000000..759ba4e2
--- /dev/null
+++ b/sys/etc/doc/etc.hd
@@ -0,0 +1,29 @@
+# Help directory for the ETC (miscellaneous system stuff) package.
+
+$etc	= "sys$etc/"
+
+brktime		hlp = brktime.hlp,		src = etc$brktime.x
+btoi		hlp = btoi.hlp,			src = etc$btoi.x
+clktime		hlp = clktime.hlp,		src = etc$clktime.x
+cnvdate		hlp = cnvdate.hlp,		src = etc$cnvdate.x
+cnvtime		hlp = cnvtime.hlp,		src = etc$cnvtime.x
+cputime		hlp = cputime.hlp,		src = etc$cputime.x
+envgetb		hlp = envget.hlp,		src = etc$envgetb.x
+envgeti		hlp = envget.hlp,		src = etc$envgeti.x
+envgets		hlp = envget.hlp,		src = etc$envgets.x
+erract		hlp = erract.hlp,		src = etc$erract.x
+errcode		hlp = errcode.hlp,		src = etc$errcode.x
+error		hlp = error.hlp,		src = etc$error.x
+getuid		hlp = getuid.hlp,		src = etc$getuid.x
+itob		hlp = itob.hlp,			src = etc$itob.x
+lpopen		hlp = lpopen.hlp,		src = etc$lpopen.x
+main		hlp = main.hlp,			src = etc$main.x
+onerror		hlp = onerror.hlp,		src = etc$onerror.x
+onexit		hlp = onexit.hlp,		src = etc$onexit.x
+oscmd		hlp = oscmd.hlp,		src = etc$oscmd.x
+qsort		hlp = qsort.hlp,		src = etc$qsort.x
+sys_ptime	hlp = sys_ptime.hlp,		src = etc$sys_ptime.x
+syserr		hlp = syserr.hlp,		src = etc$syserr.x
+tsleep		hlp = tsleep.hlp,		src = etc$tsleep.x
+urand		hlp = urand.hlp,		src = etc$urand.x
+xwhen		hlp = xwhen.hlp,		src = etc$xwhen.x
diff --git a/sys/etc/doc/etc.men b/sys/etc/doc/etc.men
new file mode 100644
index 00000000..5ed6f4ad
--- /dev/null
+++ b/sys/etc/doc/etc.men
@@ -0,0 +1,24 @@
+	brktime - Convert a long integer time into year, month, day, etc.
+	   btoi - Boolean to integer
+	clktime - Get the clock time
+	cnvdate - Convert long integer time to date string (short format)
+	cnvtime - Convert long integer time to time string (long format)
+	cputime - Get the CPU time consumed by the process
+    envget[bis] - Get a boolean, integer, or string valued environment variable
+	 erract - Take an error action for a previously posted error
+	errcode - Get the error code of the posted error
+	  error - Post an error and take an error action
+	 getuid - Get the name of the runtime user of a program
+	   itob - Convert integer to boolean
+	 lpopen - Open the line printer as a file
+	   main - The IRAF Main
+	onerror - Post a procedure to be executed if error recovery occurs
+	 onexit - Post a procedure to be executed upon process shutdown
+	  oscmd - Send a command to the host operating system
+	  qsort - General quick sort for any data structure
+      sys_mtime - Mark the time (for timing programs)
+      sys_ptime - Print the elapsed time since last mark
+	 syserr - Post a system error and take an error action
+	 tsleep - Delay process execution
+	  urand - Uniform random number generator
+	  xwhen - Post an exception handler
diff --git a/sys/etc/doc/psio.doc b/sys/etc/doc/psio.doc
new file mode 100644
index 00000000..d0f34c9a
--- /dev/null
+++ b/sys/etc/doc/psio.doc
@@ -0,0 +1,275 @@
+.help pr_psio
+.nf __________________________________________________________________________
+PR_PSIO -- Pseudofile i/o for a process.  Process an i/o request for the
+specified pseudofile stream of the specified process.  Called either to read
+command input from the CLIN of a process, or to process a read or write
+request to a pseudofile of a process.
+
+
+1. Introduction
+
+    Pseudofile i/o in a multiprocess configuration, e.g., for the graphics
+streams, is quite complex and difficult to explain briefly.  I have tried to
+cover the major points here but warn the reader that it is not going to be easy
+to understand the flow of data and control involved.  The problem is a difficult
+one due to the nature of the IPC protocol and the complexity of the three
+process architecture required when an external graphics kernel is used.  The
+discussion herein is not complete but should as least give the reader some
+idea of what is going on.
+
+
+2. Pseudofile I/O
+
+    While a task is running the CL will be reading command input from the task.
+This read eventually resolves into a call to PR_PSIO on the CLIN for the
+process.  When pseudofile i/o occurs, e.g., the process writes to STDOUT or
+STDERR, an XMIT or XFER directive will be seen in the CLIN input from the
+process.  If we are directed to XMIT to an ordinary file our task is relatively
+easy, i.e., we read the data block from CLIN and write it to the output file.
+A directive to read from the standard input is also easy, i.e., we read from
+the standard input of the parent (assuming i/o is not redirected) and write
+the data block to the CLOUT of the process preceded by a count of the number
+of chars.
+
+
+2.1 I/O to a Graphics Stream
+
+    If we are directed to read or write a graphics stream our task is somewhat
+more difficult.  The standard graphics streams STDGRAPH, STDIMAGE, and STDPLOT
+differ from other pseudofiles in that the streams are both readable and
+writable, provided all data is used up before switching modes.  A graphics
+stream may be connected to a file if output is being spooled, to the builtin
+STDGRAPH kernel if the graphics device is the graphics terminal, or to a
+graphics kernel resident in an external subprocess.
+
+If a graphics stream is redirected to a spool file we merely copy output to
+the file and reading is forbidden.  If output is to an external graphics
+kernel but is unfiltered (no workstation transformation, e.g., for STDPLOT),
+we merely copy data blocks on to the subprocess but the protocol involved
+is nontrivial.  If output is to the builtin STDGRAPH kernel or to an
+external interactive kernel, output must be filtered through GIOTR before
+being written to the local or remote graphics kernel.  Graphics input is
+also possible and is handled similarly but without need to call GIOTR.
+
+Before reading or writing a graphics stream GIO will send a special directive to
+PR_PSIO to connect a kernel to the stream.  This directive is passed to PR_PSIO
+via an XMIT to the special pseudofile PSIOCONTROL.  The data passed in the
+XMIT call will be the GKI control instruction to be executed by PSIO.  There
+are currently three such directives, i.e., OPENWS, SETWCS, and GETWCS.  Each
+such directive is included in the normal metacode stream as well, but by
+writing to a special pseudofile we avoid the need to have PR_PSIO scan each
+metacode stream for control instructions, a fairly expensive operation if a
+lot of data is involved.
+
+
+2.1.1 Graphics Stream Dataflow
+
+    A frame buffer is associated with each graphics stream in the parent
+process.  If graphics output (metacode) is being filtered, each output record
+is appended to the frame buffer and then GIOTR is called to filter the new
+instructions.  GIOTR writes the filtered metacode stream either directly to
+the builtin kernel or to the graphics output pseudofile stream of the parent
+process.
+
+Output to the builtin kernel is easy to understand: GIOTR merely calls the
+kernel to execute the transformed instruction.  If output is to an external
+kernel we unfortunately cannot simply write to the kernel because we require
+that the graphics kernel task be a conventional task callable from either
+the CL or by the graphics system, i.e., by PL_PSIO.  We must buffer the
+transformed output metacode and pass it on to the kernel process only when
+requested to do so by an XFER command from the kernel.
+
+This buffering is done in a somewhat tricky way which makes it look like we
+are writing to a simple file, and which allows us to use conventional READ and
+WRITE calls to access the graphics stream.  GIOTR, if not writing to the
+builtin kernel, will write to one of the three graphics streams of the parent
+process, i.e., to STDGRAPH, STDIMAGE, or STDPLOT.  The graphics stream of the
+parent is logically connected to the same stream in the kernel process.  We
+arrange things such that data may be written or read into the FIO buffer
+associated with the stream, but the buffer will never actually be flushed,
+since this would cause the contents to appear as garbage on the user terminal.
+
+The sequence of events for an XMIT to STDGRAPH with an external kernel is as
+follows:
+
+	
+	The parent process (CL) blocks, waiting for a read on the IPC
+	    channel to the graphics task.
+
+	Graphics task writes to stdgraph.
+	FIO flushes stdgraph buffer through IPC channel.
+
+	PR_PSIO (in the parent) sees XMIT to stdgraph.
+	Parent reads data record from IPC channel, appending the
+	    data record to the frame buffer for the stream.
+
+	PR_PSIO calls GIOTR to process the new metacode.
+	GIOTR writes the transformed metacode instructions to the stdgraph
+	    stream of the parent and returns control to PR_PSIO.
+
+	PR_PSIO rewinds the stdgraph buffer in preparation for a read and
+	    stacks the pending XMIT request and directs its command input
+	    to the IPC of the kernel process.
+
+	The kernel process sends zero or more XMIT or XFER requests to
+	    the parent to read or write pseudofile streams other than
+	    stdgraph.
+	The kernel process sends an XFER request to the parent to read
+	    from stdgraph.
+	The parent reads the data record from the stdgraph FIO buffer
+	    and passes it on to the kernel, completing the XFER request
+	    of the kernel as well as the original XMIT request of the
+	    graphics task.
+
+	The parent process (CL) blocks, waiting for a read on the IPC
+	    channel to the graphics task.
+
+
+The sequence of operations for an XFER request from the graphics task is
+as follows.
+
+	The parent process (CL) blocks, waiting for a read on the IPC
+	    channel to the graphics task.
+
+	The parent receives an XFER request from the graphics task.
+	If there is any data in the stdgraph buffer the parent returns
+	    that to the graphics task, otherwise the PR_PSIO procedure
+	    pushes an XFER request and redirects its input to the
+	    graphics kernel.
+
+	The kernel process sends zero or more XMIT or XFER requests to
+	    the parent to read or write pseudofile streams other than
+	    stdgraph.
+	The kernel process sends an XMIT request to the parent to write
+	    to stdgraph.
+	The parent reads the data block from the IPC channel to the kernel
+	    and writes it to stdgraph, completing the XMIT request.
+
+	The parent pops the XFER request and copies the data in the stdgraph
+	    buffer to the graphics task, completing the original XFER request.
+
+	The parent process (CL) blocks, waiting for a read on the IPC
+	    channel to the graphics task.
+
+
+In summary, the principal data buffers involved in pseudofile i/o to a graphics
+stream are the frame buffer, used by GIOTR to spool the metacode instructions
+for a graphics frame, and the FIO buffer for the graphics stream, used to
+pass data between XMIT/XFER request pairs from cooperating processes at
+opposite ends of a graphics stream.
+
+
+3. Summary
+
+    The actual code required to implement all this is probably easier to
+understand than the English description.  To summarize the justification for
+the complexity of the scheme we have adopted:
+
+    [1] The graphics kernel task is a conventional CL callable task with
+	parameters etc., usable to process metacode from a metafile or from
+	a pipe as well as callable by PR_PSIO.  The conventional IPC protocol
+	is used in the graphics kernel task.  Other tasks may be resident in
+	the same process, saving disk and memory.
+
+    [2] The graphics kernel may read STDIN and write STDOUT and STDERR while
+	processing metacode, allowing access to the graphics terminal via the
+	CL process, output of debugging information during operation, and
+	output of error messages during operation.
+.endhelp ______________________________________________________________________
+
+
+# PR_PSIO -- Process an i/o request for the specified pseudofile stream
+# of the specified process.
+
+procedure pr_psio (pid, active_fd)
+
+pid	process id
+fd	process stream for which i/o is requested
+
+begin
+	in = pr.clin
+	fd = active_fd
+	clear stack
+
+	# Process i/o requests from the subprocess until a request is received
+	# and processed for pseudofile FD.
+
+	repeat {
+	    while (filbuf (in) != EOF) {
+		determine type of request and destfd
+
+		if (xmit request to stream destfd) {
+		    if (graphics filtering enabled) {
+			read data record and append to frame buffer
+			call giotr to filter output to destfd
+		    } else {
+			read data record from process
+			write record to destfd
+		    }
+		    if (destination is a process) {
+			rewind destfd buffer for read
+			push (fd)
+			push (in)
+			push (xmit)
+			fd = destfd
+			in = newpr.clin
+			next
+		    }
+
+		} else if (xfer request from stream destfd) {
+		    if (destfd is a process and buffer is empty) {
+			push (fd)
+			push (in)
+			push (xfer)
+			fd = destfd
+			in = newpr.clin
+			next
+		    } else {
+			read data record from destfd
+			write data record to process
+		    }
+
+		} else if (gio directive) {
+		    if (open workstation)
+			connect a kernel process to a graphics stream
+		    else if (setwcs)
+			save wcs for the stream
+		    else if (getwcs)
+			write wcs data to the process
+
+		} else {
+		    destfd = CLIN
+		    if (fd != CLIN)
+			error: unsolicited command input from the subprocess
+		}
+
+		if (destfd == fd) {
+		    if (stack not empty) {
+			pop (request)
+			pop (in)
+			pop (fd)
+			if (request == xfer) {
+			    read data record from fd
+			    write data record to process owning "in"
+			}
+		    } else
+			break
+		}
+	    }
+	} until (stack is empty)
+end
+
+
+
+File routing:
+
+    Each pseudofile in a subprocess is associated with a stream in the parent
+process.  A subprocess pseudofile may map to a real file or to a parent
+pseudofile.  When a subprocess is connected as a graphics kernel graphics
+i/o will be via any one of the standard graphics streams STDGRAPH etc.,
+with said graphics stream connected to the same stream in the parent.
+The subprocess streams STDIN, STDOUT, and STDERR are by default connected
+to the same streams in the parent, allowing the subprocess to access the
+terminal, output error messages, and so on.  A graphics kernel will be able
+to access the standard i/o streams even while connected as a subprocess
+to filter GKI metacode.