.th K_read_block II 4/21/86
.sh NAME
K_read_block \- perform read from files, terminals, extents and devices
.sh "MODULA SYNOPSIS"
.nf
 CONST od: openDescriptor;
 CONST blockNo: fBlockNumber;
 CONST inP: p_block;
 CONST id: asyncId;
 VAR errs: ioStatus;
 VAR bytesRead: cardinal;
 VAR status: K_err_num;
 ...
 status := NK_read_block(od, blockNo, inP, id, errs, bytesRead);
.sp
.sh "C SYNOPSIS"
 openDescriptor od;
 long blockNo;
 pblock inP;
 int id;
 ioStatus errs;
 int bytes;
 int status;
 ...
 status = K_read_block(od, blockNo, &inP, id, &errs, &bytes);
.sp
.fi
.sh DESCRIPTION
K_read_block is used to request reading from files, terminals, extents,
and devices.  The parameter block inP defines the memory area to be
used for input.
.s3
Files and extents are stored in units of 512 byte blocks.
From 1 to 64 blocks can be read from a file or extent with one request.
A single big request is much faster than many small requests.
Files which contain "holes" (unwritten blocks) are treated on read
as if the unwritten block contained all zero bytes.
Transfers are always in multiples of 512 bytes, regardless of the byte
size of the file.
.s3
Terminals may be read and written in sizes from 1 to 128 bytes.
.s3
Devices may have different rules for each device depending on the block
size used by that device.  See the specific device in (VI).
.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.

To make a normal, synchronous, request, the id argument should be zero.
.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 priviledge
.lp 22 15
XnotReadable  Object not open for reading
.lp 22 15
XnotWritable  Cannot write specified object
.i0
.sh "ERROR CODES"
Error information is returned in errs.  After an operation
errs.devIndep contains one of the values described in Appendix A, and,
for operations on devices, errs.devDep contains 16 bits of hardware
status as described in the DEC Peripherals Manual under the specific
device.  See K_device_function (II) for further details.
.sh "SEE ALSO"
K_device_function(II), K_write_block(II),
ioFunction(IIa),
ioStatus(IIa),
p_block(IIa)
