#-h- acopy.fmt        349  asc  25-mar-82 10:09:51  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Acopy (3) 15-Mar-82
copy n characters from one file to another
.sy
subroutine acopy(ifd, ofd, n)

integer n
filedes ifd, ofd
.ds
`acopy' copies `n' characters from `ifd' to `ofd', both of
which are assumed open.  If an EOF is encountered on `ifd' before `n'
characters have been copied, the routine simply returns.
.sa

.di
none
#-h- adddi.fmt        554  asc  25-mar-82 10:09:52  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Adddi (3) 15-Mar-82
add double integers together
.sy
adddi(dbl1,dbl2)

integer dbl1(2), dbl2(2)

expands into:

.in +6
{
dbl2(1) = dbl2(1) + dbl1(1)
dbl2(2) = dbl2(2) + dbl1(2)
if (dbl2(2) >= 10000)
.in +2
{
dbl2(1) = dbl2(1) + 1
dbl2(2) = dbl2(2) - 10000
}
.in -2
}
.in -6
.ds
Invocation of this macro causes the first double integer
argument to be added to the second.  If a carry is necessary, it is
performed.  See the entry for `initdi' for more information on
double integers.
.sa
initdi(3), incrdi(3), decrdi(3), subdi(3)
.di

#-h- addset.fmt       588  asc  25-mar-82 10:09:53  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Addset (3) 13-Nov-78
put c in array(j) if it fits, increment j
.sy
stat = addset(c, array, j, maxsize)

character c, array(ARB)
integer j                 # j is incremented
integer maxsize
integer stat returned as YES/NO
.ds
Adds a character at a time to a specified position of an array
and increments the index.
It also checks that there's enough room to do so.

The array is an ascii character array stored one character per
word.
'c' is a single ascii character.

YES is returned if the routine succeeded, otherwise NO.
.sa
scopy(3), stcopy(3), concat(3)
.di
None
#-h- addstr.fmt       703  asc  25-mar-82 10:09:54  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Addstr (3) 17-Sep-81
add string s to str(j) if it fits, increment j
.sy
stat = addstr(s, str, j, maxsize)

character s(ARB), str(ARB)
integer j                 # j is incremented
integer maxsize
integer stat returned as YES/NO
.ds
Copies the string 's' to array 'str', starting in location 'j'.
`j' is incremented to point to the next free position in 'str'.

If the addition of `s' to `str' will exceed its maximum length (maxsize),
no copying is done and the status NO is returned.

Both `s' and `str' are ascii character arrays stored one character per
array element.

YES is returned if the routine succeeded, otherwise NO.
.sa
scopy(3), stcopy(3), addset(3), concat(3)
.di
None
#-h- adrfil.fmt       291  asc  25-mar-82 10:09:55  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Adrfil (3) 15-Mar-82
get name of user-information database file
.sy
subroutine adrfil(file)

character file(FILENAMESIZE)
.ds
`adrfil' returns the local file specification for the
user-information database file, known as "~msg/address".
.sa
mailid(2), homdir(2)
.di
none
#-h- agetch.fmt       679  asc  25-mar-82 10:09:56  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Agetch (3) 14-Mar-82
get next character from an archive module
.sy
character function agetch(c, fd, size)

character c
filedes fd
integer size(2)
.ds
`agetch' fetches the next character from the archive
module opened on `fd' and returns it in the variable `c' and as the
value of the function.  The `size' argument is that returned by an
`aopen' or `agethd' call, and is decremented by `agetch' to reflect
the decrease in size of the remainder of the module.  If the end of the
module is detected, or a true end of file is detected on `fd', the
value EOF is returned.
.sa
agethd(3), agtlin(3), aopen(3), askip(3)
.di
Returns EOF if end of module is detected.
#-h- agethd.fmt       823  asc  25-mar-82 10:09:57  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Agethd (3) 14-Mar-82
get next archive header from file
.sy
integer function agethd(fd, buf, size, fsize)

filedes fd
character buf(MAXLINE)
integer size(2), fsize(2)
.ds
`agethd' reads the next line from the archive module
represented by the file descriptor `fd' and the size `fsize'.
If the line is of the form of an archive header, the name of the
module is placed in `buf', and the size of the module is placed
in `size', with `fsize' decremented to represent the decrease in size
of the containing module.  The value OK is returned if successful.
If an end of module is detected, the value EOF is returned, and if
the line read is not of the proper format, a value of ERR is returned.
.sa
agetch(3), agtlin(3), aopen(3), askip(3)
.di
Returns EOF on end of module and ERR if improper archive
format.
#-h- agtlin.fmt       610  asc  25-mar-82 10:09:58  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Agtlin (3) 14-Mar-82
get next line from an archive module
.sy
integer function agtlin(buf, fd, size)

character buf(MAXLINE)
filedes fd
integer size(2)
.ds
`agtlin' fetches the next line of input from the archive
module represented by the arguments `fd' and `size'.  If another line
is found, it is placed in `buf', `size' is decremented by the number of
characters in the line, and this number is returned as the value of the
function.  If an end of module is detected, a value of EOF is returned.
.sa
agetch(3), agethd(3), aopen(3), askip(3)
.di
Returns EOF if end of module is detected.
#-h- alldig.fmt       308  asc  25-mar-82 10:09:58  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Alldig (3) 15-Mar-82
determine if string is all digits
.sy
integer function alldig(str)

character str(ARB)
.ds
`alldig' determines if the given string is all digits.  If
this is true, the value YES is returned, otherwise, NO.
.sa
type(3)
.di
A value of NO is returned if not all digits.
#-h- amatch.fmt       937  asc  25-mar-82 10:09:59  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Amatch (3) 23-Jul-80
look for pattern matching regular expression
.sy
integer function amatch(line, from, pat, tagbeg, tagend)

character line(ARB)
integer   from, pat(MAXPAT)
integer   tagbeg(10), tagend(10)
.in +10
(element "i+1" returns start or end, respectively,
of "i"th tagged sub-pattern)
.in -10
.ds
Amatch scans 'line' starting at location 'from', looking
for a pattern which matches the
regular expression coded in 'pat'.
If the pattern is found, the next available location in `line' is returned.
If the pattern is not found, amatch returns 0.

The regular expression in 'pat' must have been previously
encoded by 'getpat' or 'makpat'.
(For a complete description of regular expressions,
see the
writeup on the editor.)

Amatch is a special-purpose version of match, which should be
used in most cases.
.sa
match(3), getpat(3), makpat(3), ed(1)
.di
A value of 0 is returned if the pattern does not match.
#-h- aopen.fmt       1144  asc  25-mar-82 10:10:00  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Aopen (3) 14-Mar-82
open archive module for reading
.sy
filedes function aopen(name, fd, size)

character name(FILENAMESIZE)
filedes fd
integer size(2)
.ds
`aopen' opens the archive module specified in `name' for
reading with subsequent calls to `agetch' and `agtlin'.
If the open is successful, the resulting file descriptor is placed in
`fd', as well as returned as the function value; the size of the module
is placed in the variable `size'.  Failure is signalled by returning a
value of ERR.

