#-h- intro.fmt       4211  asc  25-mar-82 10:05:30  v1.1 (sw-tools v1.1)
.pl 60
.in 0
.rm 70
NAME
.ti +4
Intro - introduction to software tools primitives
.sp 20
.ce
A (Not So) Primitive Document
.sp 5
.ce 100
Joseph Sventek
Computer Science & Applied Mathematics
Lawrence Berkeley Laboratory
Berkeley, CA  94720
.ce 0
.sp 5
.in 15
.rm 55
A complete writeup of the syntax and semantics of the primitive
functions upon which the LBL Software Tools Virtual Operating System
is based.
.bp 1
.rm 70
.in 0
.he 'Intro (2)'11/17/80'Intro (2)'
.fo ''-#-''
.fi
Basic assumptions of the tools concerning data types:

.in +5
`character' is a signed integer data type of at least eight-bit accuracy.
The internal representation of characters within the programs is the
7-bit ASCII code, with EOS being traditionally defined as 0 (NULL).
This leaves 128 negative values for special flags such as EOF, ERR etc.
Msg assumes that it can use 200(8) (NULL with the high bit set) to
pad NEWLINES in raw terminal I/O.

Integers and characters are freely assigned to each other.  Since the above
assumption is made, normal FORTRAN compilers should perform this without
any side effects.

The data type `linepointer' should be defined as an intrinsic FORTRAN
data type large enough to hold the address of a record in a file.  No
arithmetic or assignments are done on linepointers, with all activities
on these entities embodied in the routines `note', `seek', `ptreq',
`ptrcpy', `ptrtoc' and `ctoptr'.  It is also assumed that a defined
symbol NULLPOINTER exists and is different from any possible valid
linepointer value.


.ti -5
Basic assumptions of the ratfor runtime system

I/O redirection flags are interpreted (and removed from the argument list)
before the tool's main routine is called.
In order to be able to pass arguments to the utility which start with the
special characters '<', '>', or '?', quoted string arguments are not
scanned when determining io redirection.
The primitives, as currently
defined, only handle character files, with the exception that `gettyp'
expects to be able to determine whether a file is BINARY or ASCII.
It is expected that the primitives will be extended in the near future
to handle ASCII, LOCAL and BINARY files unambiguously.

`getarg(0)' should return the name by which the process was invoked.  This is
useful if your system supports UNIX-style links, thus allowing an image
to act differently depending upon which alias was used for its invocation.
None of the tools currently use this capability.

The first routine to be executed is named

subroutine main

It is assumed that all I/O redirection and command line fetching have been
completed before `main' is called.  Upon completion, `main' simply returns,
which causes a return to the Tools runtime system.  In order to implement
this feature, `ld' is set up to extract a module from the library which
is the FORTRAN main program, and usually consists of the following lines:

.nf
call initst
call main
call endst(OK)
end
.fi

If such library extraction is not possible on a system, the above four
line routine will have to be added to each tool.


.ti -5
Basic assumptions concerning RAW terminal I/O

The routine `stmode' is supplied to permit the use of RAW terminal I/O.
In actuality, three modes are defined, RAW, RARE and COOKED.  COOKED
io implies that the system applies its own semantics concerning the
control characters emitted by the terminal, and performs the echo of the
characters for the user.  RARE and RAW assume that all reads are done
a character at a time, with no echo.  RARE io assumes that there are
certain control characters which the operating system will not
relinquish its control of.  These probably include XON, XOFF, terminal
interrupt characters, etc.  RARE is the mode of io used by all of the
tools currently using RAW io,
since they usually only wish to apply their
own semantics to the actual printing characters.  RAW io is handy if one
wishes to write network control programs over asynchronous lines in
ratfor (Don't laugh, it's being done!).  With RAW io, it is assumed that
the terminal driver is totally bypassed.  On many systems, this capability
requires enormous privilege and other funky resources, so none of the
commonly available tools use it.
.in -5
#-h- amove.fmt       1019  asc  25-mar-82 10:05:32  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Amove (2) 18-Aug-81
move (rename) file1 to file2
.sy
integer function amove(name1, name2)

character name1(ARB), name2(ARB)
.ds
`amove'
moves the contents of the file specified by
`name1'
to the file specified by
`name2'.
It is essentially a renaming of the file.
 
Both file names are character strings representing pathnames or
filenames in whatever format is expected by the local operating system.
The names are passed as character arrays terminated with an
EOS character.
 
The files need not be opened by (connected to) the running program to be
renamed.

The function value returned is OK is successful or ERR if not.
.im
`amove'
could be easily implemented by opening the first file,
creating the second,  copying the first to the second,
and then removing the first file.
Alternatively, if possible, it could be implemented with
a native system call to rename the file.
.sa
remove(2)
.di
If the rename fails for any reason, ERR is returned.  `name1' is removed
only if the rename succeeds.
#-h- assign.fmt      1020  asc  25-mar-82 10:05:33  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Assign (2) 18-Aug-81
open a file on the specified unit
.sy
integer function assign(name, fd, access)

character name(FILENAMESIZE)
filedes fd
integer access
.ds
`assign' is the equivalent of `open' or `create' on a
particular ratfor I/O unit.  If a file is currently open on `fd',
`assign' closes it first.  If `access' has the value of READ, `assign'
then performs an `open' on the specified unit.  If `access' has the
value of WRITE, READWRITE or APPEND, `assign' performs a `create' on
the specified unit.  The function value returned is either the value
of `fd' if successful, or ERR.
.im
There has been much debate whether `assign' should still
be in the primitive set.  The only tool which relies upon it is `sort',
since is does some fairly complex file manipulation during the external
merge phase.
.sa
open(2), create(2), close(2)
.di
If the file could not be opened or created for any reason,
the value ERR is returned.  In this case, the previous file associated
with `fd' remains closed.
#-h- brdcst.fmt       720  asc  25-mar-82 10:05:34  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Brdcst (2) 12-Mar-82
broadcast message to one or all terminals
.sy
integer function brdcst(msg, dev)

character msg(ARB), dev(ARB)

return(OK/ERR)
.ds
`brdcst' broadcasts the message in `msg' to the terminal
specified by the `dev' argument.  If `dev' is the string "all", the
message is broadcast to all logged in terminals on the system.
.im
`brdcst' is heavily dependent upon whether the operating
system supports such a notion.  In addition, some systems support broadcasts
only for very privileged users.  This routine is only used by `sndmsg' and
`mail' to notify users of mail delivery, and can safely be implemented as
a stub.
.sa
trmlst(2)
.di
Returns ERR if the message cannot be broadcast.
#-h- chmod.fmt        780  asc  25-mar-82 10:05:35  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Chmod (2) 12-Mar-82
change protection mode on file
.sy
integer function chmod( name, mode)

character name(ARB)
integer mode

return(OK/ERR)
.ds
`chmod' attempts to change the protection on the file `name'
to the value specified in `mode'.  It returns the value OK/ERR reflecting
the degree of success in the operation.
.im
The only current use of `chmod' is in the `rm' tool using
the `-f' flag.  In that situation, `mode' is passed as an integer of
all ones.  Before `chmod' can become generally useful, some
system-independent way of specifying the protection on a file needs to
be devised.  It is totally permissible to implement this as a stub
always returning the value ERR.
.sa
rm(1)
.di
Return a value of ERR if the mode change could not be performed.
#-h- closdr.fmt       416  asc  25-mar-82 10:05:35  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Closdr (2) 18-Aug-81
close an opened directory
.sy
subroutine closdr(fd)

filedes fd
.ds
`closdr' closes the directory that is currently opened and
associated with the internal descriptor `fd', which was returned by
the `opendr' function.
.im
.sa
opendr(2)
.di
If `fd' is an invalid descriptor, or if no opened directory
is currently associated with `fd', `closdr' returns with no error message.
#-h- close.fmt        803  asc  25-mar-82 10:05:36  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Close (2) 18-Aug-81
close (detach) a file
.sy
subroutine close(fd)

