    SALLOC(VII)                  6/15/72                  SALLOC(VII)

    NAME
         salloc - string allocation and manipulation

    SYNOPSIS
         (get size in r0)
         jsr pc,allocate
         (header address in r1)

         (get source header address in r0,
         destination header address in r1)
         jsr pc,copy

         jsr pc,wc

         (all following routines assume r1 contains header address)

         jsr pc,release

         (get character in r0)
         jsr pc,putchar

         jsr pc,lookchar
         (character in r0)

         jsr pc,getchar
         (character in r0)

         (get character in r0)
         jsr pc,alterchar

         (get position in r0)
         jsr pc,seekchar

         jsr pc,backspace
         (character in r0)

         (get word in r0)
         jsr pc,putword

         jsr pc,lookword
         (word in r0)

         jsr pc,getword
         (word in r0)

         (get word in r0)
         jsr pc,alterword

         jsr pc,backword
         (word in r0)

         jsr pc,length
         (length in r0)

         jsr pc,position

                                  - 1 -

    SALLOC(VII)                  6/15/72                  SALLOC(VII)

         (position in r0)

         jsr pc,rewind

         jsr pc,create

         jsr pc,fsfile

         jsr pc,zero

    DESCRIPTION
         This  package is a complete set of routines for dealing with
         almost arbitrary length strings  of  words  and  bytes.   It
         lives  in  /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.

         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.

         Allocate obtains a string of the requested size and  returns
         a pointer to its header in r1.

         Release releases a string back to free storage.

         Putchar  and  putword write a byte or word respectively into
         the string and advance the write pointer.

         Lookchar and lookword read a byte or word respectively  from
         the string but do not advance the read pointer.

         Getchar  and  getword  read a byte or word respectively from
         the string and advance the read pointer.

         Alterchar and alterword write a byte  or  word  respectively
         into  the  string where the read pointer is pointing and ad-
         vance the read pointer.

         Backspace and backword read the last byte  or  word  written
         and decrement the write pointer.

         All  write  operations will automatically get a larger block
         if the current block is exceeded.  All read  operations  re-
         turn with the error bit set if attempting to read beyond the
         write pointer.

         Seekchar moves the read pointer to the offset  specified  in
         r0.

                                  - 2 -

    SALLOC(VII)                  6/15/72                  SALLOC(VII)

         Length  returns  the current length of the string (beginning
         pointer to write pointer) in r0.

         Position returns the current offset of the read  pointer  in
         r0.

         Rewind  moves  the  read  pointer  to  the  beginning of the
         string.

         Create returns the read and write pointers to the  beginning
         of the string.

         Fsfile moves the read pointer to the current position of the
         write pointer.

         Zero zeros the whole string and sets the  write  pointer  to
         the beginning of the string.

         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  desti-
         nation string.

         Wc forces the contents of the internal buffers and the head-
         er blocks to be written on disc.

         An in-core version of this allocator exists in dc(I), and a
         permanent-file version exists in form and fed(VI).

    FILES
         /lib/libs.a  library, accessed by ld ... -ls
         alloc.d      temporary file for string storage

    SEE ALSO
         alloc(III)

    DIAGNOSTICS
         `error in copy' - disk write error encountered in copy.
         `error in allocator' - routine called with bad header point-
         er.
         `cannot open output file' - temp file alloc.d cannot be cre-
         ated or opened.
         `out of space' - no sufficiently large block or no header is
         available for a new or growing block.

    BUGS

                                  - 3 -