The format of the name specification is quite straight-forward; the
syntax is:
.sp
.ce
filename[`module]...
.sp
If no module names are specified, `aopen' is equivalent to an `open' call
at READ access, and an "infinite" module size is placed in `size'.
.ex
.nf
character c
character agetch
integer size(2)
filedes fd
filedes aopen

string name "rlib.w`lib.r`arsubs.r`aopen"

if (aopen(name, fd, size) == ERR)
.ti +2
call cant(name)
while (agetch(c, fd, size) != EOF)
.ti +2
call putch(c, STDOUT)
call close(fd)
.fi
.sa
agetch(3), agethd(3), agtlin(3), askip(3)
.di
Returns ERR if the specified archive module cannot be opened.
#-h- argtab.fmt       423  asc  25-mar-82 10:10:01  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Argtab (3) 15-Mar-82
fetch tab information from command line
.sy
subroutine argtab(buf)

character buf(MAXLINE)
.ds
`argtab' reads the command line arguments, using `getarg',
and copies those arguments which `detab' and `entab' understand into
`buf', separated by blank characters.  This is in preparation for calling
`settab' to set the TAB stops.
.sa
settab(3), detab(1), entab(1), getarg(2)
.di
none
#-h- askip.fmt        952  asc  25-mar-82 10:10:02  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Askip (3) 14-Mar-82
skip rest of archive module contents
.sy
subroutine askip(fd, size, fsize)

filedes fd
integer size(2), fsize(2)
.ds
`askip' skips the number of characters indicated by `size'
in the archive module specified by `fd' and `fsize'.  `fsize' is
decreased by the number of characters skipped.  This routine is handy when
using `aopen' to open a nested archive, and then scanning the archive
modules at that level for the ones of interest.
.ex
.nf
character buf(MAXLINE)
integer size(2), fsize(2)
integer agethd
filedes fd
filedes aopen

string name "rlib.w`lib.r"
string line "The modules contained in rlib.w`lib.r are:@n"

if (aopen(name, fd, fsize) == ERR)
.ti +2
call cant(name)
call putlin(line, STDOUT)
while (agethd(fd, buf, size, fsize) == OK)
.in +2
{
call putlin(buf, STDOUT)
call putch('@n', STDOUT)
call askip(fd, size, fsize)
}
.in -2
call close(fd)
.fi
.sa
agetch(3), agethd(3), agtlin(3), aopen(3)
.di

#-h- badarg.fmt       298  asc  25-mar-82 10:10:03  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Badarg (3) 15-Mar-82
output "invalid argument" message
.sy
subroutine badarg(arg)

character arg(ARB)
.ds
`badarg' displays the following message on Error Output:

.ce
? Ignoring invalid argument `<arg>'

where <arg> is replaced by the contents of `arg'.
.sa
getarg(2)
.di
none
#-h- bubble.fmt       346  asc  25-mar-82 10:10:04  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Bubble (3) 15-Mar-82
bubble sort integers
.sy
subroutine bubble(v, n)

integer n, v(n)
.ds
`bubble' performs a bubble sort on the integers v(1) ... v(n).
As is well known, the bubble sort algorithm should only be used for very
small arrays.  If larger arrays need to be sorted, see the entry on `shell'.
.sa
shell(3)
.di
none
#-h- cant.fmt         367  asc  25-mar-82 10:10:05  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Cant (3) 13-Nov-78
print "Can't open" message and terminate execution
.sy
call cant(name)

character name(ARB)
.ds
Prints an error message (on ERROUT) indicating file "name" could not be opened.
All open files are closed and execution is terminated.
Name is an ascii character array terminated with an EOS marker.
.sa
error(3), remark(2)
.di
None
#-h- catsub.fmt       908  asc  25-mar-82 10:10:06  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Catsub (3) 15-Mar-82
add replacement text to new buffer
.sy
subroutine catsub(lin, from, to, sub, new, k, maxnew)

integer from, to, k, maxnew
character lin(MAXLINE), new(maxnew), sub(ARB)
.ds
The string represented by lin(from) ... lin(to-1) is replaced according to
the instructions in `sub'(which has been generated via a call to `getsub'
or `maksub');
the replacement text is appended to `new'
starting at position `k'.
`k' is incremented as the substitutions are added, and points to the
EOS location `new' upon return.
`maxnew' represents the maximum size of
`new'.  If an illegal tagged pattern (section) has been specified in
`sub', the error message
.ce
? In CatSub: illegal section.
is displayed to the user on Error Output.
.sa
getpat(3), makpat(3), amatch(3), getsub(3), maksub(3)
.di
If an illegal section is specified, a comment to that effect is
displayed on Error Output.
#-h- chcopy.fmt       398  asc  25-mar-82 10:10:07  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Chcopy (3) 15-Mar-82
copy character into buffer, increment pointer, EOS terminate
.sy
subroutine chcopy(c, buf, i)

character c, buf(ARB)
integer i
.ds
`chcopy' copies `c' into `buf(i)', increments `i', and places
an EOS after `c' in `buf'.  This routine assumes that there is enough
room in `buf' for BOTH the character and the EOS.
.sa
addset(3), stcopy(3), scopy(3)
.di
none
#-h- clower.fmt       239  asc  25-mar-82 10:10:07  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Clower (3) 13-Nov-78
fold c to lower case
.sy
c = clower(c)

character c
.ds
Fold character c to lower case, if not already there.
If c is not alphabetic, returns it unchanged.
.sa
fold(3), upper(3), clower(3)
.di
None
#-h- concat.fmt       458  asc  25-mar-82 10:10:08  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Concat (3) 23-Jul-80
concatenate 2 strings together
.sy
call concat(buf1, buf2, outstr)

character buf1(ARB), buf2(ARB), outstr(ARB)
.ds
Copies the arrays buf1 and buf2 into the array outstr.

All arrays are ascii character arrays stored one character per
array element.
.sp
It is perfectly legal for `buf1' and `outstr' to be the same arrays, which
results in `buf2' being appended to `buf1'.
.sa
scopy(3), stcopy(3), addset(3)
.di
None
#-h- ctoc.fmt         804  asc  25-mar-82 10:10:09  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Ctoc (3) 23-Mar-80
copy string-to-string, observing length limits
.sy
integer function ctoc (from, to, len)
integer len
character from (ARB), to (len)
.ds
'Ctoc' copies an EOS-terminated unpacked string from one array to
another, observing a maximum-length constraint on the destination array.
The function return is the number of characters copied (i.e., the
length of the string in the parameter 'to').
.sp
Note that the other string copy routine, 'scopy', is not protected;
if the length of the source string exceeds the space available in the
destination string, some portion of memory will be garbled.
.im
A simple loop copies characters from 'from' to 'to' until
an EOS is encountered or all the space available in the destination
array is used up.
.am
to
.sa
scopy(3), ctoi(3)
#-h- ctodi.fmt        431  asc  25-mar-82 10:10:10  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Ctodi (3) 15-Mar-82
convert character string to double integer array
.sy
subroutine ctodi(buf, i, di)

character buf(ARB)
integer i, di(2)
.ds
`ctodi' converts the numeric string starting at `buf(i)' into
a double integer array, as described in `initdi'.  The index `i' is left
at the next character after the converted numeric string.
.sa
ditoc(3), initdi(3), incrdi(3), decrdi(3), adddi(3), subdi(3)
.di
none
#-h- ctoi.fmt         762  asc  25-mar-82 10:10:11  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Ctoi (3) 13-Nov-78
convert string at in(i) to integer, increment i
.sy
n = ctoi(in, i)

character in(ARB)
integer i               # i is incremented
integer n is returned as the converted integer
.ds
Ctoi converts the character string at "in(i)" into an integer.
A leading minus sign ('-') is allowed.
Leading blanks and tabs are ignored; any subsequent digits are
converted to the correct numeric value.
The first non-digit seen terminates the scan; upon return,
"i"
points to this position.
"n"
is returned as the value of the integer.

The
"in"
array is an ascii character array terminated with an EOS marker
(or a non-numeric character).

Zero is returned if no digits are found.
.sa
itoc(3)
.di
There are no checks for machine overflow.
#-h- cupper.fmt       271  asc  25-mar-82 10:10:12  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Cupper (3) 13-Nov-78
convert character to upper case
.sy
c = cupper(c)

character c
.ds
CUPPER converts ascii character c to upper case, if not already there.
Non-alphabetic characters are returned unchanged.
.sa
upper(3), clower(3), fold(3)
.di
None
#-h- decrdi.fmt       522  asc  25-mar-82 10:10:12  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Decrdi (3) 15-Mar-82
decrement double integer array
.sy
decrdi(dblint)

integer dblint(2)

expands into:

.in +6
{
dblint(2) = dblint(2) - 1
if (dblint(2) < 0)
.in +2
{
dblint(1) = dblint(1) - 1
dblint(2) = 9999
}
.in -2
}
.in -6
.ds
Invocation of this macro causes the double integer argument
to be decremented by one, with an appropriate carry occurring, if necessary.
See the entry for `initdi' for more information on the double integer
construct.
.sa
initdi(3), incrdi(3), adddi(3), subdi(3)
.di

#-h- delete.fmt       902  asc  25-mar-82 10:10:13  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Delete (3) 23-Mar-80
remove a symbol from a symbol table
.sy
subroutine delete (symbol, table)
character symbol (ARB)
pointer table
.ds
'Delete' removes the character-string symbol given as its first argument
from the symbol table given as its second argument.
All information associated with the symbol is lost.
.sp
The symbol table specified must have been generated by the routine 'mktabl'.
.sp
If the given symbol is not present in the symbol table, 'delete'
does nothing; this condition is not considered an error.
.im
'Delete' calls 'stlu' to determine the location of the given symbol
in the symbol table.
If present, it is unlinked from its hash chain.
The dynamic storage space allocated to the symbol's node is returned
to the system by a call to 'dsfree'.
.ca
stlu, dsfree
.sa
enter(3), lookup(3), mktabl(3), rmtabl(3), stlu(3),
dsget(3), dsfree(3), dsinit(3), sctabl(3)
#-h- disize.fmt       516  asc  25-mar-82 10:10:14  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Disize (3) 15-Mar-82
determine size of file as double integer array
.sy
integer function disize(file, di)

character file(FILENAMESIZE)
integer di(2)
.ds
`disize' opens `file', counts the number of characters as
a double integer, closes the file, and returns the value OK.  If the
file could not be opened, a value of ERR is returned.  Consult the
entry for `initdi' for more information on double integers.
.sa
fsize(3), initdi(3)
.di
A value of ERR is returned if the file could not be opened.
#-h- ditoc.fmt        499  asc  25-mar-82 10:10:15  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Ditoc (3) 15-Mar-82
convert a double integer array to a character string
.sy
integer function ditoc(di, buf, size)

integer di(2), size
character buf(size)
.ds
`ditoc' converts the double integer in `di' into a character
string in buf.  The length of the generated string is returned as the
value of the function.  The entry on `initdi' can be consulted for more
information on double integers.
.sa
ctodi(3), itoc(3), initdi(3), incrdi(3), decrdi(3), adddi(3), subdi(3)
.di
none
#-h- dopack.fmt       639  asc  25-mar-82 10:10:16  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Dopack (3) 14-Mar-82
pack words at TAB stops and flush line, if required
.sy
subroutine dopack(word, nxtcol, rightm, buf, fd)

filedes fd
integer nxtcol, rightm
character word(ARB), buf(MAXLINE)
.ds
`dopack' packs `word' into `buf', aligning word at the next
available tab stop, which are taken to be every 16 characters.  If `buf'
cannot be added to without exceeding `rightm', `buf' will be flushed to
`fd' and `word' packed into `buf' starting in column 1.   At least one
word is packed into `buf', regardless of length, to assure that
some progress is made in outputting the data.
.sa
inpack(3), flpack(3)
.di
none
#-h- dsdecl.fmt       876  asc  25-mar-82 10:10:17  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Dsdecl (3) 15-Mar-82
declare storage for Dynamic Memory routines
.sy
DS_DECL(Mem,MEM_SIZE)

expands into:
.sp
.in +6
integer Mem(MEM_SIZE)
character cMem(arith(MEM_SIZE,*,CHAR_PER_INT))
equivalence (Mem(1),cMem(1))

common / cdsmem / Mem
.in -6
.ds
This macro invocation must appear in the program units which
invoke any of the following routines: dsinit, iminit, tbinit.
This macro causes the common block which is used by the dynamic storage
routines to be generated into the program with a size determined by the
constant MEM_SIZE.
The same value of MEM_SIZE must be used in the calls to dsinit, iminit
and tbinit as is used in the DS_DECL declaration.
.sp
The user must have defined MEM_SIZE prior to the invocation of
DS_DECL, usually via a statement of the form
.sp
.ce
define(MEM_SIZE,4000)
.sp
for example.
.sa
dsinit(3), iminit(3), tbinit(3)
.di

#-h- dsfree.fmt      1079  asc  25-mar-82 10:10:18  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Dsfree (3) 23-Mar-80
free a block of dynamic storage
.sy
subroutine dsfree (block)
pointer block
.ds
'Dsfree' returns a block of storage allocated by 'dsget' to the
available space list.
The argument must be a pointer returned by 'dsget'.
.sp
See the remarks under 'dsget' for required initialization measures.
.im
'Dsfree' is an implementation of Algorithm B on page 440 of Volume 1
of The Art of Computer Programming, by Donald E. Knuth.
The reader is referred to that source for detailed information.
.sp
'Dsfree' and 'dsget' maintain a list of free storage blocks,
ordered by address.
'Dsfree' searches the list to find the proper location for the block
being returned, and inserts the block into the list at that location.
If blocks on either side of the newly-returned block are available,
they are coalesced with the new block.
If the block address does not correspond to the address of any
allocated block, 'dsfree' remarks "attempt to free unallocated
block" and returns to the user.
.bu
The algorithm itself is not the best.
.sa
dsget(3), dsinit(3)
#-h- dsget.fmt       1619  asc  25-mar-82 10:10:19  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Dsget (3) 23-Mar-80
obtain a block of dynamic storage
.sy
pointer function dsget (w)
integer w
.ds
'Dsget' searches its available memory list for a block that is
at least as large as its first argument.
If such a block is found, its index in the memory list is returned;
otherwise, the constant LAMBDA is returned.
.sp
In order to use 'dsget', the following declaration must be present:
   DS_DECL (mem, MEMSIZE)
.br
where MEMSIZE is supplied by the user, and may take on any positive
value between 6 and 32767, inclusive.
Furthermore, memory must have been initialized with a call to 'dsinit':
   call dsinit (MEMSIZE)
.im
'Dsget' is an implementation of Algorithm A' on pages 437-438 of
Volume 1 of The Art of Computer Programming, by Donald E. Knuth.
The reader is referred to that source for detailed information.
.sp
'Dsget' searches a linear list of available blocks for one of
sufficient size.
If none are available, a value of LAMBDA is returned;
otherwise, the block found is broken into two pieces, and the index
(in array 'mem') of the piece of the desired size is returned to
the user.
The remaining piece is left on the available space list.
Should this procedure cause a block to be left on the available
space list that is smaller than a threshhold size, the few extra
words are awarded to the user and the block is removed entirely,
thus speeding up the next search for space.
.bu
It is somewhat annoying for the user to have to declare
the storage area, but Fortran prevents effective use of pointers,
so this inconvenience is necessary for now.
.sa
dsfree(3), dsinit(3), dsdecl(3)
#-h- dsinit.fmt       819  asc  25-mar-82 10:10:20  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Dsinit (3) 23-Mar-80
initialize dynamic storage space
.sy
subroutine dsinit (w)
integer w
.ds
'Dsinit' initializes an area of storage in the common block CDSMEM
so that the routines 'dsget' and 'dsfree' can be used for dynamic
storage allocation.
The memory to be managed must be supplied by the user, by a
declaration of the form:
   DS_DECL (mem, MEMSIZE)
.br
.br
The memory size must be passed to 'dsinit' as its argument:
   call dsinit (MEMSIZE)
.im
'Dsinit' sets up an available space list consisting of two blocks,
the first empty and the second containing all remaining memory.
The first word of memory (below the available space list) is set
to the total size of memory; this information is used only by the
dump routines 'dsdump' and 'dsdbiu'.
.ca
error
.sa
dsget(3), dsfree(3), dsdecl(3)
#-h- entdef.fmt       632  asc  25-mar-82 10:10:21  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Entdef (3) 14-Mar-82
enter a new symbol definition, discarding any old one
.sy
subroutine entdef(name, defn, table)

character name(ARB), defn(ARB)
pointer table
.ds
`entdef' enters a (name,defn) pair into the symbol table
`table'.  If any old definitions for `name' exist, they are purged.
`table' must have been obtained by a call to `mktabl'.  If the
(name,defn) pair cannot be stored in the table, the error message
.sp
in entdef: no room for new definition.
.sp
is displayed on error output.
.sa
mktabl(3), ludef(3)
.di
If the symbol definition cannot be entered, an error
message is displayed to the user.
#-h- enter.fmt       1447  asc  25-mar-82 10:10:22  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Enter (3) 23-Mar-80
place symbol in symbol table
.sy
integer function enter (symbol, info, table)
character symbol (ARB)
integer info (ARB)
pointer table
.ds
'Enter' places the character-string symbol given as its first argument,
along with the information given in its second argument, into the symbol
table given as its third argument.
If the symbol is successfully entered in the table, the value of OK is
returned; otherwise, the value ERR is returned.
.sp
The symbol table used must have been created by the routine 'mktabl'.
The size of the info array must be at least as large as the symbol
table node size, determined at table creation time.
.sp
Should the given symbol already be present in the symbol table,
its information field will simply be overwritten with the new information.
.sp
'Enter' uses the dynamic storage management routines, which
require initialization by the user; see 'dsinit' for further details.
.im
'Enter' calls 'stlu' to find the proper location for the symbol.
If the symbol is not present in the table, a call to 'dsget' fetches
a block of memory of sufficient size, which is then linked onto the
proper chain from the hash table.
Once the location of the node for the given symbol is known, the
contents of the information array are copied into the node's information
field.
.ca
stlu, dsget
.sa
lookup(3), delete(3), mktabl(3), rmtabl(3), stlu(3),
dsget(3), dsfree(3), dsinit(3), sctabl(3)
#-h- equal.fmt        365  asc  25-mar-82 10:10:24  v1.1 (sw-tools v1.1)
.bp 1
.in 0
.so ~bin/manhdr
.hd Equal (3) 13-Nov-78
compare str1 to str2; return YES if equal
.sy
stat = equal(str1, str2)

character str1(ARB), str2(ARB)
integer stat is returned as YES/NO
.ds
Compares two strings, returning YES if they are the same, NO
if they differ.
Each string is an ascii character array
terminated with an EOS marker.
.sa
strcmp(3)
.di
None
#-h- error.fmt        686  asc  25-mar-82 10:10:24  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Error (3) 23-Jul-80
print single-line message and terminate execution
.sy
call error (message)

integer message          #message is a hollerith array
.ds
Error
writes the message onto the standard error file ERROUT.
A NEWLINE is always generated, even though one may not appear in
the message.
Endst is called
and execution ceases.

Error is essentially a call to 'remark' and then to 'endst'.

The message array is a Fortran hollerith string in the
format generated by the Ratfor quoted string capability.
On some systems,
it may be necessary to terminate the string with a '.' or other
end-of-string marker.
.sa
remark(2), putlin(2), prompt(2), endst(2)
.di
None
#-h- esc.fmt         1046  asc  25-mar-82 10:10:25  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Esc (3) 23-Jul-80
map array(i) into escaped character, if appropriate
.sy
character function esc(array, i)

character array(ARB)
integer i              # i will be incremented
.ds
This function checks array(i) for the existence of an
escape character (as defined by ESCAPE in the general
symbol definitions).
If an escape is found and is appropriate, array(i+1) is
returned as the escaped character.
If no escape is found, the character `array(i)' is returned.

Those characters which have special meaning are:
.sp
.in +10
.nf
b   backspace (BS) ^H
f   formfeed  (FF) ^L
l   linefeed  (LF) ^J
n   newline   (LF) ^J
r   return    (CR) ^M
t   tab       (HT) ^I
.sp
.in -10
In addition, specifying '@ddd', where '0' <= d <= '7', results in the
encoding of a character with that octal representation.  Therefore, a
^Z character (SUB or 8%026) could be specified as '@026'.

If the character after the escape is not one of the above or a string of
digits, then that character is returned, unchanged.
.sa
index(3), type(3)
.di
None
#-h- exppth.fmt       895  asc  25-mar-82 10:10:27  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Exppth (3) 15-Mar-82
generate pointers to the path fields in a filename
.sy
subroutine exppth(path, depth, ptr, buf)

character path(FILENAMESIZE), buf(FILENAMESIZE)
integer depth, ptr(MAXDIRECTS)
.ds
Given a filename in path format in the array `path', `exppth'
scans the pathname, filling in pointers to each path field in `ptr', and
returns the number of path fields found in `depth'.
.ex
.nf
.in +6
integer depth, ptr(MAXDIRECTS)
character scr(FILENAMESIZE)

string path "~bin/symbols"

call exppth(path, depth, ptr, scr)

.in -6
.fi
Upon return from exppth, ptr(1) is 1, ptr(2) is 5, and depth is 2.
The calling program can now access the individual path fields via
invocations of the following form:

.nf
.in +6
i = ptr(2)
junk = gtftok(path, i, scr)
.in -6
.fi
.sp
The second path field ("symbols") is now in `scr', awaiting further processing.
.sa
gtftok(3)
.di
none
#-h- fcopy.fmt        451  asc  25-mar-82 10:10:27  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Fcopy (3) 13-Nov-78
copy file in to file out
.sy
call fcopy (in, out)

integer in, out
.ds
Assuming that both files are opened, positioned, and ready to go,
the routine copies lines from the current file position until
an EOF is reached on file 'in'.
'in' and 'out' are file identifiers returned by open or create.
.im
'Fcopy' simply makes repeated calls to getlin and putlin.
.sa
open(2), create(2), getlin(2), putlin(2)
.di
None
#-h- flpack.fmt       301  asc  25-mar-82 10:10:28  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Flpack (3) 14-Mar-82
flush any packed words
.sy
subroutine flpack(nxtcol, rightm, buf, fd)

filedes fd
integer nxtcol, rightm
character buf(MAXLINE)
.ds
`flpack' writes `buf' to `fd' if there is any data packed into
`buf', and resets nxtcol to 1.
.sa
inpack(3), dopack(3)
.di
none
#-h- fmtdat.fmt       963  asc  25-mar-82 10:10:29  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Fmtdat (3) 25-Sep-80
convert date information to character string
.sy
subroutine fmtdat (date, time, now, form)
character date (10), time (9)
integer now (7), form
.ds
'Fmtdat' is used to convert date information (such as that provided
by 'getnow') into human-readable graphics.
The first argument is a character string to receive the representation
of the current date.
The second argument is a character string to receive the representation
of the current time.
The third argument is a date specification in the same 7-word integer
array format as is returned by 'getnow' (year including century,
month, day, hour, minute, second, millisecond).
The fourth argument selects the format of the character representations;
if form == LETTER, the date is formatted as dd-Mmm-yy; if form == DIGIT,
`date' is formatted as mm/dd/yy.  `time' is formatted as hh:mm:ss.
.im
Simple integer-to-character conversions.
.am
date, time
.sa
getnow(2), date(1)
#-h- fold.fmt         318  asc  25-mar-82 10:10:30  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Fold (3) 13-Nov-78
convert string to lower case
.sy
call fold (str)

character str(ARB)
.ds
Converts the array 'str' to lower case characters.
Non-alphabetic characters are left unchanged.
The 'str' array is ascii characters terminated by an EOS marker.
.sa
clower(3), cupper(3), upper(3)
.di
None
#-h- fsize.fmt        621  asc  25-mar-82 10:10:31  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Fsize (3) 15-Mar-82
determine size of file in characters
.sy
integer function fsize(file)

character file(FILENAMESIZE)
.ds
`fsize' opens the file, counts the number of characters using
`getch', and closes the file, returning the number of characters found as
an integer.  Caution must be exercised on 16-bit machines, as any files
containing more than 32767 characters will not be accounted for correctly.
It is probably better to use `disize' as a rule, since the 16-bit limit
will only affect files with more than 327,679,999 characters.
.sa
disize(3)
.di
Returns ERR if the file cannot be opened.
#-h- fskip.fmt        303  asc  25-mar-82 10:10:32  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Fskip (3) 15-Mar-82
skip n characters on open file
.sy
subroutine fskip(fd, n)

filedes fd
integer n
.ds
`n' characters are skipped on the file open on unit `fd'.
.sa
acopy(3)
.di
If an EOF is encountered before the number of characters has
been skipped, the routine simply returns.
#-h- getc.fmt         512  asc  25-mar-82 10:10:33  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Getc (3) 10-Nov-78
read character from standard input
.sy
c = getc (c)

character c
.ds
Getc
reads the next character from the standard input.
The character is returned in ascii format both as the functional
return and in the parameter c.
If the end of a line has been encountered, NEWLINE is returned.
If the end of the file has been encountered, EOF is returned.

If the input file is not ascii, characters are mapped
into their corresponding ascii format.
.sa
getch(2), getlin(2)
.di
None
#-h- getpat.fmt      1028  asc  25-mar-82 10:10:34  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Getpat (3) 23-Jul-80
prepare regular expression for pattern matching
.sy
integer function getpat(arg, pat)

character arg(ARB)
integer   pat(MAXPAT)
.ds
Getpat is used to translate a regular expression into a format
convenient for subsequent pattern matching via 'match'
or 'amatch'.
(For a complete description of regular expressions, see the
writeup on the editor.)

A typical scenario for pattern-matching might be:

.nf
.in +5
stat = getpat(pattern_you_want_located, pattern_array)
YES/NO = match(input_line, pattern_array)
.in -5
.fi
.sp
The pattern array should be dimensioned at least MAXPAT
integers long, a definition available in the standard
symbol definitions file.
.sp
If the pattern can be made, the functions returns the number
of integers in "pat";
otherwise it returns ERR.
.sp
Getpat is essentially a call to makpat with the
following parameters:

.ce
getpat = makpat (arg, 1, EOS, pat)
.sa
makpat(3), match(3), amatch(3)
.di
A value of ERR is returned if a failure occurs in the encoding.
#-h- getsub.fmt       408  asc  25-mar-82 10:10:35  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Getsub (3) 15-Mar-82
generate substitution pattern
.sy
integer function getsub(arg, sub)

character arg(ARB), sub(MAXPAT)
.ds
This routine is simply a special version of `maksub', and is equivalent to
.sp
.ce
getsub = maksub(arg, 1, EOS, sub)
.sp
Consult the entry for `maksub' for what these routines do.
.sa
maksub(3)
.di
If an error occurs in the encoding, a value of ERR is returned.
#-h- getwrd.fmt       704  asc  25-mar-82 10:10:36  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Getwrd (3) 13-Nov-78
get non-blank word from in(i) into out, increment i
.sy
size = getwrd(in, i, out)

character in(ARB), out(ARB)
integer i               # i is incremented
integer size is returned as the length of the word found
.ds
Starting at position 'i' in array 'in', skips any leading blanks
and tabs and returns the next word and its length.
A word is any series of characters terminated by a BLANK,
TAB, or NEWLINE.
The terminator is not returned as part of the word.
'i' is incremented to the position just past the end of the
word.
The word is returned in array 'out'.

Both 'in' and 'out' are ascii character arrays terminated with an
EOS marker.
.sa
skipbl(3)
.di
None
#-h- gitocf.fmt       754  asc  25-mar-82 10:10:37  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Gitocf (3) 15-Mar-82
general integer to character conversion with fill characters
.sy
integer function gitocf(int, str, size, base, width, fc)

integer int, size, base, width
character str(size), fc
.ds
`gitocf' does general formatting of integers to characters
in any base and will right justify the number in a field of a given width,
padding with the specified fill character.  If the base specified is less
than 2 or greater than 36, a base of 10 is used.  If the resulting string
would overflow the size of str, only the rightmost `size-1' characters
are returned.  The number of characters in the string is returned as the
value of the function.  If `width' is specified as 0, then no padding is
performed.
.sa
itoc(3)
.di
none
#-h- gtftok.fmt       543  asc  25-mar-82 10:10:38  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Gtftok (3) 15-Mar-82
fetch next path token into buffer, incrementing pointer
.sy
integer function gtftok(buf, i, token)

character buf(ARB), token(FILENAMESIZE)
integer i
.ds
`gtftok' fetches the next path token starting at `buf(i)' into
the array `token', incrementing the pointer `i' to the character which
terminated the scan.  The length of the token is returned as the function
value.  Characters which can terminate the scan are '/', '\' and EOS.
Upon entry, if `buf(i)' == '/', it is skipped.
.sa
exppth(3)
.di
none
#-h- gtword.fmt       587  asc  25-mar-82 10:10:38  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Gtword (3) 15-Mar-82
get next word, subject to size limitations
.sy
integer function gtword(in, i, out, size)

integer i, size
character in(ARB), out(size)
.ds
`gtword' is similar to `getwrd', except that it will only
copy `size-1' characters into `out'.  If the next word of input is too
big for the buffer, the extra characters are skipped over, leaving `i'
pointing at the character which terminated the entire word, not just the
portion returned in `out'.  The length of the word returned in `out' is
returned as the value of the function.
.sa
getwrd(3)
.di
none
#-h- imget.fmt        588  asc  25-mar-82 10:10:39  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Imget (3) 23-Mar-80
fetch next token from in-memory sort area
.sy
integer function imget(table, buf)

pointer table
character buf(ARB)
.ds
`imget' fetches the next token from the in-memory sort area
pointed to by `table', which was returned as the function value if an
`iminit' call.  If there is another token which has not been fetched yet,
it is returned in `buf' and a value of OK is returned as the value of
the function; otherwise, the value EOF is returned.
.sa
iminit(3), imput(3), imsort(3)
.di
The value EOF is returned if there are no more tokens to fetch.
#-h- iminit.fmt       799  asc  25-mar-82 10:10:40  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Iminit (3) 23-Mar-80
initialize in-memory sort area
.sy
pointer function iminit(memsiz, avetok)

integer memsiz, avetok
.ds
`iminit' initializes the dynamic storage region (via a
`dsinit' call) and allocates a block of pointers for future use by
`imget', `imput' and `imsort'.  The pointer to this block of pointers
is returned as the value of the function.  The program calling `iminit'
must have made the following declaration
.ce
DS_DECL(Mem,memsiz)
to cause the memory area used by the dynamic storage routines to be
allocated.  `avetok' is an estimate of the average length of the
tokens which will be inserted into the dynamic memory via `imput' calls.
.sa
dsinit(3), imput(3), imget(3), imsort(3)
.di
The value LAMBDA is returned if the dynamic storage area is too small.
#-h- impath.fmt      1195  asc  25-mar-82 10:10:41  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Impath (3) 15-Mar-82
generate search path for known files
.sy
subroutine impath(path)

character path(arith(FILENAMESIZE,*,3))
.ds
`impath' returns a search path for use in `loccom' when
searching for known files.  The search path returned depends upon whether
your system has a tree-structured file system or not.  If not, the path
returned corresponds to:

.ce
"@e~/@e~usr/@e~bin/@e@n"

while tree-structured systems return:

.ce
"@e~/tools/@e~usr/@e~bin/@e@n"

Consult the entry for `loccom' for more information on the structure of
the search path.
.ex
The program wishes to spawn the editor for the user.  The following code
fragment will do the trick, searching for the editor through the standard
search path as used by the shell:

.nf
.in +6
character image(FILENAMESIZE), pid(PIDSIZE)
character path(arith(FILENAMESIZE,*,3))
integer loccom, spawn

string edst   "ed"
string args   "ed temp.fil"
string suffix IMAGE_SUFFIX

call impath(path)
if (loccom(ed, path, suffix, image) != BINARY)
.ti +2
call error("? Cannot locate editor image file.")
if (spawn(image, args, pid, WAIT) == ERR)
.ti +2
call error("? Error spawning editor.")
.fi
.in -6
.sa
loccom(2)
.di
none
#-h- imput.fmt        532  asc  25-mar-82 10:10:43  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Imput (3) 23-Mar-80
place token into in-memory sort area
.sy
integer function imput(table, buf)

pointer table
character buf(ARB)
.ds
`imput' places the token passed in `buf' into the in-memory
sort area pointed to by `table', which was returned as the function value
of an `iminit' call.  If there is room for the token, a value of OK is
returned as the function value; otherwise, a value of ERR is returned.
.sa
iminit(3), imget(3), imsort(3)
.di
If there is no room for the token, a value of ERR is returned.
#-h- imrset.fmt       402  asc  25-mar-82 10:10:43  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Imrset (3) 14-Mar-82
reset in-memory read pointer
.sy
subroutine imrset(table)

pointer table
.ds
`imrset' resets the in-memory read pointer, such that the
next `imget' call will start reading at the beginning of the in-memory
sort area.
`table' must have been obtained by a call to `iminit'.
This function is equivalent to rewinding an input file.
.sa
iminit(3), imget(3)
.di
none
#-h- imsort.fmt       506  asc  25-mar-82 10:10:44  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Imsort (3) 23-Mar-80
sort tokens in in-memory sort area
.sy
subroutine imsort(table)

pointer table
.ds
`imsort' sorts the string tokens stored in the in-memory
sort area pointed to by `table', which was returned as the function
value of a previous `iminit' call.  The strings are sorted according
to the ASCII collating sequence, with all characters being significant.
Upon completion, the tokens may be fetched via `imget' calls in sorted
order.
.sa
iminit(3), imput(3), imget(3)
.di
#-h- imuniq.fmt       444  asc  25-mar-82 10:10:45  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Imuniq (3) 14-Mar-82
unique sorted in-memory array
.sy
subroutine imuniq(table)

pointer table
.ds
`imuniq' scans the in-memory array generated via `imput'
calls, and possible sorted by a call to `imsort', eliminating adjacent
duplicate lines.  `table' must have been obtained by a call to `iminit'.
This is the same function as provided by the `uniq' utility for files.
.sa
iminit(3), imput(3), imsort(3), uniq(1)
.di
none
#-h- incrdi.fmt       538  asc  25-mar-82 10:10:46  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Incrdi (3) 15-Mar-82
increment double integer array
.sy
incrdi(dblint)

integer dblint(2)

expands into:

.in +6
{
dblint(2) = dblint(2) + 1
if (dblint(2) >= 10000)
.in +2
{
dblint(1) = dblint(1) + 1
dblint(2) = 0
}
.in -2
}
.in -6
.ds
Invocation of this macro causes the double integer argument
to be incremented by one, with the appropriate carry into the high
integer, if necessary.  See the entry for `initdi' for more information
on the double integer structure.
.sa
initdi(3), decrdi(3), adddi(3), subdi(3)
.di

#-h- index.fmt        434  asc  25-mar-82 10:10:47  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Index (3) 13-Nov-78
find character c in string str
.sy
loc = index(str, c)

character str(ARB), c
integer loc is returned as the location is str where c was located
.ds
Returns the index of the first character in 'str' that matches 'c',
or zero if 'c' isn't in the array.
'Str' is an ascii character array terminated with an EOS marker.
'c' is a single ascii character.
.sa
match(3), getpat(3), indexs(3)
.di
None
#-h- indexs.fmt       531  asc  25-mar-82 10:10:47  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Indexs (3) 15-Mar-82
return index of substring in character string
.sy
integer function indexs(str, sub)

character str(ARB), sub(ARB)
.ds
`indexs' scans the string `str' for the first occurrence
of the substring `sub', and returns the index into `str' where `sub'
starts.  If the substring is not found, a value of 0 is returned.
The comparison is stricly character by character, as done in `strcmp'
or `equal'.
.sa
strcmp(3), equal(3), index(3)
.di
If the substring cannot be found, a value of 0 is returned.
#-h- inihlp.fmt       693  asc  25-mar-82 10:10:48  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Inihlp (3) 23-Mar-80
initialize help facility on help archive
.sy
integer function inihlp(file, ptrara, ptrsiz, unit)

integer ptrsiz
linepointer ptrara(ptrsiz)
filedes unit
character file(FILENAMESIZE)
.ds
`inihlp' opens `file' at READ access, and notes the
disk address of each archive header in the linepointer array, `ptrara'.
If the number of headers is larger than `ptrsiz', only `ptrsiz' addresses
are noted.  The ratfor unit for using `mrkhlp' and `puthlp' is
returned in `unit'.  If the file could not be opened, ERR is returned
as the function value; otherwise, OK is returned.
.sa
mrkhlp(3), puthlp(3), note(2)
.di
If the file cannot be opened, ERR is returned.
#-h- initdi.fmt       886  asc  25-mar-82 10:10:49  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Initdi (3) 15-Mar-82
initialize double integer array
.sy
initdi(dblint)

integer dblint(2)

expands into:

.in +6
{
dblint(1) = 0
dblint(2) = 0
}
.in -6
.ds
This macro expansion causes the double integer array
argument to be initialized for use in the other double integer macros
and routines.  The double integer construct is used by all utilities
which have to count quantities which might be larger than a 16-bit
integer (32767), which seems to be most things of counting interest.
.sp
The format of the double integers is:
.sp
.in +3
.ti -2
* the second element of the array varies from 0 to 9999
.sp
.ti -2
* the first element of the array is the carry from the second element
.sp
.in -3
In this manner, up to 327,679,999 units of things can be counted before
16-bit architectures overflow.
.sa
incrdi(3), decrdi(3), adddi(3), subdi(3), ctodi(3), ditoc(3)
.di

#-h- inpack.fmt       485  asc  25-mar-82 10:10:50  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Inpack (3) 14-Mar-82
initialize data for packing subroutines
.sy
subroutine inpack(nxtcol, rightm, buf, fd)

filedes fd
integer nxtcol, rightm
character buf(MAXLINE)
.ds
`inpack' initializes the parameters for packing data using
`dopack' and `flpack'.  These routines pack words into a buffer, aligned
in columns starting every 16 characters, using TAB characters to achieve
the spacing.  `inpack' sets `nxtcol' to 1, and returns.
.sa
dopack(3), flpack(3)
.di
none
#-h- itoc.fmt         578  asc  25-mar-82 10:10:51  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Itoc (3) 13-Nov-78
convert integer to character string
.sy
length = itoc(int, str, size)

integer int, size
character str(ARB)
integer length returned as the number of characters needed
.ds
Converts an integer 'int' to characters in array 'str', which
is at most 'size' characters long.
'length' is returned as the number of characters the integer
took, not including the EOS marker.
Characters are stored in ascii character arrays terminated with
an EOS marker.

Negative numbers are handled correctly.
.sa
ctoi(3), putdec(3), putint(3), gitocf(3)
.di
None
#-h- length.fmt       309  asc  25-mar-82 10:10:52  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Length (3) 13-Nov-78
compute length of string
.sy
n = length(str)

character str(ARB)
integer n returned as the number of characters in str
.ds
Computes the length of a character string, excluding the EOS.
The string is an ascii character array terminated with an EOS
marker.
.sa
.di
None
#-h- logpmt.fmt       535  asc  25-mar-82 10:10:52  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Logpmt (3) 23-Mar-80
`prompt' with history mechanism
.sy
integer function logpmt(pstr, buf, fd)

character pstr(ARB), buf(MAXLINE)
filedes fd
.ds
`logpmt' is semantically the same as `prompt', with the
addition that is keeps a log of each line returned to the user, and
permits the user to recall and edit lines previously entered.
The writeup for `hsh', the history shell, may be consulted for the
syntax of the history manipulating commands.
.sa
prompt(2), rawpmt(3), ledpmt(3), hsh(1)
.di
Same as for prompt(2).
#-h- lookup.fmt      1294  asc  25-mar-82 10:10:53  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Lookup (3) 23-Mar-80
retrieve information from a symbol table
.sy
integer function lookup (symbol, info, table)
character symbol (ARB)
integer info (ARB)
pointer table
.ds
'Lookup' examines the symbol table given as its third argument for the
presence of the character-string symbol given as its first argument.
If the symbol is not present, 'lookup' returns 'NO'.
If the symbol is present, the information associated with it is copied
into the information array passed as the second argument to 'lookup',
and 'lookup' returns 'YES'.
.sp
The symbol table used must have been created by the routine 'mktabl'.
The size of the information array must be at least as great as the
symbol table node size, specified at its creation.
.sp
Note that all symbol table routines use dynamic storage space, which
must have been previously initialized by a call to 'dsinit'.
.im
'Lookup' calls 'stlu' to determine the location of the symbol in the
table.
If 'stlu' returns NO, then the symbol is not present, and 'lookup'
returns NO.
Otherwise, 'lookup' copies the information field from the appropriate
node of the symbol table into the information array and returns
YES.
.am
info
.ca
stlu
.sa
enter(3), delete(3), mktabl(3), rmtabl(3), stlu(3),
sctabl(3), dsinit(3), dsget(3), dsfree(3)
#-h- ludef.fmt        573  asc  25-mar-82 10:10:54  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Ludef (3) 14-Mar-82
look up a defined symbol, returning its definition
.sy
integer function ludef(name, defn, table)

character name(ARB), defn(ARB)
pointer table
.ds
`ludef' looks up `name' in the symbol table `table', returning
its definition in `defn'.  If the symbol is found, a value of YES is returned
as the function value, otherwise, NO.  `defn' is assumed to be large enough
to hold the definition stored.  `table' must have been obtained by a
call to `mktabl'.
.sa
mktabl(3), entdef(3)
.di
Returns a value of NO if the symbol cannot be found.
#-h- makpat.fmt      1070  asc  25-mar-82 10:10:55  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Makpat (3) 23-Jul-80
prepare regular expression for pattern matching
.sy
integer function makpat(arg, from, delim, pat)

character arg(ARB), delim
integer   from, pat(MAXPAT)
.ds
Makpat is similar to getpat, but slightly more general purpose.
It is used to translate a regular expression into a format
convenient for subsequent pattern matching via 'match'
or 'amatch'.
(For a complete description of regular expressions, see the
writeup on the editor.)
.sp
Makpat scans "arg" starting at location "from" and terminates
the scan at the 'delim' character.
The characters between arg(from) and the delimiter are
then encoded into a pattern suitable for subsequent
matching.
The function returns an index into arg of the next character
past the delimiter, or ERR if there was some problem encoding
the pattern.
.sp
The pattern array should be dimensioned at least MAXPAT
integers long, a definition available in the standard
symbol definitions file.
.sa
getpat(3), match(3), amatch(3)
.di
A value of ERR is returned if a failure occurs in the encoding.
#-h- maksub.fmt       689  asc  25-mar-82 10:10:56  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Maksub (3) 15-Mar-82
make substitution string
.sy
integer function maksub(arg, from, delim, sub)

character arg(ARB), sub(MAXPAT)
integer from
.ds
Starting at `arg(from)', a substitution string is encoded into
`sub' until the `delim' character is sensed in `arg'. The next available
character position in `arg' is returned as the value of the function.
If an error occurs in the encoding, a value of ERR is returned.  This
function is concerned with encoding the ditto character '&' and the tagged
patterns (those of the form $1 ;.. $9).
it also handles escaped characters (@c).
.sa
getsub(3), ed(1)
.di
A value of ERR is returned if the encoding fails for any reason.
#-h- match.fmt        872  asc  25-mar-82 10:10:57  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Match (3) 23-Mar-80
match pattern anywhere on a line
.sy
integer function match (lin, pat)

character lin(ARB)
integer   pat(MAXPAT)
.ds
'Match' attempts to find a match for a regular expression
anywhere in a given line of text.
The first argument contains the text line;
the second contains the pattern to be matched.
The function return is YES if the pattern was found anywhere in
the line, NO otherwise.
.sp
The pattern in 'pat' is a standard Software Tools encoded regular
expression.
'Pat' can be generated most conveniently by a call to the routine
'makpat'.
.im
'Match' calls 'amatch' at each position in 'lin', returning
YES whenever 'amatch' indicates it found a match.
If the test fails at all positions, 'match' returns NO.
.ca
amatch(3)
.bu
Not exactly blindingly fast.
.sa
amatch(3), makpat(3), maksub(3), catsub(3), find(1), ch(1), ed(1)
#-h- mktabl.fmt      1374  asc  25-mar-82 10:10:58  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Mktabl (3) 23-Mar-80
make a symbol table
.sy
pointer function mktabl (nodesize)
integer nodesize
.ds
'Mktabl' creates a symbol table for manipulation by the routines
'enter', 'lookup', 'delete', and 'rmtabl'.
The symbol table is a general means of associating data with a symbol
identified by a character string.
The sole argument to 'mktabl' is the number of (integer) words of
information that are to be associated with each symbol.
The function return is the address of the symbol table in
dynamic storage space (see 'dsinit' and 'dsget').
This value must be passed to the other symbol table routines to
select the symbol table to be manipulated.
.sp
If an allocation failure occurs, the value LAMBDA is returned.
.sp
Note that dynamic storage space must be initialized by a call to
'dsinit' before using any symbol table routines.
.im
'Mktabl' calls 'dsget' to allocate space for a hash table in dynamic
memory.
Each entry in the hash table is the head of a linked list (with zero
used as a null link) of symbol table nodes.
'Mktabl' also records the nodesize specified by the user, so
'enter' will know how much space to allocate  when a new symbol
is entered in the table.
.ca
dsget
.sa
enter(3), lookup(3), delete(3), rmtabl(3), stlu(3),
dsget(3), dsfree(3), dsinit(3), sctabl(3)
.di
If an allocation failure occurs, the value LAMBDA is returned.
#-h- mrkhlp.fmt       790  asc  25-mar-82 10:10:59  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Mrkhlp (3) 23-Mar-80
mark help elements matching pattern
.sy
integer function mrkhlp(unit, ptrara, key, outara)

linepointer ptrara(ARB), outara(ARB)
filedes unit
character key(ARB)
.ds
`mrkhlp' goes through the set of archive modules pointed to
by `ptrara' and copies those which match the pattern specified by `key'
into `outara', terminating the list with an element having the value
NULLPOINTER.  If the key is one of the strings "%" or "?", all elements in
`ptrara' are copied into `outara'; otherwise, only the module with a name
which matches `key' exactly (via an `equal' call) is copied.  If none
of the modules match `key', ERR is returned; otherwise, OK is returned.
.sa
inihlp(3), puthlp(3), equal(3)
.di
If none of the modules match `key', ERR is returned.
#-h- ngetch.fmt       474  asc  25-mar-82 10:11:00  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Ngetch (3) 23-Mar-80
get a (possibly pushed back) character
.sy
character function ngetch(c, fd)

character c
filedes fd
.ds
`ngetch' fetches the next character into the variable `c'
and also returns it as its value.  If there are any characters on the
push back buffer, the most recently pushed back character will be returned
and removed from the buffer.
.sa
putbak(3), pbstr(3), pbinit(3), pbdecl(3)
.di
If an end of file is reached, EOF is returned.
#-h- pbdecl.fmt       713  asc  25-mar-82 10:11:01  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Pbdecl (3) 15-Mar-82
declare push-back buffer storage
.sy
PB_DECL(Buffer_size)

expands into:
.sp
.in +6
integer pbp, pbsize
character pbbuf(Buffer_size)

common / cpback / pbp, pbsize, pbbuf
.in -6
.ds
Invocation of this macro causes the buffer and associated
variables needed by the push-back buffer routines to be declared.
This macro expansion must appear in the modules which invoke the
`pbinit' routine.
The same value of `Buffer_size' must be used in the `pbinit' call
that is used in the PB_DECL declaration.
.sp
`Buffer_size' must have been defined prior to the expansion of the
macro, usually by a statement of the form:

.ce
define(Buffer_size,512)

for example.
.sa
pbinit(3)
.di

#-h- pbinit.fmt       586  asc  25-mar-82 10:11:02  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Pbinit (3) 23-Mar-80
initialize push-back buffer
.sy
subroutine pbinit(bufsiz)

integer bufsiz
.ds
`pbinit' permits the user to initialize the push-back
buffer without knowledge of its implementation.  After initialization,
`ngetch', `putbak' and `pbstr' may be used.
The following declaration must be made in the module which calls
`pbinit' to create the common block which these routines use:
.ce
PB_DECL(bufsiz)
This declaration causes a character array `bufsiz' characters to be
created for use by the routines.
.sa
ngetch(3), putbak(3), pbstr(3), pbdecl(3)
.di
#-h- pbstr.fmt        545  asc  25-mar-82 10:11:03  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Pbstr (3) 23-Mar-80
push string onto push back buffer
.sy
subroutine pbstr(in)

character in(ARB)
.ds
`pbstr' pushes the characters in the string `in' onto the
push back buffer, from which they will be retrieved via future `ngetch'
calls.  If there is insufficient room in the buffer for the characters,
an error message to that effect is displayed and the program terminated.
.sa
pbinit(3), putbak(3), ngetch(3), pbdecl(3)
.di
If there is no room for the string, an error message is displayed and the
program is terminated.
#-h- putbak.fmt       490  asc  25-mar-82 10:11:03  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Putbak (3) 23-Mar-80
push character onto push back buffer
.sy
subroutine putbak(c)

character c
.ds
`putbak' pushes `c' onto the push back buffer, from which it will
be removed via a future `ngetch' call.  If there is no room for the character,
an error message will be displayed to that effect and the program terminated.
.sa
pbinit(3), pbstr(3), ngetch(3), pbdecl(3)
.di
If there is no room for the character, an error message is displayed and
the program terminated.
#-h- putc.fmt         459  asc  25-mar-82 10:11:04  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Putc (3) 10-Nov-78
write character to standard output
.sy
call putc (c)

character c
.ds
Putc
writes a character onto the standard output file (STDOUT).
If
c
is a NEWLINE character,
the appropriate action is taken to indicate the end of the record
on the file.
The character is assumed to be in ascii format; however, if
the output file is not ascii, characters are mapped
into their corresponding format.
.sa
putch(2), putlin(2)
.di
None
#-h- putdec.fmt       428  asc  25-mar-82 10:11:05  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Putdec (3) 13-Nov-78
write integer n in field width >=w
.sy
call putdec(n, w)

integer n, w
.ds
This routine writes onto the standard output the number 'n'
as a string of at
least 'w' characters, including a sign if 'n' is negative.
If fewer than 'w' characters are needed, blanks are inserted to
the left to make up the count; if more than 'w' are needed, more
are provided.
.sa
itoc(3), putint(3)
.di
None
#-h- puthlp.fmt       594  asc  25-mar-82 10:11:06  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Puthlp (3) 23-Mar-80
output marked modules from help archive
.sy
subroutine puthlp(unit, outara, key, out, putout)

linepointer outara(ARB)
filedes unit, out
character key(ARB)
external putout
.ds
`puthlp' outputs the help archive entries marked in `outara'
onto ratfor unit `out' using the external routine `putout' via calls of
the form
.ce
call putout(buf, out)
in a format depending upon `key'.
If `key' is the string "%", only the first line of each marked entry is
output; otherwise, the second through n-th lines of each entry is output.
.sa
inihlp(3), mrkhlp(3)
.di
#-h- putint.fmt       582  asc  25-mar-82 10:11:06  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Putint (3) 23-Jul-80
write integer n onto file fd in field width >=w
.sy
call putint( n, w, fd)

integer n, w, fd
.ds
This routine writes on the file specified by 'fd' the number 'n'
as a string of at
least 'w' characters, including a sign if 'n' is negative.
If fewer than 'w' characters are needed, blanks are inserted to
the left to make up the count; if more than 'w' are needed, more
are provided.
If 'w' is negative, the number is left-justified in the field.
.sp
'Fd' is a a file descriptor as returned by open or create.

.sa
itoc(3), putdec(3)
.di
None
#-h- putlnl.fmt       399  asc  25-mar-82 10:11:07  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Putlnl (3) 16-Mar-82
output line and flush, if necessary
.sy
subroutine putlnl(buf, fd)

character buf(ARB)
filedes fd
.ds
`putlnl' calls `putlin' to output the line.  It then
checks to see if the last character in the buffer is a NEWLINE ('@n');
if not, it outputs a NEWLINE character to flush the line.  If `buf'
is empty, a NEWLINE character is output.
.sa
putlin(2)
.di
None
#-h- putptr.fmt       299  asc  25-mar-82 10:11:08  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Putptr (3) 15-Mar-82
output linepointer as a character string
.sy
subroutine putptr(ptr, fd)

linepointer ptr
filedes fd
.ds
`putptr' formats the linepointer `ptr' using `ptrtoc', and
outputs the resulting string to the ratfor unit `fd'.
.sa
ptrtoc(2), note(2), seek(2)
.di
none
#-h- putstr.fmt       594  asc  25-mar-82 10:11:09  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Putstr (3) 23-Jul-80
write str onto file fd in field width >=w
.sy
call putstr( str, w, fd)

character str(ARB)
integer w, fd
.ds
Putstr writes the character string 'str' onto the file
specified by 'fd',
in a field at least 'w' characters long.
If fewer than 'w' characters are needed, blanks are inserted to
the left to make up the count; if more than 'w' are needed, more
are provided.
If 'w' is negative, the characters are left-justified in the field.
.sp
'Fd' is a a file descriptor as returned by open or create.

.sa
putch(2), putlin(2), remark(2), error(3)
.di
None
#-h- query.fmt        782  asc  25-mar-82 10:11:10  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Query (3) 25-Sep-80
print command usage information on request
.sy
subroutine query (usage)
hollerith_string usage (ARB)
.ds
Many Software Tools commands will supply usage information
when invoked with a single argument consisting only of a question
mark.
'Query' exists to simplify this convention for the programmer.
.sp
The sole argument is a period-terminated hollerith literal,
such as that passed to 'error'.
.sp
When called, 'query' checks to see that the command calling it was
invoked with exactly one argument, and that that argument is a question
mark.
If so, the usage message is passed along to 'error' and the command
terminates.
If not, 'query' returns quietly.
.im
Two calls to 'getarg', some tests, and a call to 'error'.
.ca
error
.sa
error(3)
#-h- rmtabl.fmt      1193  asc  25-mar-82 10:11:11  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Rmtabl (3) 23-Mar-80
remove a symbol table
.sy
subroutine rmtabl (table)
pointer table
.ds
'Rmtabl' is used to remove a symbol table created by 'mktabl'.
The sole argument is the address of a symbol table in dynamic storage
space, as returned by 'mktabl'.
.sp
'Rmtabl' deletes each symbol still in the symbol table, so it is normally
not necessary to empty a symbol table before deleting it.
However, if the information associated with a symbol includes a pointer
to dynamic storage space, the space will not be reclaimed.
(This problem can be averted by scanning the symbol table with 'sctabl'
and freeing dynamic objects, then removing the symbol table with 'rmtabl'.)
.sp
Please see the manual entry for 'dsinit' for instructions on
initializing the dynamic storage space used by the symbol table
routines.
.im
'Rmtabl' traverses each chain headed by the hash table created by 'mktabl'.
Each symbol table node encountered along the way is returned to free
storage by a call to 'dsfree'.
Once all symbols are removed, the hash table itself is returned by
a similar call.
.ca
dsfree
.sa
mktabl(3), enter(3), lookup(3), delete(3), dsget(3),
dsfree(3), dsinit(3), sctabl(3)
#-h- scopy.fmt        289  asc  25-mar-82 10:11:12  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Scopy (3) 13-Nov-78
copy string at from(i) to to(j)
.sy
call scopy(from, i, to, j)

character from(ARB), to(ARB)
integer i, j
.ds
Copies the (sub)string of 'from', starting in location 'i',
into array 'to', starting at 'j'.
.sa
stcopy(3), addset(3), concat(3)
.di
None
#-h- sctabl.fmt      2067  asc  25-mar-82 10:11:13  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Sctabl (3) 16-Mar-80
scan all symbols in a symbol table
.sy
integer function sctabl (table, symbol, info, posn)
pointer table, posn
integer info (ARB)
character symbol (ARB)
.ds
'Sctabl' provides a means of accessing all symbols present in a
symbol table (c.f. 'mktabl') without knowledge of the table's
internal structure.
After a simple initialization (see below), successive calls
to 'sctabl' return symbols and their associated information.
When the return value of 'sctabl' is EOF, the entire table
has been scanned.
.sp
The first argument is the index in dynamic storage of the symbol
table to be accessed.
(This should be the value returned by 'mktabl'.)
.sp
The second and third arguments receive the character text of and
integer information associated with the symbol currently under
scan.
.sp
The fourth argument is used to keep track of the current position
in the symbol table.
It must be initialized to zero before 'sctabl' is called for the
first time for a given scan.
.sp
The function return is EOF when the entire table has been scanned,
not EOF otherwise.
.im
If 'posn' is zero, 'sctabl' assigns the location of a two-word block
in the table header to it.
These words are used to keep track of (1) the hash table bucket
currently in use and (2) the position in the bucket's list of the
next symbol.
If a symbol is available in the current list, 'sctabl'
returns its data and records the position of the next symbol in
the list;
otherwise, it moves to the next bucket and examines that list.
If there are no more buckets in the symbol table,
EOF is returned as the function value and
'posn' is set to zero.
.am
symbol, info, posn
.ca
dsget, dsfree
.bu
A call to 'enter' must be made to update the information associated
with a symbol.
If new symbols are entered or old symbols deleted during a scan,
the results are unpredictable.
The argument order is bogus; all the other symbol table routines
have the table pointer as the last argument.
.sa
lookup(3), delete(3), mktabl(3), rmtabl(3), stlu(3),
dsget(3), dsfree(3), dsinit(3)
#-h- sdrop.fmt        535  asc  25-mar-82 10:11:14  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Sdrop (3) 23-Mar-80
drop characters from a string (APL-style)
.sy
integer function sdrop (from, to, length)
character from (ARB), to (ARB)
integer length
.ds
'Sdrop' copies all but 'length' characters from the 'from' string
into the 'to' string and returns as its result the number of
characters copied.  If 'length' is positive, the omitted characters
are relative to the beginning of the 'from' string; if it is negative,
they are relative to the end of the string.
.am
to
.ca
ctoc, length
.sa
stake(3), index(3)
#-h- sdupl.fmt        504  asc  25-mar-82 10:11:15  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Sdupl (3) 14-Mar-82
duplicate a string in dynamic storage
.sy
pointer function sdupl(str)

character str(ARB)
.ds
`sdupl' allocates space for `str' in dynamic storage, and
copies the string into the allocated space.  A pointer to the dynamic
space is returned as the value of the function.  If the allocation
fails, a value of LAMBDA is returned.  `dsinit' must have been called
before this function can be called.
.sa
dsinit(3)
.di
Returns a value of LAMBDA if the allocation fails.
#-h- settab.fmt       542  asc  25-mar-82 10:11:16  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Settab (3) 15-Mar-82
set tab stops
.sy
subroutine settab(buf, tabs)

character buf(ARB)
integer tabs(MAXLINE)
.ds
`settab' reads the token found in `buf', and generates the
tab stops in the array tabs.  If `buf' is empty, tabstops are set starting
in column 9 and every 8 columns thereafter.  Consult the entries for `entab'
and `detab' for the actual arguments which can be passed in `buf'.   After
this call, `tabs' is ready for use in calling the `tabpos' routine.
.sa
argtab(3), tabpos(3), entab(1), detab(1)
.di
none
#-h- shell.fmt        278  asc  25-mar-82 10:11:16  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Shell (3) 15-Mar-82
shell sort integer array
.sy
subroutine shell(v, n)

integer n, v(n)
.ds
`shell' performs a shell sort on the array of integers found
in v(1) ... v(n).  This algorithm is to be preferred over that used in
`bubble'.
.sa
bubble(3)
.di
none
#-h- skipbl.fmt       336  asc  25-mar-82 10:11:17  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Skipbl (3) 13-Nov-78
skip blanks and tabs at str(i)
.sy
call skipbl(str, i)

character str(ARB)
integer i              # i is incremented
.ds
Starting at position 'i' of array 'str', increments i while
str(i) is a BLANK or TAB.
'Str' is an ascii character array terminated with an EOS marker.
.sa
getwrd(3)
.di
None
#-h- stake.fmt        531  asc  25-mar-82 10:11:18  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Stake (3) 23-Mar-80
take characters from a string (APL-style)
.sy
integer function stake (from, to, length)
character from (ARB), to (ARB)
integer length
.ds
'Stake' copies the number of characters specified by 'length'
from the 'from' string into the 'to' string and returns
as its result the number of characters copied.  If 'length' is
positive, the characters are copied from the beginning of
'from'; if it is negative, they are copied from the end of 'from'.
.am
to
.ca
ctoc, length
.sa
sdrop(3), index(3)
#-h- stcopy.fmt       506  asc  25-mar-82 10:11:19  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Stcopy (3) 6-Jun-79
copy string at from(i) to to(j); increment j
.sy
call stcopy(from, i, to, j)

character from(ARB), to(ARB)
integer i
integer j             # j is incremented
.ds
Copies the (sub)string of 'from', starting in location 'i',
into array 'to', starting at 'j'.
'j' is incremented to point to the next available position in
'to' (i.e. the EOS marker inserted by the copy).
In all other respects, 'stcopy' is similar to 'scopy'.
.sa
scopy(3), concat(3), addset(3)
.di
None
#-h- stlu.fmt         643  asc  25-mar-82 10:11:20  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Stlu (3) 14-Mar-82
symbol table lookup primitive
.sy
integer function stlu(symbol, node, pred, table)

character symbol(ARB)
pointer node, pred, table
.ds
`stlu' looks up the token `symbol' in the symbol table `table',
returning a pointer to the symbol in `node' if it found.  The variable `pred'
is used as a scratch pointer during the search.  If the symbol is found, a
value of YES is returned, otherwise, NO.  `table' is the return value of
`mktabl', and the symbol would have been entered by using the `enter' function.
.sa
mktabl(3), enter(3)
.di
A value of NO is returned if the symbol cannot be found in the
table.
#-h- strcmp.fmt       371  asc  25-mar-82 10:11:20  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Strcmp (3) 23-Jul-80
compare 2 strings
.sy
stat = strcmp (str1, str2)

character str1(ARB), str2(ARB)
integer stat is returned as -1, 0, or +1
.ds
Strcmp compares its aguments and returns an integer greater than,
equal to, or less than 0, depending on whether str1 is
lexicographically greater than, equal to, or less than str2.
.sa
equal(3)
.di
None
#-h- strcpy.fmt       236  asc  25-mar-82 10:11:21  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Strcpy (3) 26-Oct-81
copy string at "from" to "to".
.sy
call strcpy( from, to)

character from(ARB), to(ARB)
.ds
Copies the string starting at "from" into "to".
.sa
scopy(3), stcopy(3), addset(3), concat(3)
.di
None
#-h- strim.fmt        562  asc  25-mar-82 10:11:22  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Strim (3) 23-Mar-80
trim trailing blanks and tabs from a string
.sy
integer function strim (str)
character str (ARB)
.ds
'Strim' is used to trim trailing blanks and tabs from the EOS-terminated
string passed as its first argument.
The function return is the length of the trimmed string,
excluding EOS.
.im
One pass is made through the string, and the position of the last
non-blank, non-tab character remembered.
When the entire string has been scanned, an EOS is planted immediately
after the last non-blank.
.am
str
.sa
stake(3), sdrop(3)
#-h- subdi.fmt        548  asc  25-mar-82 10:11:23  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Subdi (3) 15-Mar-82
subtract double integer arrays
.sy
subdi(dbl1,dbl2)

integer dbl1(1), dbl2(2)

expands into:

.in +6
{
dbl2(1) = dbl2(1) - dbl1(1)
dbl2(2) = dbl2(2) - dbl1(2)
if (dbl2(2) < 0)
.in +2
{
dbl2(1) = dbl2(1) - 1
dbl1(1) = dbl1(1) + 10000
}
.in -2
}
.in -6
.ds
Invocation of this macro causes the first double integer to be
subtracted from the second.  If a carry is necessary, it is performed.
See the entry for `initdi' for more information of double integers.
.sa
initdi(3), incrdi(3), decrdi(3), adddi(3)
.di

#-h- tabpos.fmt       362  asc  25-mar-82 10:11:23  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Tabpos (3) 15-Mar-82
determine if at a tab stop
.sy
integer function tabpos(column, tabs)

integer column, tabs(MAXLINE)
.ds
This function returns YES/NO depending upon whether `column'
corresponds to a tab stop or not.  The array `tabs' must have been set
up via a call to `settab' before calling `tabpos'.
.sa
settab(3), argtab(3)
.di
none
#-h- tbinit.fmt       558  asc  25-mar-82 10:11:24  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Tbinit (3) 23-Mar-80
initialize simple lookup table
.sy
subroutine tbinit(size)

integer size
.ds
`tbinit' causes a symbol table to be created for the user
by calling `mktabl' in anticipation of calling `tbinst' and `tblook',
thus providing the same functionality as the old `lookup' and `instal'
routines from rat4 without forcing the user to worry about the dynamic
storage manipulation routines.  `size' is the size of the dynamic storage
region declared in the caller via
.ce
DS_DECL(Mem,size)
.sa
tbinst(3), tblook(3), dsdecl(3)
.di
#-h- tbinst.fmt       524  asc  25-mar-82 10:11:25  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Tbinst (3) 23-Mar-80
install (name,defn) pair in lookup table
.sy
subroutine tbinst(name, defn)

character name(ARB), defn(ARB)
.ds
`tbinst' installs the (name,defn) pair in the lookup table
initialized by a `tbinit' call.  If there is no room in the table,
the message "in tbinst: no room for new definition." is displayed and
control returned to the user.
.sa
tbinit(3), tblook(3)
.di
If there is no room for the (name,defn) pair, an error message is
displayed and control returned back to the caller.
#-h- tblook.fmt       413  asc  25-mar-82 10:11:26  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Tblook (3) 23-Mar-80
look up name in simple lookup table
.sy
integer function tblook(name, defn)

character name(ARB), defn(ARB)
.ds
`tblook' looks up `name' in the lookup table.  If found,
its definition is copied into `defn' and the value YES returned as the
function value; otherwise, NO is returned.
.sa
tbinit(3), tbinst(3)
.di
If the name is not in the table, a value of NO is returned.
#-h- tooldr.fmt       861  asc  25-mar-82 10:11:27  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Tooldr (3) 12-Mar-82
locate user-specific tool directory
.sy
subroutine tooldr(direct, dtype)

character direct(FILENAMESIZE)
integer dtype
.ds
`tooldr' returns the directory in which the caller's
tools-specific files are kept.
If `dtype' has the value LOCAL, then the string is returned in the native
operating system format; otherwise, it is returned in pathname format.
It is returned as an EOS terminated string.
.im
If the system supports Tree-structured file systems, as evidenced by
the definition of TREE_STRUCT_FILE_SYS in `~bin/symbols', then the
tools directory is obtained by calling `homdir' and appending the
string "tools/" to it.  If the system supports a flat file system,
`homdir' is simply called.
The routine is called
by `impath(3)' to build the standard search path for many of the
tools.
.sa
homdir(2), impath(3)
.di

#-h- type.fmt         312  asc  25-mar-82 10:11:28  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Type (3) 13-Nov-78
determine type of character
.sy
t = type(c)

character c
character t is returned as LETTER, DIGIT, or c
.ds
This function determines whether the character 'c' is a letter,
a digit, or something else; it returns LETTER, DIGIT, or the
character itself.
.sa
index(3)
.di
None
#-h- upper.fmt        347  asc  25-mar-82 10:11:28  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Upper (3) 13-Nov-78
convert string to upper case
.sy
call upper(str)

character str(ARB)
.ds
Converts the array 'str' to upper case, if not already there.
If any characters are non-alphabetic, it leaves them unchanged.
'Str' is an ascii character array terminated with an EOS marker.
.sa
cupper(3), fold(3), clower(3)
.di
None
#-h- wkday.fmt        512  asc  25-mar-82 10:11:29  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Wkday (3) 23-Mar-80
get day-of-week corresponding to month, day, year
.sy
integer function wkday (month, day, year)
integer month, day, year
.ds
'Wkday' is used to return the day-of-the-week corresponding to a
given date.
The three arguments completely specify the date:
the month (1-12), day (1-28, 29, 30, or 31), and year (e.g. 1980).
The function return is the ordinal number of the day-of-the-week
(1 == Sunday, 7 == Saturday).
.im
Zeller's Congruence.
.sa
getnow(2), fmtdat(3), date(1)
#-h- dstime.fmt       642  asc  02-apr-82 13:18:50  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Dstime (3) 2-Apr-82
determine if the date is daylight savings time
.sy
integer function dstime(date)

integer date(7)
.ds
`Dstime' determines whether the given date (in the format as returned
by a `getnow' call) corresponds to daylight savings time.
If this is true, a value of YES is returned, otherwise, NO.
.im
If the month specified is > 4 (April) and < 10 (October), then YES.
If the month specified is < 4 or > 10, then NO.
If the month = 4, and the day is < the last Sunday, then NO, otherwise, YES.
If the month = 10, and the day is < the last Sunday, then YES, otherwise, NO.
.ca
wkday(3)
.sa
getnow(2), wkday(3)
#-h- rmdef.fmt        341  asc  16-dec-81 22:19:13  sventek (joseph sventek)
.so ~bin/manhdr
.hd Rmdef (3) 17-Dec-82
remove a symbol and its definition from a symbol table
.sy
subroutine rmdef(symbol, table)

character symbol(ARB)
pointer table
.ds
`rmdef' removes a symbol and its definition from the symbol table `table'.
`table' must have been obtained by a call to `mktabl'.
.sa
mktabl(3), ludef(3), entdef(3)
.di