filedes fd
.ds
`close'
closes the connection between a file and the running program.
Any write buffers are flushed and the file is rewound.

`fd' is an internal file descriptor as returned from an
`open'
or
`create'
call.
 
.im
`close' breaks the connection between the program and a file accessed via
`open'
or
`create'.
If necessary, the file's write buffer is flushed and the end
of the file is marked so that subsequent reads will find an EOF.
If a file has been opened multiple times (that is, more than one
internal descriptor has been assigned to a file), care is
taken that multiple closes will not damage the file.
.sa
open(2), create(2)
.di
If the file descriptor is in error, the routine simply returns.
#-h- create.fmt      1164  asc  25-mar-82 10:05:37  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Create (2) 20-Aug-81
create a new file (or overwrite an existing one)
.sy
filedes function create( name, access)

character name(ARB)
integer access
.ds
`create' creates a new file from within a running program
and connects the external name of the file to an internal
identifier
which is then usable in subsequent subroutine calls.
If the file already exists, the old version will be overwritten.
In this case, the file should be truncated immediately by `create'.
 
`name' is a character string representing a pathname or filename
in whatever format is used by the local operating system.
It is passed as a character array terminated by an EOS character.
 
`access' is a integer descriptor for the type of
access desired - WRITE, READWRITE or APPEND.
 
The value returned is a "filedes" internal descriptor
to be used in subsequent I/O calls on this file.
.im
`create'
is similar to
`open'
except that
`create'
generates a new file if it does not
already exist, whereas `open' returns an error on such occasions.
.sa
open(2), close(2)
.di
The function returns ERR if the file could not be created or if
there are already too many files open.
#-h- ctoptr.fmt       449  asc  25-mar-82 10:05:38  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Ctoptr (2) 20-Aug-81
convert character string into linepointer
.sy
subroutine ctoptr(buf, i, ptr)

character buf(ARB)
integer i
linepointer ptr
.ds
`ctoptr' converts the characters starting at location
`buf(i)' into a linepointer value and stores the value in the
variable `ptr'.  The value of `i' is incremented to point to the
next available location in `buf'.
.im
.sa
ptreq(2), ptrcpy(2), note(2), seek(2), ptrtoc(2)
.di
none
#-h- cwdir.fmt        664  asc  25-mar-82 10:05:39  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Cwdir (2) 20-Aug-81
change current working directory
.sy
integer function cwdir(name)

character name(FILENAMESIZE)
.ds
`cwdir' changes the current working directory to that specified
by `name'.  `name' is a character string representing a pathname or
whatever format is expected by the local operating system.  `name' is passed
as a character array terminated by an EOS character.

The return value is either OK or ERR depending upon the success of the
operation.  If the operation fails, the current working directory should
be restored to the previous value.
.im
.sa
gwdir(2)
.di
A value of ERR is returned if the operation is unsuccessful.
#-h- delarg.fmt       538  asc  25-mar-82 10:05:40  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Delarg (2) 20-Aug-81
mask the existence of specified command line argument
.sy
subroutine delarg(n)

integer n
.ds
`delarg' masks the existence of the command line argument
number `n' so that subsequent calls to `getarg' do not see it.
.im
`delarg' works in conjunction with `getarg'.  It generally
re-orders indices to an array holding the command line arguments fetched
by `makarg'.  `delarg' is currently only used by the shell.
.sa
getarg(2), initst(2)
.di
If argument `n' does not exist, `delarg' simply returns.
#-h- enbint.fmt      1176  asc  25-mar-82 10:05:42  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Enbint (2) 20-Aug-81
enable trapping of terminal interrupts
.sy
subroutine enbint
.ds
`enbint' is used by the shell to trap interrupt characters
typed by the user at the terminal.  `enbint' assumes that there will be
a routine named `intsrv' which will be called whenever a terminal
interrupt is typed.  The canonical semantics of `intsrv' is to kill all
sub-processes of the current process and return.  This generally results
in the return of error notifications to `spawn', which returns the error
to the shell, after which the shell prompts for another command.
.im
`enbint' has been implemented on only three machines, and
is not very well defined.  In all of the implementations to date, `enbint'
checks to make sure that the caller is the top shell in the process tree
associated with the user.  This prevents `enbint' from being generally
called from other programs.  It is hoped that a firmer specification for
this routine will be available in the near future.

If this routine is difficult to implement, it may be left as a stub.
.sa
intsrv(2)
.di
If the enabling of the interrupt cannot be performed, the
current implementations simply return.
#-h- endst.fmt        566  asc  25-mar-82 10:05:43  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Endst (2) 20-Aug-81
perform system-dependent cleanup and terminate ratfor program
.sy
subroutine endst(status)

integer status
.ds
`endst' is normally implicitly called when the `main' subroutine
executes a return.  `endst' closes all open files, performs any necessary
system-dependent cleanup and terminates the program's execution.

If it is possible, endst should communicate the termination status
(OK/ERR/CHILD_ABORTED) to the outside world.

`endst' is also called by `error' to terminate the program.
.im
.sa
close(2), initst(2)
.di
none
#-h- filnfo.fmt       431  asc  25-mar-82 10:05:44  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Filnfo (2) 20-Aug-81
determine filename and access on open unit
.sy
integer function filnfo( fd, file, access)

filedes fd
integer access
character file(FILENAMESIZE)
.ds
`filnfo' returns the name and access of the file open on `fd' to
the user.  If the unit is open, `filnfo' returns OK as its value,
otherwise it returns ERR.
.im
.sa
.di
If the file specified by `fd' is not open, a value of ERR is returned.
#-h- gdraux.fmt      1998  asc  25-mar-82 10:05:46  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Gdraux (2) 20-Aug-81
get auxiliary information about a file
.sy
subroutine gdraux( fd, file, aux, date, fmtstr)

character file(FILENAMESIZE), aux(MAXLINE), date(TCOLWIDTH)
character fmtstr(ARB)
filedes fd
.ds
`gdraux' retrieves auxiliary information on a particular file
in a directory.  `fd' is the directory descriptor returned from an
`opendr' call and `file' is a filename returned from a `gdrprm' call.
The auxiliary information is returned in the character array `aux', while
`date' receives a "sortable" date string of size (TCOLWIDTH-1) which can
be used to sort files by significant date.
.sp
The information placed into `aux' is dependent upon the format string
passed in `fmtstr'.  The format string specifies the output information
as follows:
.sp
.in +3
.ti -2
b size of file in blocks (normally 512 characters)
.sp
.ti -2
c size of file in characters
.sp
.ti -2
m modification date and time (dd-mmm-yy hh:mm:ss)
.sp
.ti -2
n filename
.sp
.ti -2
o file owner's username
.sp
.ti -2
p protection codes
.sp
.ti -2
t file type (asc|bin|dir)
.in -3
.sp
The `b', `c', `n' and `o' options accept an integer prefix which
specifies the field width to be used.
.im
This is admittedly a stop-gap measure until a more
useful and penetrating primitive is devised to permit the retrieval of
extra information about a file.  The only utility which uses `gdraux'
currently is `ls', the directory lister.  The sortable date field can be
anything that the primitive implementor desires, but it is strongly
suggested that it be a sortable version of whatever significant date
the operating system keeps on the file, so that the "-t" flag in `ls'
performs up to specification.
.bp
.ex
The verbose option of `ls' uses the format string "17n p  m  6b  o".
.sa
opendr(2), gdrprm(2)
.di
If the auxiliary information cannot be obtained for a
particular file, a message to that effect is returned in
`aux', and `date' is given a value such that it will sort out first when
sorting by date.
#-h- gdrprm.fmt       882  asc  25-mar-82 10:05:48  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Gdrprm (2) 20-Aug-81
get next filename from directory
.sy
integer function gdrprm( fd, file)

