2.  SUBROUTINES AND FUNCTIONS

This section describes the use of the subroutines and functions
generally available with the software tools.
(The user should consult Section 3 for information about
linking these routines with his own programs.)

The library consists of system-independent routines as well
as a set of "primitives", those functions that are
machine-dependent and must be implemented for each local
operating system.
However, the form of invocation of the primitives is
machine-independent;
it is the implementation of the primitives themselves
that is specific to a given system.

For each primitive there is an IMPLEMENTATION section, which
describes possible implementation strategies or suggestions
to the local implementor when she is preparing the primitives
for her local system.

The SYNOPSIS subsection of each entry gives the form of
the invocation, the type of the arguments (in the form of
Fortran declarations), and the type of the returned value if
the entry is a function.
The type "character" refers to a right-justified ASCII
character, and arrays of type character are sequences of
right-justified ASCII characters, stored one per array
element, and terminated by the value of the parameter
EOS.
All software tools programs deal with only ASCII arrays, even
though the local system may use a different character type.
Conversion from local to ASCII is done in the primitives
(getch, putch).

The names of arguments are chosen to help convey the kind
of data transmitted in them.
Some commonly used names are as follows:


"fd" is used where the argument or returned value is a
file descriptor as returned by "open" or "create".
File descriptors are simply small integers used as arguments
to I/O primitives.
Their actual value is of no concern to the programmer,
other than for transmission to the primitives.

"name" or "file" is used when the argument refers to a character
string representing a file name.

"str" or "lin" is used when the argument refers to a character
string as described above.

"i", "k", "n", etc. are used when the argument or
returned value refers to an index.

"stat" or "status" is used when the argument or returned value
indicates some form of status information.
Commonly used values of status are ERR, NOERR, OK, YES, NO, etc.


Note that the names of the functions do not conform to the
usual Fortran defaults for the names of integer and
real functions.
It is therefore advisable to explicitly declare all
variables and functions used.