.TH iopause 3
.SH NAME
iopause \- check for file descriptor readability or writability
.SH SYNTAX
.B #include <libowfat/iopause.h>

int \fBiopause\fP(iopause_fd** \fIx\fR,unsigned int \fIlen\fR,
            struct taia \fIdeadline\fR,struct taia \fIstamp\fR);
.SH DESCRIPTION
iopause checks for file descriptor readability or writability as specified
by \fIx\fR[0].fd, \fIx\fR[0].events, \fIx\fR[1].fd, \fIx\fR[1].events, ..., \fIx\fR[\fIlen\fR-1].fd,
\fIx\fR[\fIlen\fR-1].events. If \fIx\fR[i].events includes the bit IOPAUSE_READ, iopause
checks for readability of the descriptor \fIx\fR[i].fd; if \fIx\fR[i].events includes
the bit IOPAUSE_WRITE, iopause checks for writability of the descriptor
\fIx\fR[i].fd; other bits in \fIx\fR[i].events have undefined effects.

iopause sets the IOPAUSE_READ bit in \fIx\fR[i].revents if it finds that \fIx\fR[i].fd
is readable, and it sets the IOPAUSE_WRITE bit in \fIx\fR[i].revents if it finds
that \fIx\fR[i].fd is writable. Beware that readability and writability may be
destroyed at any moment by other processes with access to the same ofile
that \fIx\fR[i].fd refers to.

If there is no readability or writability to report, iopause waits until
\fIdeadline\fR for something to happen. iopause will return before \fIdeadline\fR if a
descriptor becomes readable or writable, or an interrupting signal
arrives, or some system-defined amount of time passes. iopause sets
revents in any case.

You must put a current timestamp into \fIstamp\fR before calling iopause.
.SH "IMPLEMENTATION NOTES"
The current implementation of iopause uses the \fBpoll\fR function if that is
available. On some systems, \fBpoll\fR needs to dynamically allocate kernel
memory; when not much memory is available, iopause will return
immediately, and will report (often incorrectly) that no descriptors are
readable or writable. This is a kernel bug, and I encourage vendors to fix
it.

If \fBpoll\fR is not available, iopause uses the \fBselect\fR function. This function
cannot see descriptor numbers past a system-defined limit, typically 256
or 1024; iopause will artificially pretend that those descriptors are
never readable or writable.

Future implementations of iopause may work around these problems on some
systems, at the expense of chewing up all available CPU time.

Both \fBpoll\fR and \fBselect\fR use relative timeouts rather than absolute deadlines.
Some kernels round the timeout down to a multiple of 10 milliseconds; this
can burn quite a bit of CPU time as the deadline approaches. iopause
compensates for this by adding 20 milliseconds to the timeout.
.SH "SEE ALSO"
select(2), poll(3), taia_now(3)