character file(FILENAMESIZE)
filedes fd
.ds
`gdrprm' retrieves the next sequential filename from the open
directory associated with `fd' and places it in the character array `file'
as an EOS-terminated string.  If there is an error reading the directory
or no more filenames are contained in the directory, a value of EOF is
returned; otherwise, OK is returned.  The filenames are retrieved
sequentially, with no particular order (alphabetic, by date, etc.)
guaranteed.
.im
If there are lots of noise characters (version numbers,
null extensions, etc.), these are often stripped from the filename before
it is returned.
.sa
gdraux(2), opendr(2)
.di
A value of EOF is returned whenever there are no more directory
entries or an error reading the directory is detected.
#-h- getarg.fmt      1918  asc  25-mar-82 10:05:50  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Getarg (2) 20-Aug-81
get command line arguments
.sy
integer function getarg( n, array, maxsiz)

character array(maxsiz)
integer n, maxsiz
.ds
`getarg'
gets command arguments from the command line or control card
and copies the `n'th command line argument into the character array
`array',
terminating it with an EOS character.
`maxsiz'
is passed as the maximum
number of characters `array' is prepared to deal with (including
the EOS character);  `getarg' truncates the argument if necessary
to fit into the space provided.
The number or characters in the argument (not including
the EOS character) is returned in the functional call.
If there are
less than
`n'
arguments, EOF is returned.
Calling `getarg' with `n' having the value of 0 should result in the
return of the name by which the image was invoked.
.im
The implementation of 'getarg' may be quite different on different operating
systems.
Some systems allow only upper case (or lower case) on the command line;
they may limit size; they may not even provide access at all without
considerable contortions.
 
When implementing `getarg', the designer should keep in mind that
a `delarg' will also be needed.
One possible design would be to create a routine `makarg', which would
pick up the arguments from the system, convert them to ascii strings,
handle any upper-lower case escape conventions, and store them in an
array.
`getarg' could then access this array, stripping off any quoted strings
surrounding the arguments, and passing them along to the user.
`delarg' could also access this array when removing reference to
arguments.
 
If it is absolutely impossible to pick up command line arguments from
the system, `getarg' could be taught to prompt the user for them.
 
When the shell is implemented, `getarg' (or perhaps `makarg')
may have to be altered to read arguments as passed from the shell.
.sa
initst(2), delarg(2)
.di
none
#-h- getch.fmt        912  asc  25-mar-82 10:05:51  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Getch (2) 20-Aug-81
read character from file
.sy
character function getch( c, fd)

character c
filedes fd
.ds
`getch'
reads the next character from the file specified by
`fd'.
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 unit `fd' is a RAW or RARE terminal unit, then getch actually gets
the next character from the terminal WITH NO ECHO.
.im
Interspersed calls to
`getch' and `getlin'
should interleave properly.
A common implementation is to have
`getlin' make repeated calls to `getch'.
 
If the input file is not ASCII, characters are mapped
into their ASCII equivalent.
.sa
getlin(2), putch(2), putlin(2), stmode(2)
.di
If an error occurs during the reading of the file, the value ERR is
returned.
#-h- getdir.fmt       929  asc  25-mar-82 10:05:52  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Getdir (2) 26-Oct-81
get directory string for known Tools directory
.sy
subroutine getdir( key, dtype, name)

character name(FILENAMESIZE)
integer key, dtype
.ds
`getdir' returns the directory string for any of the known
Tools directories.  The directory string is returned as a character array
terminated by an EOS character.  The format of `name' is determined by
the value of `dtype', with LOCAL generating a string in local format, and
PATH causes a pathname directory string to be returned.  The valid values
of `key' and their corresponding directories are:
.nf
.in +10

BINDIRECTORY   ~bin/
USRDIRECTORY   ~usr/
TMPDIRECTORY   ~tmp/
LPRDIRECTORY   ~lpr/
MSGDIRECTORY   ~msg/
MANDIRECTORY   ~man/
SRCDIRECTORY   ~src/
INCDIRECTORY   ~inc/
LIBDIRECTORY   ~lib/
.in -10
.fi

If an invalid key is specified, a null string is returned.
.im
.sa
.di
If an invalid key is specified, a null string is returned.
#-h- getlin.fmt      1743  asc  25-mar-82 10:05:53  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Getlin (2) 21-Aug-81
get next line from file
.sy
integer function getlin( line, fd)

character line(MAXLINE)
filedes fd
.ds
`getlin' copies the next line from the file specified by the
internal identifier `fd' into the character array `line'.  Characters
are copied until a NEWLINE character is found or until MAXLINE-1
characters have been copied.  The characters are returned with the
character array terminated by an EOS character.

`getlin' returns EOF when it encounters an end-of-file, otherwise
it returns the line length (including NEWLINE, excluding EOS).

Interspersed calls to `getlin' and `getch' are permitted and
should work properly.
.im
If the external representation of characters is not ASCII, the
characters are mapped into their ASCII equivalents.

`getlin' assumes a maximum size (MAXLINE) of the array `line'.  If the
input line exceeds the limit, only the first "limit-1" characters
are returned, with the remainder of the line either being ignored or
returned on the next `getlin' call.
 
A common implementation is to have
`getlin'
call getch until a NEWLINE character is found
(or the buffer size is exceeded or EOF is reached).
 
If the underlying disk structure is record oriented (as opposed to stream
oriented), it may be more efficient to have `getlin' get the next
record in the same way that `getch' does, to avoid the overhead of
repeated calls to `getch'.

Use of `getlin' on RAW terminal units is of questionable utility, since
the repeated `getch' calls perform a READ WITH NO ECHO, and would only
terminate when the user types a CTRL/J (LINEFEED) character.  All
utilities which use RAW I/O have their own line gathering routines.
.sa
getch(2), putch(2), putlin(2), stmode(2)
.di
none
#-h- getnow.fmt      1114  asc  25-mar-82 10:05:54  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Getnow (2) 20-Aug-81
determine current date and time
.sy
subroutine getnow (now)

integer now (7)
.ds
'Getnow' is used to query the operating system for the current date
and time.
The requested information is returned in a seven-word integer array,
where:
.in +5
.nf

word 1 contains the year (e.g. 1980);
word 2 contains the month (e.g. 9);
word 3 contains the day (e.g. 25);
word 4 contains the hour (e.g. 13);
word 5 contains the minute (e.g. 39);
word 6 contains the second (e.g. 14);
word 7 contains the millisecond (e.g. 397).
.in -5
.fi

The information returned by 'getnow' may be used as-is or further
useful processing may be done by 'fmtdat' or 'wkday'.
.im
Operating systems generally have some mechanism for picking
up the current date and time.
If yours has one, use it.

Getnow is not critical to the implementation of the tools and
can be left as a stub if the operating system cannot supply
the needed information.
.am
now
.bu
Some systems cannot obtain all the time information described.
Array elements that cannot be filled default to zero.
.sa
fmtdat(3), wkday(3), date(1)
#-h- gettyp.fmt      1403  asc  25-mar-82 10:05:56  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Gettyp (2) 20-Aug-81
get type of file
.sy
integer function gettyp( fd, type)

filedes fd
integer type
.ds
`gettyp' determines whether the file opened on unit `fd' is ascii
characters (ASCII), local characters (LOCAL, if different from ASCII)
or binary(BINARY).  The type is returned as the value of the function and
as the value of the parameter `type'.  If the file is empty or new,
ASCII is returned.

`fd' is the file identifier returned from an `open' or `create' call.
.im
When a file is opened (via a call to
`open' or `create'),
an internal flag is usually set which specifies the file type.
`gettyp' then simply reads the flag.
The file type may have been determined by locating system information
about the file or by actually reading part of it and making a
reasonable guess.
 
`gettyp' is called by the archiver to store a file's type in the
archiver header.  The shell also uses `gettyp' to determine whether
a command verb given by the user represents a script file or an
image file.  If the verb corresponds to a character file, the shell
spawns itself with the file as input.  If `gettyp' cannot be implemented
on a particular system, a stub returning BINARY should be placed in the
library, which will force the user to execute script files in the following
manner:
.sp
% sh <script ...
.sa
create(2), open(2)
.di
ERR is returned if the file descriptor is incorrect.
#-h- gtmode.fmt       367  asc  25-mar-82 10:05:57  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Gtmode (2) 20-Aug-81
determine mode of ratfor unit
.sy
integer function gtmode(fd)

