.th K_device_function II 4/21/86
.sh NAME
K_device_function \- perform arbitrary I/O function
.sh "MODULA SYNOPSIS"
.nf
 CONST od: openDescriptor;
 CONST funct: ioFunction;
 CONST blockNo: fBlockNumber;
 CONST inP: p_block;
 CONST outP: p_block;
 CONST id: asyncId;
 VAR errs: ioStatus;
 VAR bytesDone: cardinal;
 VAR status: K_err_num;
 ...
 status := NK_device_function(od, funct, blockNo, inP, outP,
           id, errs, bytesDone);
.sp
.sh "C SYNOPSIS"
 openDescriptor od;
 int funct;
 long blockNo;
 pblock inp;
 pblock outp;
 int id;
 ioStatus errs;
 int bytes;
 int status;
 ...
 status = K_device_function(od, funct, blockNo, &inp, &outp,
          id, &errs, &bytes);
.sp
.fi
.sh DESCRIPTION
K_device_function can be used for performing all I/O functions.  There
are a number of I/O functions, some of which have meaning only for
certain devices.  The parameter blocks inP and outP define the memory
areas to be used for input (into memory) and output (from memory).
Either or both parameter blocks may be null (size = 0) depending on the
requirements of the I/O function.
.sh "SPECIFIC FUNCTIONS"
Functions are specified in the funct argument.  For the complete list
of I/O functions, see ioFunction(IIa).
.sh "ASYNCHRONOUS REQUESTS"
I/O and computation may be overlapped within a single process.  Normal
calls to K_device_function, K_read_block, and K_write_block should have
a zero in the id argument.  Such requests wait until the I/O operation
is complete.  If anything else is placed in the id argument, the
request is asynchronous and the call may return before the operation is
complete.  When the operation completes, an I/O completion message (see
ipc_block (IIa)) will be sent to the process which did the
K_device_function (or K_read_block or K_write_block) call.
.s1
Only when status is XOK and errs.devIndep is Xasync should an I/O
completion message be expected.  On asynchronous requests, some errors
are reported through errs.devIndep in the call and some are reported
through the errs.devIndep field in the I/O completion message.  It is
generally possible to have several requests in progress for different
devices from the same process, but an asynchronous request for a busy
device will be delayed until the device is available.
.sh EXCEPTIONS
.lp 22 15
XbadOd	Bad Open descriptor
.lp 22 15
XbadSize	TEMP invalid size in pBlock
.lp 22 15
XnoPriv	Does not have privilege
.lp 22 15
XnotReadable	Object not open for reading
.lp 22 15
XnotWritable	Cannot write specified object
.i0
.sh "SEE ALSO"
K_read_block(II), K_write_block(II),
ioFunction(IIa),
ipc_block(IIa),
p_block(IIa)
