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  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)