filedes fd
.ds
`gtmode' determines the mode of io on the unit `fd', returning one
of the values RAW, RARE or COOKED.  If the unit is not currently opened,
the value ERR is returned.
.im
.sa
stmode(2)
.di
If `fd' is not currently open, a value of ERR is returned.
#-h- gtzone.fmt       370  asc  25-mar-82 10:05:57  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Gtzone (2) 12-Mar-82
get time zone of requestor
.sy
subroutine gtzone(buf)

character buf(4)
.ds
`gtzone' returns to the requestor the 3-character mnemonic
for the time zone, terminated by an EOS character.
.im
A typical way of implementing this routine is to
simply strcpy a string into the buffer.  This routine may return a
null string.
.sa

.di

#-h- gwdir.fmt        535  asc  25-mar-82 10:05:58  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Gwdir (2) 20-Aug-81
get current working directory
.sy
subroutine gwdir( name, dtype)

character name(FILENAMESIZE)
integer dtype
.ds
`gwdir' returns the current working directory string in
`name'.  If `dtype' has the value LOCAL, the directory string is returned
in the form desired by the local operating system.  If `dtype' has the
value of PATH, the directory string is returned in pathname format.  The
directory string is returned as a character array terminated by an
EOS character.
.im
.sa
cwdir(2)
.di
none
#-h- homdir.fmt       579  asc  25-mar-82 10:05:58  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Homdir (2) 20-Aug-81
return the home directory for this process
.sy
subroutine homdir(home, dtype)

character home(FILENAMESIZE)
integer dtype
.ds
`homdir' returns the home directory string for the 
current process.
If `dtype' has the value LOCAL, the directory string is returned
in the form native to the local operating system; a value of PATH causes
it to be returned in pathname format.
It is returned as an EOS
terminated string.  If this information cannot be determined, a
stub which returns an EOS in home(1) will suffice.
.im
.sa
tooldr(3)
.di
none
#-h- initst.fmt      1134  asc  25-mar-82 10:05:59  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Initst (2) 20-Aug-81
initialize ratfor runtime environment
.sy
subroutine initst
.ds
Normally, `initst' is implicitly called before the
main subroutine of the user's program is called.  `initst' opens
STDIN, STDOUT and ERROUT, performing any redirections specified in
the command line and masking those redirections from the current process.
The remainder of the command line arguments are prepared for retrieval
via `getarg', and any other system-dependent initialization is performed.
.im
The standard I/O units are generally opened in the order
ERROUT, STDIN and STDOUT.  If an error occurs during the opening of ERROUT,
some system-dependent method of reporting the error will need to be used,
whereas if an error occurs while opening STDIN or STDOUT, ERROUT can be
used to report it.  The fetching of command line arguments from the
operating system is in the domain of `initst', as well as any initializations
of common data areas needed by the other primitive functions.
.sa
endst(2), getarg(2), delarg(2)
.di
If `initst' cannot function for some reason, the program should
abort with a diagnostic message.
#-h- intsrv.fmt       817  asc  25-mar-82 10:06:00  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Intsrv (2) 20-Aug-81
interrupt service routine for tty interrupts
.sy
subroutine intsrv
.ds
`intsrv' is the routine called whenever a terminal interrupt
character has been typed after `enbint' has been called to enable the
trapping of these interrupts.  The canonical semantics of `intsrv' is to
kill all sub-processes of the current process.  Other functions may be
embedded in `intsrv'.
.im
`enbint' and `intsrv' are not very well
defined.  It is hoped that their definitions will become firmer in the
near future.

If `enbint' has been implemented as a stub, then `intsrv' may also be
implemented as such.
.sa
enbint(2)
.di
If during the course of its duties, `intsrv' encounters an error,
it should notify the user in some way.  This may be tricky, due to the
asynchronous nature of its work.
#-h- isatty.fmt       711  asc  25-mar-82 10:06:01  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Isatty (2) 20-Aug-81
determine if file is an interactive device
.sy
integer function isatty(fd)

filedes fd
.ds
`isatty' returns the value YES if the file specified by `fd'
is an interactive device, otherwise it returns NO.  `fd' is a file
identifier returned by a call to `open' or `create'.
.im
When a file is opened, a flag is usually set indicating
what device the file is associated with.  `isatty' usually just reads this
flag.

`isatty' is used by several tools (`ls', `ar' and `users') to  determine
whether to format their output in columns or not.  It may also be used
to determine whether to prompt for input or not.
.sa
open(2), create(2)
.di
NO is returned if `fd' is in error.
#-h- loccom.fmt      1117  asc  25-mar-82 10:06:02  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Loccom (2) 20-Aug-81
locate command along specified search path
.sy
integer function loccom( in, spath, suffix, out)

character in(FILENAMESIZE), out(FILENAMESIZE), spath(ARB)
character suffix(ARB)
.ds
`loccom' searches for the command passed as an EOS-terminated
character array in `in' along the search path specified by `spath',
returning the fully-qualified file specification in the character array
`out'.
For each element of the search path, all suffixes passed in `suffix' are
appended to `in' and an open at READ access is attempted.
The type of the file thus found (ASCII or BINARY) is returned
as the value of the function.  If the command cannot be found, the value
ERR should be returned and the string `in' copied to `out'.

The structure of `spath' and `suffix' is:

string_1@estring_2@e...string_N@e@n

where `@e' represents an EOS character and `@n' represents a NEWLINE
character.  A null directory name indicates searching the current
working directory.
.im
.sa
spawn(2)
.di
If the command cannot be found, a value of ERR is returned
and the command string is returned in `out'.
#-h- mailid.fmt       920  asc  25-mar-82 10:06:03  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Mailid (2) 20-Aug-81
return username
.sy
subroutine mailid(user)

character user(USERSIZE)
.ds
`mailid' returns the name of the user of the current process as an EOS
terminated string.  This name is then used by the mail system.
.im
Most operating systems permit the user to determine some unique identifier
of the person (or account) on whose behalf the current process is running.
The third field of each entry in the mail system's database file is
dedicated to such an identifier, so that mailid could be implemented
by determining the identifier, opening ~msg/address and reading records
until an entry with that identifier is found, and returning the username
(field one of the record) in the array `user'.  `mailid' is essential
for the correct working of the mail system.
.sa
homdir(2)
.di
If the record could not be found in the database, some nonsense username
should be returned in `user'.
#-h- mklocl.fmt       481  asc  25-mar-82 10:06:04  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Mklocl (2) 20-Aug-81
convert string to fully qualified local file specification
.sy
call mklocl( in, out)

character in(FILENAMESIZE), out(FILENAMESIZE)
.ds
`mklocl' converts the input filename `in', which may be
in pathname format or a partial local file specification, to a
fully qualified local file specification.
.im
Initially, `mklocl' could be a stub, simply `scopy'ing
`in' to `out'.  `mklocl' is used by the tools `fc' and `ld'.
.sa
mkpath(2)
.di
none
#-h- mkpath.fmt       451  asc  25-mar-82 10:06:06  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Mkpath (2) 17-Nov-80
convert string to fully resolved path name
.sy
call mkpath(in, out)

character in(FILENAMESIZE), out(FILENAMESIZE)
.ds
`mkpath' converts the input filename `in', which may be
in pathname format or a partial local file specification, to a
fully qualified pathname.
.im
Initially, `mkpath' could be a stub, simply `scopy'ing
`in' to `out'.  `mkpath' is used by the tools `alist' and `ls'.
.sa
mklocl(2)
.di
None
#-h- note.fmt        1256  asc  25-mar-82 10:06:07  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Note (2) 13-Nov-78
determine current file position
.sy
stat = note (offset, fd)

