.TH DIRECTORY 3
.SH NAME
asynchio, asyn_init, asyn_read, asyn_read, asyn_write, asyn_ioctl, asyn_wait, asyn_synch \- asynchronous I/O
.SH SYNOPSIS
.ft B
#include <fcntl.h>
.br
#include <time.h>
.br
#include <sys/asynchio.h>
.sp
.in +10
.ti -10
void asyn_init(asynchio_t *\fIasyn\fP)
.ti -10
ssize_t asyn_read(asynchio_t *\fIasyn\fP, int \fIfd\fP, void *\fIbuf\fP, size_t \fIlen\fP)
.ti -10
ssize_t asyn_write(asynchio_t *\fIasyn\fP, int \fIfd\fP, const void *\fIbuf\fP, size_t \fIlen\fP)
.ti -10
int asyn_ioctl(asynchio_t *\fIasyn\fP, int \fIfd\fP, ioreq_t \fIrequest\fP, void *\fIdata\fP)
.ti -10
int asyn_wait(asynchio_t *\fIasyn\fP, int \fIflags\fP, struct timeval *\fIto\fP)
.ti -10
int asyn_cancel(asynchio_t *\fIasyn\fP, int \fIfd\fP, int \fIop\fP)
.ti -10
int asyn_pending(asynchio_t *\fIasyn\fP, int \fIfd\fP, int \fIop\fP)
.ti -10
int asyn_synch(asynchio_t *\fIasyn\fP, int \fIfd\fP)
.ti -10
int asyn_close(asynchio_t *\fIasyn\fP, int \fIfd\fP)
.in -10
.SH DESCRIPTION
These routines make asynchronous I/O programming easier.  Instead of
starting several operations (that may or may not succeed) and waiting for
them with
.BR fwait (2),
one programs a loop around several
.BR asyn_read() ,
.BR asyn_write() ,
or
.B asyn_ioctl()
calls.  One call to
.B asyn_wait()
blocks waiting for one or more of the operations to succeed.  Results are
returned by the I/O operations themselves, not by
.BR asyn_wait() .
.PP
.B Asyn_init()
initializes the bookkeeping structure needed to hold flags and results.
This call is not needed on globally allocated structures.
.PP
.BR Asyn_read() ,
.BR asyn_write() ,
.B asyn_ioctl()
can be used just like the normal read, write and ioctl system calls in
asynchronous mode, except that you can recall them until they return a
result.  The file descriptor flag
.B FD_ASYNCHIO
is set on the first call.
.PP
.B Asyn_wait()
uses
.B fwait()
to wait for one or more of the operations to finish.  It gathers all results
that fwait has available before returning.  It will only block if all the
operations are in progress, so you will have to put a loop around everything.
Use the ASYN_NONBLOCK flag for a nonblocking call.  This flag may or may not
cause an error return with
.B errno
set to
.BR EAGAIN .
This depends on whether fwait was actually called.  This is how the routine
works, either it simply returns 0 (no fwait called), or it will return like
fwait.  You can use a signal to end the wait, or you can use a non-null
.I to
argument to specify a timeout.  (An absolute time, not a time difference.)
.PP
.B Asyn_synch()
puts the file descriptor back into synchronous mode, and removes it from the
bookkeeping.  It will fail with the
.B EAGAIN
error if there is still an operation in progress.
.PP
.B Asyn_cancel()
cancels a specific operation (use
.BR ASIO_READ ,
.BR ASIO_WRITE
or
.BR ASIO_IOCTL
for the operation code).  With
.B asyn_pending()
one can check if a result is available for a given operation.  Use it after
.B asyn_cancel()
to check if the cancel was too late, so that a result can still be obtained
with one of the
.B asyn_read/write/ioctl
calls.
.B Asyn_pending()
returns 0 for no result, 1 for a result, and -1 for the unlikely case that
the file descriptor is invalid.
.PP
.B Asyn_close()
only removes the bookkeeping on a file descriptor, the file descriptor stays
in asynchronous mode and there are no checks.
.SS "Example"
This is how the functions may be used:
.PP
.RS
.nf
.ta +4m +4m +4m +4m
asynchio_t asyn;
asyn_init(&asyn);
len2= fill2(buf2);
while (1) {
	if ((r= asyn_read(&asyn, fd1, buf1, len1)) != -1) {
		use1(buf, r);
	} else {
		if (errno != EINPROGRESS) disaster1();
	}
	if ((r= asyn_write(&asyn, fd2, buf2, len2)) != -1) {
		len2= fill2(buf2);
	} else {
		if (errno != EINPROGRESS) disaster2();
	}
	if (asyn_wait(&asyn, 0, NULL) == -1) {
		if (errno == EINTR) timeout();
		disaster3();
	}
}
.fi
.RE
.PP
Typical "back to synch" code for a read operation:
.PP
.RS
.nf
.ta +4m +4m +4m +4m
if (asyn_cancel(&asyn, fd1, ASIO_READ) == -1) disaster4();
if (asyn_pending(&asyn, fd1, ASIO_READ)) {
	r= asyn_read(&asyn, fd1, buf1, len1);
	...
}
if (asyn_synch(&asyn, fd1) == -1) disaster5();
.fi
.RE
.SH "SEE ALSO"
.BR fwait (2),
.BR fcntl (2),
.BR read (2),
.BR write (2),
.BR ioctl (2).
.SH AUTHOR
Kees J. Bot (kjb@cs.vu.nl)

.\" $PchId: asynchio.3,v 1.4 1996/02/22 20:47:38 philip Exp $