|
|
|
|
.TH iopause 3
|
|
|
|
|
.SH NAME
|
|
|
|
|
iopause \-
|
|
|
|
|
.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)
|