linepointer offset
filedes fd
integer stat returned as OK/ERR
.ds
Note determines the current value of a file's read/write pointer.
The argument "offset" is a linepointer that will receive
the information.
Offset is maintained untouched by the user and passed to "seek"
when desiring to return to that particular location in the file.
.sp
Note is usually used as the file is being written,
picking up the pointer
to the end of the file before each record is inserted there.
.sp
On text files (e.g. those created by calls to putch, putlin),
note is guaranteed to work at line boundaries only.
However, it should work anywhere on a file created by calls
to writef.
.im
Note
is compatible with whatever implementation is chosen for
seek
and
the opening of files at READWRITE access.
.sp
Offset is a linepointer in which is stored a character count,
word address, block and record address, or whatever is appropriate
for the local operating system.
Note should be taught to return BEGINNING_OF_FILE and END_OF_FILE
where appropriate.
.sp
In the editor, note is called to locate the end of file for
subsequent writes.
.sa
seek(2), readf(2), writef(2)
.di
None
#-h- open.fmt        2234  asc  25-mar-82 10:06:09  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Open (2) 20-Aug-81
open an existing file
.sy
filedes function open( name, access)

character name(ARB)
integer access
.ds
`open' attaches an existing file to a running program and associates
the external file name with an internal identifier for use in other
I/O routines.  Several opens of a file at READ access are permitted.

`name' is a character string representing a pathname or filename in
whatever format is used by the local operating system.  It is passed
as a character array terminated with an EOS character.

`access' is a descriptor for the type of access desired - READ, WRITE,
READWRITE or APPEND.

The returned value of the function is a "filedes" descriptor to be used
in other I/O routines when referring to this file.

The file is positioned at the beginning, unless APPEND access is
specified, in which case the file is prepared for extension.
.im
`open' connects the file to the running program and
performs those manipulations
necessary to allow reading and/or writing to the file.
An internal descriptor is assigned to the file
and subsequently
used when calling other primitives such as close, getch, putch,
getlin, and putlin.
 
`open' may have to set up an internal I/O buffer for the file.
It may also have to do an initial read to determine the file
type (ASCII or BINARY).
Information about the file's type and
teletype characteristics (YES or NO) is generally maintained.
This information is then made available to the user via the
`gettyp' and `isatty' functions.
 
`open' is generally taught to read characters of ASCII type as well as LOCAL
character type (if different from ASCII).
Translation of characters from LOCAL to ASCII is done
in getch/getlin and vice versa for putch/putlin.
 
There is generally a limit to the maximum number of files
open at any one time.
None of the tools require more than 7.
 
READWRITE access may cause problems.  
Both `ed' and `msg' use this access on their scratch buffer files.  If
necessary, you may have to implement these functions by opening the
file twice, one at READ and once at WRITE access.
.sa
create(2), close(2)
.di
`open' returns ERR if the
file does not exist, if the file is not readable/writable or if
too many files are open.
#-h- opendr.fmt      1024  asc  25-mar-82 10:06:10  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Opendr (2) 20-Aug-81
open directory for reading filenames
.sy
filedes function opendr( name, fd))

character name(FILENAMESIZE)
filedes fd
.ds
`opendr' opens the specified directory for READ access via
`gdrprm'.  All write access to directories is implicitly done with
the `amove', `create' and `remove' primitives.
`name' is a character string
representing the directory as a pathname or whatever format is
expected by the local operating system.  The name is passed as a
character array terminated by an EOS character.

`fd' is a "filedes" descriptor for use in other directory manipulation
primitives.  The value returned by the function is the value of `fd'
or ERR.
.im
`opendr' is the directory equivalent to `open' at READ
access.  It prepares the directory for sequential access to the filenames
stored there.
.sa
closdr(2), gdrprm(2), gdraux(2), amove(2), create(2), remove(2)
.di
A value of ERR is returned if the directory could not be
opened, or too many directories have already been opened.
#-h- prompt.fmt      1585  asc  25-mar-82 10:06:11  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Prompt (2) 20-Aug-81
get next line from file, prompting if a terminal
.sy
integer function prompt( pstr, line, fd)

character pstr(ARB), line(MAXLINE)
filedes fd
.ds
`prompt' is identical to `getlin', with the exception that if `fd'
corresponds to a terminal unit, the prompt string `pstr' will be
displayed before the read is performed.  The line read will be
placed in `line' with the possible return values being identical with
those of `getlin'.  If `fd' does not correspond to a terminal unit,
`prompt' simply performs a `getlin'.

There is no implicit <CARRIAGE-RETURN, LINEFEED> pair at the end of
the prompt string (otherwise, there would be no need for this primitive).
If embedded NEWLINES are found in the
prompt string, they should result in <CARRIAGE-RETURN, LINEFEED> pairs
being output on the terminal at the appropriate locations.

If after outputting the prompt string and reading the line `prompt'
sees the NEWLINE character preceeded by an '@', the '@' should be
replaced by a BLANK, a secondary prompt string consisting of
pstr(1) followed by an '_' (underscore) should be displayed, and
another line fetched into the buffer after the inserted BLANK.
This process should be repeated until the NEWLINE is not escaped, or
MAXLINE characters have been fetched.
.im
The output of the prompt string is conditionalized upon
.ce
isatty(fd) == YES
Since `fd' generally is associated with an `open' at READ access,
`prompt' may have to temporarily open a unit to the terminal at
WRITE access in order to display the prompt string.
.sa
putlin(2)
.di
none
#-h- ptrcpy.fmt       241  asc  25-mar-82 10:06:12  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Ptrcpy (2) 20-Aug-81
copy linepointers
.sy
subroutine ptrcpy( in, out)

linepointer in, out
.ds
`ptrcpy' copies the linepointer variable `in' to the
linepointer variable `out'.
.im
.sa
ptreq(2), note(2), seek(2)
.di
none
#-h- ptreq.fmt        351  asc  25-mar-82 10:06:13  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Ptreq (2) 20-Aug-81
determine if two linepointers are equal
.sy
integer function ptreq( ptr1, ptr2)

linepointer ptr1, ptr2
.ds
`ptreq' checks for the equality of the two linepointers passed
as `ptr1' and `ptr2'.  If they are equal, the value YES is returned,
otherwise NO is returned.
.im
.sa
ptrcpy(2), note(2), seek(2)
.di
none
#-h- ptrtoc.fmt       598  asc  25-mar-82 10:06:13  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Ptrtoc (2) 20-Aug-81
format linepointer into characters
.sy
integer function ptrtoc( ptr, buf, size)

linepointer ptr
character buf(size)
integer size
.ds
`ptrtoc' generates a printable character string which represents
the value of the linepointer variable `ptr'.  The characters are placed in
the buffer `buf'.  If the formatted buffer would exceed `size' characters
(including the EOS), only `size' characters are placed in `buf'.  The
length of the formatted string is returned as the value of the function.
.im
.sa
ptreq(2), ptrcpy(2), note(2), seek(2), ctoptr(2)
.di
none
#-h- putch.fmt        825  asc  25-mar-82 10:06:14  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Putch (2) 20-Aug-81
write character to file
.sy
subroutine putch( c, fd)

character c
filedes fd
.ds
`putch' writes the character `c'
onto the file specified by `fd'.
If `c'
is the 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; if
the external representation is not ASCII, the necessary conversion
is done.

If fd' corresponds to a RAW or RARE terminal unit, the character `c' is
immediately written to the terminal with no interpretation by the
native operating system's terminal handler.
.im
Interspersed calls to `putch' and `putlin'
should work properly.
.sa
putlin(2), getch(2), getlin(2), stmode(2)
.di
If an error occurs when a record is flushed, an ugly error message will
appear on your terminal.
#-h- putlin.fmt       955  asc  25-mar-82 10:06:15  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Putlin (2) 20-Aug-81
output a line onto a given file
.sy
subroutine putlin( line, fd)

character line(ARB)
filedes fd
.ds
`putlin' outputs the character array `line' onto the file specified by
`fd'.  `line' is an ASCII character array terminated with an EOS
character.  NEWLINE characters are permitted in the array, with the effect
of flushing the record since the last NEWLINE character.  If none is
specified, no carriage-return (or end-of-record) is assumed.  If the
external representation is not ASCII, translation occurs before writing
the record.

