NAME

       iopause - check for file descriptor readability or writability

SYNTAX

       #include <libowfat/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 deadline 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  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  poll  is  not  available,  iopause  uses the select 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 poll and select 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.

SEE ALSO

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

                                                                                       iopause(3)