Research V6 development

Work on file usr/doc/man/man7/salloc.7
Work on file usr/doc/man/man7/cr.7
Work on file usr/doc/man/man7/ms.7

Co-Authored-By: Dennis Ritchie <dmr@research.uucp>
Synthesized-from: v6

diff --git a/usr/doc/man/man7/cr.7 b/usr/doc/man/man7/cr.7
new file mode 100644 (file)
index 0000000..83942a7
--- /dev/null
+++ b/usr/doc/man/man7/cr.7
@@ -0,0 +1,200 @@
+.th CR VII 1/4/75
+.sh NAME
+crfork, crexit, crread, crwrite, crexch, crprior \*- coroutine scheme
+.sh SYNOPSIS
+.nf
+.ft B
+int crfork( \fR[\fB stack, nwords \fR]\fB )
+int stack[];
+int nwords;
+.s3
+crexit()
+.s3
+int crread(connector, buffer, nbytes)
+int *connector[2];
+char *buffer;
+int nbytes;
+.s3
+crwrite(connector, buffer, nbytes)
+int *connector[2];
+char *buffer;
+int nbytes;
+.s3
+crexch(conn1, conn2, i)
+int *conn1[2], *conn2[2];
+int i;
+.s3
+#define logical char *
+crprior(p)
+logical p;
+.fi
+.ft R
+.sh DESCRIPTION
+These functions are named by analogy to
+.it "fork, exit, read, write"
+(II).
+They establish and synchronize `coroutines', which
+behave in many respects like a set of processes working
+in the same address space.
+The functions live in
+.it /usr/lib/cr.a.
+.s3
+Coroutines are placed
+on queues to indicate their state of readiness.
+One coroutine is always distinguished as `running'.
+Coroutines that are runnable but not running
+are registered on a `ready queue'.
+The head member of the ready queue is started whenever no other
+coroutine is specifically caused to be running.
+.s3
+Each connector heads two
+queues: 
+.it Connector[0]
+is the queue of unsatisfied 
+.it crreads
+outstanding on the connector.
+.it Connector[1]
+is the queue of
+.it crwrites.
+All queues must start empty,
+.it i.e.
+with heads set to zero.
+.s3
+.it Crfork
+is normally called with no arguments.
+It
+places the running coroutine at the head of
+the ready queue, creates a new coroutine, and starts the new 
+one running.
+.it Crfork
+returns immediately in the new coroutine with value 0,
+and upon restarting of the old
+coroutine with value 1.
+.s3
+.it Crexit
+stops the running coroutine and does not place it in any queue.
+.s3
+.it Crread
+copies characters from the
+.it buffer
+of the 
+.it crwrite
+at the head of the 
+.it connector's
+write queue to the 
+.it buffer
+of
+.it crread.
+If the write queue is empty, copying is delayed and the running
+coroutine is placed on the read queue.
+The number of characters copied is the minimum of
+.it nbytes
+and the number of characters remaining in the write
+.it buffer,
+and is returned as the value of
+.it crread.
+After copying, the location of the write
+.it buffer
+and the corresponding
+.it nbytes
+are updated appropriately.
+If zero characters remain, the coroutine of the
+.it crwrite
+is moved to the head of the ready queue.
+If the write queue remains nonempty,
+the head member of the read queue is moved to
+the head of the ready queue.
+.s3
+.it Crwrite
+queues the running coroutine on the
+.it connector's
+write queue,
+and records the fact that
+.it nbytes
+(zero or more)
+characters in the string
+.it buffer
+are available to 
+.it crreads.
+If the read queue is not empty,
+its head member is started running.
+.s3
+.it Crexch
+exchanges the read queues of connectors
+.it conn1
+and
+.it conn2
+if
+\fIi\fR=0; and it exchanges the write queues if
+\fIi\fR=1.
+If a nonempty read queue that had been paired with an empty write queue
+becomes paired with a nonempty write queue,
+.it crexch
+moves
+the head member of that read queue to the head
+of the ready queue.
+.s3
+.it Crprior
+sets a priority on the running coroutine to 
+control the queuing of
+.it crreads
+and
+.it crwrites.
+When queued, the running coroutine will take its place before
+coroutines whose priorities exceed
+its own priority and after others.
+Priorities are compared as logical,
+.it i.e.
+unsigned,
+quantities.
+Initially each coroutine's priority is set as large as possible,
+so default queuing is
+.nh
+FIFO.
+.hy
+.s3
+.bd "Storage allocation."
+The old and new coroutine share the same activation record
+in the function that invoked
+.it crfork,
+so only one may return from the invoking function,
+and then only when the other has completed execution in that function.
+.s3
+The activation record for each function
+execution is dynamically allocated rather than stacked;
+a factor of 3 in running time overhead
+can result if function calls are very frequent.
+The overhead may be overcome by
+providing a separate stack for each coroutine and dispensing with
+dynamic allocation.
+The base (lowest) address and size of the
+new coroutine's stack are supplied to
+.it crfork
+as optional arguments
+.it stack
+and
+.it nwords.
+Stacked allocation and dynamic allocation cannot be mixed
+in one run.
+For stacked operation, obtain the coroutine functions from
+.it /usr/lib/scr.a
+instead of
+.it /usr/lib/cr.a.
+.sh FILES
+/usr/lib/cr.a
+.br
+/usr/lib/scr.a
+.sh DIAGNOSTICS
+`rsave doesn't work' \*- an old C compilation
+has called `rsave'.
+It must be recompiled to work
+with the coroutine scheme.
+.sh BUGS
+Under /usr/lib/cr.a
+each function has just 12 words of anonymous
+stack for hard expressions and arguments
+of further calls, regardless of actual need.
+There is no checking for stack overflow.
+.br
+Under /usr/lib/scr.a
+stack overflow checking is not rigorous.

diff --git a/usr/doc/man/man7/ms.7 b/usr/doc/man/man7/ms.7
new file mode 100644 (file)
index 0000000..47f24c3
--- /dev/null
+++ b/usr/doc/man/man7/ms.7
@@ -0,0 +1,248 @@
+.hc %
+.th MS VII 11/6/74
+.sh NAME
+ms \*- macros for formatting manuscripts
+.sh SYNOPSIS
+.bd "nroff \*-ms"
+[ options ]
+file ... 
+.br
+.bd "troff \*-ms"
+[ options ]
+file ... 
+.sh DESCRIPTION
+This package of 
+.it nroff
+and
+.it troff
+macro definitions provides a canned formatting
+.li
+facility for tech%nical papers.
+When producing 2-column output on a terminal, its
+output should be filtered through
+.it col
+(I).
+.s3
+The package supports three different formats:
+BTL technical memorandum with cover sheet,
+released paper with cover sheet,
+and an abbreviated `debugging' form without
+cover sheet.
+.s3
+The macro requests are defined in the attached
+Request Reference.
+Many
+.it nroff
+and
+.it troff
+requests are unsafe in conjunction with
+this package, however the requests listed below may be used with
+impunity after the first .PP.
+.s3
+.lp +8 0
+.ta 5n
+.nf
+.li
+.bp    begin new page
+.li
+.br    break output line here
+.li
+.sp n  insert n spacing lines
+.li
+.ls n  (line spacing) n=1 single, n=2 double space
+.li
+.na    no alignment of right margin
+.fi
+.i0
+.s3
+Output of the
+.it eqn,
+.it neqn
+and
+.it tbl
+(I) preprocessors
+for equations and tables is acceptable as input.
+.sh FILES
+/usr/lib/tmac.s
+.sh "SEE ALSO"
+eqn (I), nroff (I), troff (I), tbl (VI)
+.sh BUGS
+.bp
+.in0
+.tr &.
+.in0
+.ce
+REQUEST REFERENCE
+.if t .ta .75i 1.5i 2i
+.if n .ta 10 18 24
+.if t .in 2i
+.if n .in 23
+.if n .na
+.s3
+.ti0
+Request        Initial Cause
+.ti0
+Form   Value   Break   Explanation
+.ps 9
+.vs 11p
+.s3
+.ti0
+.li
+.1C    yes     yes     One column format on a new page.
+.ti0
+.li
+.2C    no      yes     Two column format.
+.ti0
+.li
+.AB    no      yes     Begin abstract.
+.ti0
+.li
+.AE    -       yes     End abstract.
+.ti0
+.li
+.AI    no      yes     Author's institution follows.
+Suppressed in TM.
+.ti0
+.li
+.AU \fIx y\fR  no      yes     Author's name follows.
+\fIx\fR is location and \fIy\fR is
+extension, ignored except in TM.
+.ti0
+.li
+.B     no      no      Boldface text follows.
+.ti0
+.li
+.CS \fIx...\fR -       yes     Cover sheet info if
+TM format, suppressed otherwise.
+Arguments are number of text pages,
+other pages, total pages, figures, tables, references.
+.ti0
+.li
+.DA \fIx\fR    nroff   no      `Date line' at bottom of page
+is \fIx\fR.
+Default is today.
+.ti0
+.li
+.DE    -       yes     End displayed text.
+Implies .KE.
+.ti0
+.li
+.DS \fIx\fR    no      yes     Start of displayed text,
+to appear verbatim line-by-line.
+\fIx\fR=I for indented display (default),
+\fIx\fR=L for left-justified on the page,
+\fIx\fR=C for centered.
+Implies .KS.
+.ti0
+.li
+.EN    -       yes     Space after equation
+produced by
+.it eqn
+or
+.it neqn.
+.ti0
+.li
+.EQ \fIx\fR    -       yes     Space before
+equation.
+Equation number is \fIx\fR.
+.ti0
+.li
+.FE    -       yes     End footnote.
+.ti0
+.li
+.FS    no      no      Start footnote.
+The note will be moved to the bottom of the page.
+.ti0
+.li
+.HO    -       no      `Bell Laboratories, Holmdel,
+New Jersey 07733'.
+.ti0
+.li
+.I     no      no      Italic text follows.
+.ti0
+.li
+.IP \fIx y\fR  no      yes     Start indented paragraph,
+with hanging tag \fIx\fR.
+Indentation is \fIy\fR ens (default 5).
+.ti0
+.li
+.KE    -       yes     End keep.
+Put kept text on next page if not enough room.
+.ti0
+.li
+.KF    no      yes     Start floating keep.
+If the kept text must be moved to the next page,
+float later text back to this page.
+.ti0
+.li
+.KS    no      yes     Start keeping following text.
+.ti0
+.li
+.LG    no      no      Make letters larger.
+.ti0
+.li
+.LP    yes     yes     Start left-blocked paragraph.
+.ti0
+.li
+.MH    -       no      `Bell Laboratories, Murray Hill,
+New Jersey 07974'.
+.ti0
+.li
+.ND    troff   no      No date line at bottom of page.
+.ti0
+.li
+.NH \fIn\fR    -       yes     Same as .SH, with section
+number supplied automatically.
+Numbers are multilevel, like 1.2.3,
+where \fIn\fR tells what level is wanted (default is 1).
+.ti0
+.li
+.NL    yes     no      Make letters normal size.
+.ti0
+.li
+.OK    -       yes     `Other keywords' for TM cover
+sheet follow.
+.ti0
+.li
+.PP    no      yes     Begin paragraph.
+First line indented.
+.ti0
+.li
+.R     yes     no      Roman text follows.
+.ti0
+.li
+.RE    -       yes     End relative indent level.
+.ti0
+.li
+.RP    no      -       Cover sheet and first page for released
+paper.
+Must precede other requests.
+.ti0
+.li
+.RS    -       yes     Start level of relative indentation.
+Following .IP's measured from current indentation.
+.ti0
+.li
+.SG \fIx\fR    no      yes     Insert signature(s) of author(s),
+ignored except in TM.
+\fIx\fR is the reference line (initials of author and typist).
+.ti0
+.li
+.SH    -       yes     Section head follows,
+font automatically bold.
+.ti0
+.li
+.SM    no      no      Make letters smaller.
+.ti0
+.li
+.TL    no      yes     Title follows.
+.ti0
+.li
+.TM \fIx y z\fR        no      -       BTL TM cover sheet and first page,
+\fIx\fR=TM number, \fIy\fR=(quoted list of) case number(s),
+\fIz\fR=file number.
+Must precede other requests.
+.ti0
+.li
+.WH    -       no      `Bell Laboratories, Whippany,
+New Jersey 07981'.

diff --git a/usr/doc/man/man7/salloc.7 b/usr/doc/man/man7/salloc.7
new file mode 100644 (file)
index 0000000..4c71d3a
--- /dev/null
+++ b/usr/doc/man/man7/salloc.7
@@ -0,0 +1,185 @@
+.th SALLOC VII 6/15/72
+.sh NAME
+salloc \*- string allocation and manipulation
+.sh SYNOPSIS
+.nf
+(get size in r0)
+.bd "jsr       pc,allocate"
+(header address in r1)
+.s3
+(get source header address in r0,
+destination header address in r1)
+.bd "jsr       pc,copy"
+.s3
+.bd "jsr       pc,wc"
+.s3
+(all following routines assume r1 contains header address)
+.s3
+.bd "jsr       pc,release"
+.s3
+(get character in r0)
+.bd "jsr       pc,putchar"
+.s3
+.bd "jsr       pc,lookchar"
+(character in r0)
+.s3
+.bd "jsr       pc,getchar"
+(character in r0)
+.s3
+(get character in r0)
+.bd "jsr       pc,alterchar"
+.s3
+(get position in r0)
+.bd "jsr       pc,seekchar"
+.s3
+.bd "jsr       pc,backspace"
+(character in r0)
+.s3
+(get word in r0)
+.bd "jsr       pc,putword"
+.s3
+.bd "jsr       pc,lookword"
+(word in r0)
+.s3
+.bd "jsr       pc,getword"
+(word in r0)
+.s3
+(get word in r0)
+.bd "jsr       pc,alterword"
+.s3
+.bd "jsr       pc,backword"
+(word in r0)
+.s3
+.bd "jsr       pc,length"
+(length in r0)
+.s3
+.bd "jsr       pc,position"
+(position in r0)
+.s3
+.bd "jsr       pc,rewind"
+.s3
+.bd "jsr       pc,create"
+.s3
+.bd "jsr       pc,fsfile"
+.s3
+.bd "jsr       pc,zero"
+.fi
+.sh DESCRIPTION
+This package is a complete set of routines
+for dealing with almost arbitrary
+length strings of words and bytes.
+It lives in
+.it /lib/libs.a.
+The strings are stored on a disk file, so the sum of
+their lengths can be considerably larger than
+the available core.
+A small buffer cache makes for reasonable speed.
+.s3
+For each string there is a header of four words, namely
+a write pointer, a read pointer and pointers to the beginning and end of
+the block containing the string.
+Initially the read and write pointers point to the beginning of the string.
+All routines that refer to a string require the header address in r1.
+Unless the string is destroyed by the call,
+upon return r1 will point to the same string, although
+the string may have grown to the extent that it had to be
+be moved.
+.s3
+.it Allocate
+obtains a string of the requested size and returns
+a pointer to its header in r1.
+.s3
+.it Release
+releases a string back to free storage.
+.s3
+.it Putchar
+and
+.it putword
+write a byte or word respectively into the string
+and advance the write pointer.
+.s3
+.it Lookchar
+and
+.it lookword
+read
+a byte or word respectively from the string but do not advance the read pointer.
+.s3
+.it Getchar
+and
+.it getword
+read a byte or word respectively from the string and advance the read pointer.
+.s3
+.it Alterchar
+and
+.it alterword
+write a byte or word respectively into the string where the read pointer
+is pointing and advance the read pointer.
+.s3
+.it Backspace
+and
+.it backword
+read the last byte or word written and decrement the write pointer.
+.s3
+All write operations will automatically get a larger block if the current block is exceeded.
+All read operations return with the error bit set if attempting to read beyond the write pointer.
+.s3
+.it Seekchar
+moves the read pointer to the offset specified in r0.
+.s3
+.it Length
+returns the current length of the string (beginning pointer to write pointer) in r0.
+.s3
+.it Position
+returns the current offset of the read pointer in r0.
+.s3
+.it Rewind
+moves the read pointer to the beginning of the string.
+.s3
+.it Create
+returns the read and write pointers to the beginning of the string.
+.s3
+.it Fsfile
+moves the read pointer to the current position of the write pointer.
+.s3
+.it Zero
+zeros the whole string and sets the write pointer to the beginning of the string.
+.s3
+.it Copy
+copies the string whose header pointer is in r0 to the string whose header pointer is in
+r1.
+Care should be taken in using the copy instruction since r1 will be changed if the contents of the source string
+is bigger than the destination string.
+.s3
+.it Wc
+forces the contents of the internal buffers and the header blocks to be written on disc.
+.s3
+An in-core version of this allocator exists in
+.it dc
+(I),
+and a permanent-file version exists in
+.it form
+and 
+.it fed
+(VI).
+.sh FILES
+.if t .ta 1i
+.if n .ta 13
+/lib/libs.a    library, accessed by
+.it "ld ... -ls"
+.br
+alloc.d        temporary file for string storage
+.sh "SEE ALSO"
+alloc (III)
+.sh DIAGNOSTICS
+`error in copy' \*- disk write error encountered in
+.it copy.
+.br
+`error in allocator' \*- routine called with bad header pointer.
+.br
+`cannot open output file' \*- temp file 
+.it alloc.d 
+cannot be created or opened.
+.br
+`out of space' \*- no sufficiently large block or no 
+header is available for a new or growing block.
+.sh BUGS