If `fd' is a RAW or RARE mode terminal unit, the `line' buffer is written
immediately to the terminal, with no interpretation by the terminal
driver.
.im
Interspersed calls to `putch' and `putlin' are permitted.  A common
implementation for COOKED mode units is to have `putlin' call `putch'
until an EOS character is found.
.sa
putch(2), getch(2), getlin(2), stmode(2)
.di
none
#-h- readf.fmt        872  asc  25-mar-82 10:06:16  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Readf (2) 20-Aug-81
read from an opened file
.sy
count = readf( buf, n, fd)

character buf(ARB)
integer n
filedes fd
integer count returned as count/EOF
.ds
Readf reads `n' bytes from the file opened on file
descriptor `fd' into the array `buf'.
The bytes are placed in `buf' one per array element.
Readf is the typical way of doing binary reads on files.
Readf returns the number of bytes actually read.
In most cases, this is equal to `n'.
However, it may be less if an EOF has been encountered or if
`fd' specified a device such as a terminal where less than
`n' bytes were input.
.im
Readf is the typical way of implementing binary I/O.
Do whatever is necessary on your system to allow users
to get at the file directly.

If reasonable, design readf to work properly in conjunction
with getch and getlin.
.sa
writef(2), getch(2), putch(2)
.di
none
#-h- remark.fmt       772  asc  25-mar-82 10:06:17  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Remark (2) 20-Aug-80
print single-line message
.sy
subroutine remark(messag)

