debian man page for iopause

iopause(3)						     Library Functions Manual							iopause(3)

NAME
       iopause - check for file descriptor readability or writability

SYNTAX
       #include <iopause.h>

       int iopause(iopause_fd** x,unsigned int len,
		   struct taia deadline,struct taia stamp);

DESCRIPTION
       iopause checks for file descriptor readability or writability as specified by x[0].fd, x[0].events, x[1].fd, x[1].events, ..., x[len-1].fd,
       x[len-1].events. If x[i].events includes the bit IOPAUSE_READ, iopause checks for readability of the  descriptor  x[i].fd;  if  x[i].events
       includes the bit IOPAUSE_WRITE, iopause checks for writability of the descriptor x[i].fd; other bits in x[i].events have undefined effects.

       iopause	sets  the IOPAUSE_READ bit in x[i].revents if it finds that x[i].fd is readable, and it sets the IOPAUSE_WRITE bit in x[i].revents
       if it finds that x[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 x[i].fd refers to.

       If there is no readability or writability to report, iopause waits until deadline for something to happen. iopause will return before dead-
       line 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 stamp before calling iopause.

IMPLEMENTATION NOTES
       The current implementation of iopause uses the poll function if that is available. On some systems, poll needs to dynamically allocate ker-
       nel 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  poll is not available, iopause uses the select function. This function cannot see descriptor numbers past a system-defined limit, typi-
       cally 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 poll and select use relative timeouts rather than absolute deadlines.  Some kernels round the timeout down to a multiple  of  10  mil-
       liseconds;  this can burn quite a bit of CPU time as the deadline approaches. iopause compensates for this by adding 20 milliseconds to the
       timeout.

SEE ALSO
       select(2), poll(3), taia_now(3)

																	iopause(3)