.th K_write_block II 4/21/86
.sh NAME
K_write_block \- perform write to files, terminals, extents, and devices
.sh "MODULA SYNOPSIS"
.nf
 CONST od: openDescriptor;
 CONST blockNo: fBlockNumber;
 CONST outP: p_block;
 CONST id: asyncId;
 VAR errs: ioStatus;
 VAR status: K_err_num;
 ...
 status := NK_write_block(od, blockNo, outP, id, errs);
.sp
.sh "C SYNOPSIS"
 openDescriptor od;
 long blockNo;
 pblock outP;
 int id;
 ioStatus errs;
 int status;
 ...
 status = K_write_block(od, blockNo, &outP, id, &errs);
.sp
.fi
.sh DESCRIPTION
K_write_block is used to request writing to files, terminals, extents,
and devices.  The parameter block outP defines the memory area to be
used for output.
.s3
Writing to a file will cause file space to be allocated as required.  A
write which increases the highest block number of the file sets the
byte size of the file to (high block \*X 512).  The user may later
indicate, via the SETFILESIZE function of K_device_function (II), that
the size of the file in bytes is up to 511 less.  This will not prevent
the entire last block from being read.
.s3
Files may contain "holes", (unwritten blocks)
but extremely sparse files are inefficient.
.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, asynchronous, request, id 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 privilege
.lp 22 15
XnotReadable  Object not open for reading
.lp 22 15
XnotWritable  Cannot write specified object
.i0
.sh "SEE ALSO"
K_device_function(II), K_read_block(II),
ioStatus(IIa),
ioFunction(IIa),
p_block(IIa)