character messag(ARB)
.ds
`remark' writes the message onto the standard error file ERROUT.
A NEWLINE is always generated, even though one may not appear in
the message.
 
The `messag' array is generally a Fortran hollerith string in the
format generated by the Ratfor quoted string capability.
It may also be an character array terminated with an EOS character.
.im
If a quoted string is used as the argument to remark, it should, by
convention, be terminated by a PERIOD (`.').  This permits all implementations
to locate the end of the string to print.  If a NEWLINE character is not
found at the end of the string, one must be `putch'ed to ERROUT.
.sa
putlin(2)
.di
none
#-h- remove.fmt       843  asc  25-mar-82 10:06:18  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Remove (2) 20-Aug-81
delete a file from the file system
.sy
integer function remove(name)

character name(FILENAMESIZE)

return(OK/ERR)
.ds
`remove' deletes a file from the file system when invoked from a
running program.  `name' is a character string representing a
pathname or filename in whatever format is used by the local
operating system.  It is passed as a character array terminated
by an EOS character.
.sp
The function value returned should be OK/ERR depending upon the success
of the delete operation.  Deletion of a non-existent file should result
in a return of OK.
.im
The file to be removed need not be opened before remove is called.  If the
file is currently open on other units, remove should display an error
message.
.sa
open(2), close(2), create(2)
.di
If an error occurs, a value of ERR is returned.
#-h- scratf.fmt      1301  asc  25-mar-82 10:06:19  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Scratf (2) 20-Aug-81
generate unique scratch file name
.sy
subroutine scratf( seed, name)

character seed(ARB), name(FILENAMESIZE)
.ds
`scratf' is used to generate unique scratch file names.  `seed' is
passed as a character array terminated by an EOS character, and will
be used to make this scratch file name unique with respect to other
scratch files generated by this process.  The scratch file name generated
is returned in `name' as an EOS-terminated character array.  Only the
first three (3) characters of `seed' are guaranteed to be used, so the
user should be sure that all `seed's used in the program are unique in
the first three characters.
.im
`scratf' is used to avoid conflicts which occur when more than
one user is logged in under a single user or directory name.  The optimal
implementation would be to return an absolutely unique file name based upon
`seed', which can often be achieved via some manipulation of the process
name or id.  It is common practice to have all scratch files generated by
the tools reside in a common scratch file directory.

On single-user systems or systems which support the notion of "local files",
`scratf' can simply return `seed' as `name'.
.sa
getdir(2)
.di
If the file name could not be generated, a message should be
printed.
#-h- seek.fmt         709  asc  25-mar-82 10:06:20  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Seek (2) 20-Aug-81
move read/write pointer
.sy
subroutine seek( addres, fd)

linepointer addres
filedes fd
.ds
`seek' positions the file specified by `fd' for a
subsequent read or write beginning at `addres'.  `addres' is a
variable of type linepointer containing the system-dependent
address of the record, which was originally obtained by a call
to `note'.

If a write is performed after a `seek', the file is truncated after
that line, due to the sequential nature of the Tool's I/O.
.im
`seek' is generally used on files opened at READWRITE
access.  The units of `addres' are chosen to be whatever is most
appropriate for the system involved.
.sa
note(2), ptrcpy(2), ptreq(2)
.di
none
#-h- sleep.fmt        510  asc  25-mar-82 10:06:20  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Sleep (2) 20-Aug-81
stop process for period of time
.sy
subroutine sleep(secnds)

integer secnds
.ds
`sleep' causes the current process to suspend itself for the period
of time specified in the parameter `secnds'.  Control resumes at the
next instruction after the call sleep statement when the time
period has elapsed.
.im
The only utility which uses `sleep' is `sched'.  Therefore, it is not
necessary, although such a facility will make many real-time tasks
easier to solve
.sa
.di
none
#-h- spawn.fmt       3376  asc  25-mar-82 10:06:22  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Spawn (2) 20-Aug-81
initiate sub-process
.sy
integer function spawn( image, args, pid, waitfl)

character image(FILENAMESIZE), args(ARGBUFSIZE), pid(PIDSIZE), waitfl
.ds
`spawn' causes the initiation of a sub-process.  `image' is
an EOS-terminated character array specifying the filename of the image
to be initiated, in either pathname or local file format.

`args' is a character array specifying the command line to be passed to
the sub-process.  The name by which the image was invoked should be the
first word in the argument buffer.  If the string passed in `image' is
equal to the string "local", then `args' should contain the native command
line to be passed to the local command language interpreter.

If `waitfl' == WAIT & equal(image, "local") == NO, `spawn' should
scan `args' for redirection of STDOUT and ERROUT.  If either of these
units are not redirected, the corresponding unit should be closed, and
an APPEND redirection to that file should be formatted into `args' for
the child.  When the child process completes, the unit should be re-opened
at APPEND access, thus permitting the correct interleaving of output
on these units between parent and child processes.

`pid' is an array to receive the process id of the spawned sub-process.
This id may then be used in other process control primitives.

`waitfl' is a flag indicating whether the parent process wishes to
synchronize its execution with the termination of the sub-process.
If the value of WAIT is specified, `spawn' will not return control until
the sub-process has completed.  If NOWAIT is specified, `spawn' immediately
returns to the caller (for use with real pipes).  Processes spawned with
this flag are required to exit when the parent process exits.  If BACKGR
is specified, the sub-process is spawned in the background and control
is immediately returned to the caller.  Background process come to life
with the standard I/O units directed to the null device, and have an
existence totally independent of that of the parent.  It is common to
have the background processes run at a lower priority than foreground
processes.

If an error occurs during the initiation of the sub-process,
ERR is returned to the user.
If the
sub-process abnormally exits when WAIT has been specified, a value of
CHILD_ABORTED
is returned.  Otherwise, OK is returned.
.im
`spawn' is normally the most difficult primitive to
implement.  A few of the major obstacles which must be overcome are:

.in +5
.ti -3
1. Does the operating system permit a running process to spawn a
sub-process?  If it provides a multi-user, interactive environment,
it most certainly could, but it may not be common knowledge as to
how to do it.

.ti -3
2. Once one has determined how to spawn the process, it is necessary to
determine how to control it.  If the operating system does not provide
any synchronization methods, they must be implemented.

.ti -3
3. Finally, one must determine how to communicate the arguments and
environment information to the sub-process.  This generally entails
an exploration of the system-provided interprocess-communication
mechanisms, and often requires the invention of better ones.
.in -5
.sa
.di
A value of ERR is returned if an error occurs during
sub-process initiation.  If the sub-process exits abnormally
when `waitfl' had a value of WAIT, CHILD_ABORTED is returned.
#-h- stmode.fmt       904  asc  25-mar-82 10:06:24  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Stmode (2) 20-Aug-81
change mode on terminal unit to RAW/RARE/COOKED
.sy
integer function stmode( fd, mode)

filedes fd
integer mode
.ds
`stmode' is used to change an open ratfor unit, `fd', to a
different mode of operation, as specified by `mode'.
The default mode when a unit is opened or
created is COOKED.  If the unit corresponds to an interactive device, it is
permitted to change the mode to RARE or RAW.  The value to which the
mode is set is returned as the value of the function.
.im
`stmode' usually sets a flag for the particular unit,
such that future `getch' and `putch' calls on the unit will be performed
correctly for the given mode of operation.  If the unit specified is not
currently associated with a particular file, the value of ERR will be
returned.
.sa
getch(2), putch(2)
.di
If the unit is not currently associated with a file, the value
of ERR is returned.
#-h- symbols.fmt    10838  asc  25-mar-82 10:06:28  v1.1 (sw-tools v1.1)
.in 0
.pl 60
.rm 72
.bp 1
.he "Symbols (2)"18-Aug-81"Symbols (2)"
NAME
.ti +4
Symbols - standard symbol definitions
.sp
.nf
#================= GENERAL SYMBOL DEFINITIONS =================

# General definitions for software tools
# Should be put on a file named 'symbols'
# Used by all the tools; read automatically by preprocessor


#   Many of these symbols may change for your particular machine.
#   The values provided are intended as guidelines, and may
#   well serve you adequately, but don't hesitate to change them if
#   necessary.

# In particular, the following might have to change for your system:
#         TERMINAL_IN
#         TERMINAL_OUT
#         MAXLINE
#         FILENAMESIZE
#         DRIVER    and    DRETURN
#         MAXOFILES
#         character

#   Also, watch out for the following definitions, which
#   may conflict with the Fortran operators on your system:
#       AND         OR        NOT


#  Many of the definitions will be used in character variables.
#  They must be defined to be something other than a valid ascii
#  character--such as a number > 255 or a negative number.
#  If you have defined "character" to be "integer", then you may
#  use either a very large number or a small negative number.
#  If you have defined "character" to be something like an 8-bit
#  signed field, you'll need to use negative numbers.
#  Use of a standard integer (whatever is the default size on your
#  machine) is STRONGLY recommended, despite the apparent waste of
#  storage.


# The following constants affect conditional pre-processing

define(VAX_VMS,)		# Define CPU and Operating system.
define(LARGE_ADDRESS_SPACE,)	# this is defined if the user has at least
				# 18 address bits for use
define(TREE_STRUCT_FILE_SYS,)	# this is defined is the file system is
				# tree structured
define(SORTED_DIRECTORIES,)	# defined if the directories are inherently
				# sorted

# ASCII control character definitions:

define(NUL,0)
define(SOH,1)
define(STX,2)
define(ETX,3)
define(EOT,4)
define(ENQ,5)
define(ACK,6)
define(BEL,7)
define(BS,8)
define(HT,9)
define(LF,10)
define(VT,11)
define(FF,12)
define(CR,13)
define(SO,14)
define(SI,15)
define(DLE,16)
define(DC1,17)
define(DC2,18)
define(DC3,19)
define(DC4,20)
define(NAK,21)
define(SYN,22)
define(ETB,23)
define(CAN,24)
define(EM,25)
define(SUB,26)
define(ESC,27)
define(FS,28)
define(GS,29)
define(RS,30)
define(US,31)
define(SP,32)
define(DEL,127)

# Synonyms for ASCII control characters

define(BACKSPACE,8)
define(BELL,7)
define(BLANK,32)
define(CARRIAGE_RETURN,13)
define(NEWLINE,10)
define(RUBOUT,127)
define(TAB,9)

# Printable ASCII characters:

define(ACCENT,96)
define(AMPER,38)	# ampersand
define(AMPERSAND,AMPER)
define(AND,AMPER)
define(ATSIGN,64)
define(BACKSLASH,92)
define(BANG,33)		# exclamation mark
define(BAR,124)
define(BIGA,65)
define(BIGB,66)
define(BIGC,67)
define(BIGD,68)
define(BIGE,69)
define(BIGF,70)
define(BIGG,71)
define(BIGH,72)
define(BIGI,73)
define(BIGJ,74)
define(BIGK,75)
define(BIGL,76)
define(BIGM,77)
define(BIGN,78)
define(BIGO,79)
define(BIGP,80)
define(BIGQ,81)
define(BIGR,82)
define(BIGS,83)
define(BIGT,84)
define(BIGU,85)
define(BIGV,86)
define(BIGW,87)
define(BIGX,88)
define(BIGY,89)
define(BIGZ,90)
define(CARET,94)
define(COLON,58)
define(COMMA,44)
define(DASH,45)		#same as MINUS
define(DIG0,48)
define(DIG1,49)
define(DIG2,50)
define(DIG3,51)
define(DIG4,52)
define(DIG5,53)
define(DIG6,54)
define(DIG7,55)
define(DIG8,56)
define(DIG9,57)
define(DOLLAR,36)
define(DQUOTE,34)
define(EQUALS,61)
define(ESCAPE,ATSIGN)		# escape char for ch, find, tr, ed, and sh.
define(GREATER,62)
define(LBRACE,123)
define(LBRACK,91)
define(LESS,60)
define(LETA,97)
define(LETB,98)
define(LETC,99)
define(LETD,100)
define(LETE,101)
define(LETF,102)
define(LETG,103)
define(LETH,104)
define(LETI,105)
define(LETJ,106)
define(LETK,107)
define(LETL,108)
define(LETM,109)
define(LETN,110)
define(LETO,111)
define(LETP,112)
define(LETQ,113)
define(LETR,114)
define(LETS,115)
define(LETT,116)
define(LETU,117)
define(LETV,118)
define(LETW,119)
define(LETX,120)
define(LETY,121)
define(LETZ,122)
define(LPAREN,40)
define(MINUS,45)
define(NOT,BANG)	# used in pattern matching; choose ~, ^, or !
define(OR,BAR)
define(PERCENT,37)
define(PERIOD,46)
define(PLUS,43)
define(QMARK,63)
define(RBRACE,125)
define(RBRACK,93)
define(RPAREN,41)
define(SEMICOL,59)
define(SHARP,35)
define(SLASH,47)
define(SQUOTE,39)
define(STAR,42)
define(TAB,9)
define(TILDE,126)
define(UNDERLINE,95)


# Ratfor language extensions:

define(andif,if)
define(ARB,1000)
define(character,logical*1)	# define character data type
define(CHARACTER,character)
define(DS_DECL,integer $1($2);character c$1(arith($2,*,CHAR_PER_INT));
equivalence (c$1(1),$1(1));common/cdsmem/$1)
define(PB_DECL,integer pbp, pbsize; character pbbuf($1);
common/cpback/pbp, pbsize, pbbuf)
define(cvt_to_cptr,(CHAR_PER_INT*($1-1)+1))	# convert pointer to char ptr
define(elif,else if)
define(filedes,integer)		# file descriptor/designator data type
define(FILEDES,filedes)
define(IS_DIGIT,(DIG0<=$1&$1<=DIG9))	# valid only for ASCII!
define(IS_LETTER,(IS_UPPER($1)|IS_LOWER($1)))
define(IS_LOWER,(LETA<=$1&$1<=LETZ))
define(IS_UPPER,(BIGA<=$1&$1<=BIGZ))
define(long_real,double precision)
define(linepointer,real*8)
define(NULLPOINTER,-1)
define(LINEPTRSIZE,MAXCHARS)
define(pointer,integer)
define(POINTER,integer)



# Input/output modes:

define(APPEND,4)
define(PRINT,5)		# print file access
define(READ,1)
define(READWRITE,3)
define(WRITE,2)


# Standard input/output ports:

define(ERROUT,3)	# standard error file
define(STDERR,ERROUT)
define(STDIN,1)		# standard input file
define(STDOUT,2)	# standard output file


# TERMINAL_IN and TERMINAL_OUT are the names of the I/O channels
# from and to the user's terminal, respectively.  It's highly likely
# there is no such thing on your system; in this case, simply invent
# a name that is not likely to conflict with any file name.
# For example, the VAX/VMS version of the tools uses "TT", the RSX/11M
# version uses "TI:", the DEC 10 version uses "tty:", and the Prime
# version uses "/dev/tty".
# Note that you must make the 'open' primitive recognize this name
# and provide access to the terminal accordingly.

define(TTY_NAME,"TT")
define(TERMINAL_IN,TTY_NAME)
define(TERMINAL_OUT,TTY_NAME)


# Manifest constants included for readability and modifiability:

define(ALPHA,-9)
define(ASCII,12)		# flag for ascii character file
define(BEGINNING_OF_FILE,-2)	# flag to seek for positioning at
				# the beginning of a file
define(BINARY,60)		# flag for indicating binary file
define(CHILD_ABORTED,101)	# possible status return from spawn
define(DIGIT,2)
define(END_OF_FILE,-1)		# flag to seek for positioning at
				# end of file
define(EOF,-1)
define(EOS,0)
define(ERR,-3)
define(HUGE,30000)		# some arbitrarily large number
define(LAMBDA,0)		# end of list marker
define(LETTER,1)
define(LOCAL,6)			# flag for local-type character file
define(NO,0)
define(NOERR,0)			# flag for successful completion
define(OK,0)			# success flag
define(PATH,5)			# type == PATH
define(TMO,-4)			# error return for timeout (dpm 8-Jun-81)
define(USERSIZE,20)		# size of username returned by userid
define(YES,1)


# Size limiting definitions for important objects:

define(FILENAMESIZE,100)	# max characters in file name
				# (including EOS)
define(MAXARG,MAXLINE)		# max size of command line argument
define(MAXARGS,25)		# some tools require this for max no of args
define(MAXCHARS,20)		# max nbr of chars when converting
				# from integers to characters
				# (used by putint, outnum, etc.)
define(MAXLINE,512)		# normal size of line buffers;
				# must be at least 1 more than MAXCARD
define(MAXCARD,arith(MAXLINE,-,1))
define(MAXNAME,FILENAMESIZE)	# max size of file name
define(MAXOFILES,15)		# max nbr opened files allowed at a time
define(MAXPAT,128)		# max size of encoded patterns
				# (used in string matching)
define(NCHARS,33)		# number of special characters


# Machine-dependent parameters: (VAX)

define(BITS_PER_CHAR,8)
define(BITS_PER_WORD,32)	# (dpm 8-Jun-81)
define(CHARS_PER_WORD,4)	# (dpm 8-Jun-81)
define(CHAR_PER_INT,4)
define(MAX_INTEGER,1073241823)	# 2**30 - 1 (dpm 8-Jun-81)
define(MIN_INTEGER,-1073241824) # -2**30 - 1 (dpm 8-Jun-81)
define(MAX_REAL_EXP,38)
define(MIN_REAL_EXP,-37)	# (dpm 8-Jun-81)
define(REAL_PRECISION,7)	# (dpm 8-Jun-81)


# DRIVER is defined as those things you need to do to start a Software
# Tools program running.  The following is a common approach, but you
# may have to change it (for example, by adding a "program" card).
# Many machines will require no special driver procedure other than
# the call to 'initst'.

define(DRIVER,subroutine main # $1)

# DRETURN is used to finish up a Software Tools program:

define(DRETURN,return)		# (returning from subroutine defined in DRIVER)


# Definitions for 'spawn' primitive (if implemented):

define(WAIT,LETW)		# wait for subprocess to complete
define(NOWAIT,LETN)		# control returns as soon as
				# subprocess starts
define(BACKGR,LETB)		# spawning a background process
define(PIDSIZE,9)
define(ARGBUFSIZE,512)


# rawmode io definitions

define(COOKED,0)		# line-at-a-time (record) io
define(RAW,1)			# char-at-a-time (unfiltered) io
define(RARE,2)			# char-at-a-time (with interrupts) io

# definitions for obtaining directory strings

define(BINDIRECTORY,1)
define(USRDIRECTORY,2)
define(TMPDIRECTORY,3)
define(LPRDIRECTORY,4)
define(MSGDIRECTORY,5)
define(MAILDIRECTORY,5)
define(MANDIRECTORY,6)
define(SRCDIRECTORY,7)
define(INCDIRECTORY,8)
define(LIBDIRECTORY,9)

# definitions needed for directory operations

define(TCOLWIDTH,24)		# width of date string returned by gdraux
define(MAXDIRECTS,10)		# max number of path fields in file spec

# definitions needed for double integer manipulations

define(initdi,{$1(1) = 0; $1(2) = 0})
define(incrdi,{$1(2) = $1(2) + 1; if($1(2) >= 10000)
{$1(1) = $1(1) + 1; $1(2) = 0}})
define(decrdi,{$1(2) = $1(2) - 1; if($1(2) < 0)
{$1(1) = $1(1) - 1; $1(2) = 9999}})
define(adddi,{$2(1) = $2(1) + $1(1); $2(2) = $2(2) + $1(2);
if ($2(2) >= 10000){$2(1) = $2(1) + 1; $2(2) = $2(2) - 10000}})
define(subdi,{$2(1) = $2(1) - $1(1); $2(2) = $2(2) - $1(2);
if ($2(2) < 0){$2(1) = $2(1) - 1; $2(2) = $2(2) + 10000}})

# It may be necessary to add special definitions; for example
# names of important directories, substitute routine names for
# Software Tools primitives that conflict with local subprograms,
# etc.

define(putc,putch($1,STDOUT))
define(getc,ifelse($1,,getch,getch($1,STDIN)))
define(putdec,putint($1,$2,STDOUT))
define(index,indexx)
define(INDEX,index)
define(SS_NORMAL,1)
define(BOTH_SUFFIX,".sh@e.exe@e@n")
define(IMAGE_SUFFIX,".exe@e@n")
define(NO_SUFFIX,"@e@n")
define(mkuniq,scratf)
# special definitions for pwait
define(ANDWAIT,51)
define(ORWAIT,50)
define(TERMSGSIZE,21)
.fi
#-h- trmlst.fmt       676  asc  25-mar-82 10:06:34  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Trmlst (2) 12-Mar-82
list terminal a user is logged onto
.sy
integer function trmlst(user, tlist)

character user(ARB), tlist(ARB)

return(number of terminals found)
.ds
`trmlst' scans the system for the names of all terminals
upon which `user' is logged onto, and returns the names as blank-separated
tokens in the array `tlist'.  The number of terminals found is returned
as the value of the function.
.im
As for `brdcst', this may be a difficult function to
provide.  It may be safely implemented as a stub returning 0.  It is
only used by `sndmsg' and `mail' to notify users of mail.
.sa
brdcst(2)
.di
Returns 0 if the user is not currently logged in.
#-h- writef.fmt       742  asc  25-mar-82 10:06:35  v1.1 (sw-tools v1.1)
.so ~bin/manhdr
.hd Writef (2) 20-Aug-81
write to an opened file
.sy
count = writef( buf, n, fd)

character buf(ARB)
integer n
filedes fd
integer count returned as count/ERR
.ds
Writef writes `n' bytes from the array `buf' to the file
opened on file descriptor `fd'.
Writef is the typical way of doing binary writes to files.

Writef returns the number of bytes actually written.
In most cases, this is equal to `n'.
If, however, a write error occurs, writef returns ERR.
.im
Writef is the typical way of implementing binary I/O.
Do whatever is necessary on your system to allow users
to get at the file directly.

If reasonable, design writef to work properly in conjunction
with putch and putlin.
.sa
readf(2), putch(2), putlin(2)
.di
none