4.3BSD/usr/contrib/apl/doc/quadf

.LP
The following standard quad functions
are available in \*u \*a:
.IP "\*(qdcr \'name\'" 24
The result of ``\*(qdcr'' is a character array
containing the function whose name is
passed as an argument.
.IP "\*(qdfx newfn"
The contents of the character array
specified as an argument are fixed as
an \*a function.
.IP "\*(qdnc \'arg\'"
This function can be used to determine what
type of variable an \*a symbol is.  The
apl symbol must be specified inside quote
marks, as shown.  The returned value will be:
.br
0 \(em symbol is undefined
.br
2 \(em symbol is a label or variable
.br
3 \(em symbol is a function name
.br
4 \(em unknown type (should not occur)
.br
.IP "\*(qdnl arg"
The argument should be a scalar or vector
with components 1, 2, or 3.
This function returns a two-dimensional
character array containing the names of
all items whose types are specified in the
vector
(same type definitions as for ``\*(qdnc'' above).
The ordering of names in the matrix is fortuitous.
.sp 2
.LP
The following non-standard quad functions are
defined:
.IP "fd \*(qdap \'string\'" 24
This quad function is used to append a
character string onto the end of a \*u
file.  The first argument specifies the
file descriptor of the file (which should
have been opened earlier).  The second
argument is a character array which is
to be appended.  A carriage return is
automatically appended to the end of
each row of the character array when it
is appended to the end of the file.
.IP "\*(qdchdir \'directory\'"
This quad function can be used to change
\*a to another directory.  Normally, \*a
runs in the directory that you were in
when it was started by the ``apl'' command.
The argument is a character
vector specifying the new directory (there
is NO way to default this).  A 0 is returned
if the ``chdir'' was successful; a \(mi1 is
returned if it failed.
.IP "\*(qdclose fd"
This function complements ``\*(qdopen''.  The
argument is the file descriptor of a \*u
file to be closed.  This function returns
0 for success or \(mi1 for failure.
.IP "mode \*(qdcreat \'file\'"
This function creates a \*u file.  If the
file already exists, it is truncated to zero
length.  The creation mode is specified as
the first argument
The filename is specified
in a character vector as the second argument.
The file descriptor of the created file (or
\(mi1 for error) is returned.
.IP "\*(qddup fd"
This function executes the ``dup'' system
call.  It returns an integer number which
may be used as a file descriptor on later
I/O calls.
The new file descriptor
is a duplicate of the argument ``fd''.
If the argument file descriptor could not be
duplicated, \(mi1 is returned.
.IP "\*(qdexec matrix"
Takes a two-dimensional character matrix
and formats it into a \*u ``exec'' system
call.  The matrix passed as an argument
must be two-dimensional, the rows must
be \fIzero\fR terminated.
.IP "\*(qdexit code"
This quad function is used to terminate
the execution of the current process,
with the completion code ``code''.  It should
be used to terminate child processes and
can be used to terminate an \*a session;
however, it is recommended that the system command
``)off'' be used for that purpose.
.IP "\*(qdfloat charvect"
This quad function is useful in conjunction
with ``\*(qdwrite'' and ``\*(qdread''.
Although any type of
data may be written to a \*u file with
``\*(qdwrite'', when it is read with ``\*(qdread'' it
will be interpreted as character data.  This
function will convert a character array into
numeric form.  The array must be a multiple
of 4 elements long for apl2 and 8 for apl.
The converted array is the returned value.
.IP "\*(qdfork xx"
``xx'' is a dummy argument.  A ``fork'' system
call is performed.
This quad function
probably will be followed by a
``\*(qdexec'' quad function.
The process-id
of the child is returned to the parent;
a zero is returned to the child.
.IP "pid \*(qdkill signal"
This function executes the ``kill'' system
call.  The first argument specifies what
process is to be signalled.  The second
argument specifies what signal is to be
sent.  A 0 is returned for a successful
``kill''; \(mi1 is returned if the specified
process could not be found or is not
owned by the current user.
.IP "mode \*(qdopen \'file\'"
This function is dyadic.  It opens a \*u
file for use by an \*a function with calls
via ``\*(qdread'' and ``\*(qdwrite''.  The first
argument is the mode for the open (0=read,
1=write, 2=read/write).  The second
argument is a character vector containing
the file name.  The file descriptor of the
opened file is returned (\(mi1 for error).
.IP "\*(qdpipe xx"
This quad function can be used to set up
a pipe (used for interprocess communication)
It returns a 2-element vector containing
the two ``pipe'' file descriptors.
.IP "\*(qdrd fd"
This function reads one line from the
file descriptor specified.  If the line
is completely blank, a null string is
returned.  An end-of-file will also return
a null string.  Otherwise, the returned
value is the character string which was
read.
.IP "\*(qdrm \'filename\'"
The specified file will be removed,
equivalent to )drop filename.  A 0
is returned for a successful remove;
\(mi1 is returned if the file could not be
removed or does not exist.
.IP "fd \*(qdread nbytes"
This function reads a specified number
of bytes from a designated file.  The
first argument is the file descriptor;
the second is the number of bytes to be
read.  The data which is read is returned.
Note that the returned vector is always
character data \(em to convert to numeric
format see the function ``\*(qdfloat''.
.IP "\*(qdrline fd"
This quad function is identical to ``\*(qdrd'',
described above.
.IP "\*(qdrun \'unix command\'"
The argument passed to ``\*(qdrun'' is executed
as a \*u shell command.
.IP "\*(qdseek (fd,pos,mode)"
This function executes the ``seek'' system
call on a \*u file.  The argument to
``\*(qdseek'' is a three-element vector containing
the file descriptor, seek offset, and mode
A 0 is returned for
a successful seek; \(mi1 is returned if an
error is detected.
.IP "signal \*(qdsig action"
This quad function allows signal processing
to be turned on and off under \*a function
control.  The first argument is the signal
whose processing is to be changed.  The
second argument specifies how the signal
will be processed \(em if zero, the signal will
cause termination of \*a and a possible
core dump; if non-zero, the signal will be
ignored.  Note that the special way in which
interrupts and other signals are processed
by \*a is turned off by a call to ``\*(qdsig''
and cannot be turned back on.  A \(mi1 is
returned on error, a positive number or zero
for success.
.IP "\*(qdwait xx"
This quad function is used in conjunction
with ``\*(qdfork'' \(em it returns a 3-element
vector of information about a child
process which has terminated.  The first
element is either the 
process-id of a completed
child process or \(mi1 (no children).
The second is the status of the dead 
process,
and the last is the completion code.
.IP "fd \*(qdwrite data"
This function writes data to a specified
file.  The first argument is the file
descriptor; the second is the data to be
written.  The number of bytes written is
returned as the count.  Any type of data
(character or numeric) may be written in
this manner.
.LP