fwait(2)

NAME
     fwait - wait for asynchronous I/O operations to complete

SYNOPSIS
     #define _MINIX_SOURCE 1

     #include <sys/types.h>
     #include <fcntl.h>

     int fwait(struct fwait *fwp)

DESCRIPTION
     Fwait allows a program to wait for the  completion  of  asynchronous  I/O
     operations, and to get the results of completed operations.  Asynchronous
     I/O operations are started by marking a file descriptor asynchronous with
     fcntl(2).  After  that  read(2),  write(2), and ioctl(2) system calls are
     asynchronous.

     Fwait takes one argument, a pointer  to  an  fwait  structure,  which  is
     defined in <fcntl.h> as follows:

     typedef struct fwait
     {
             int fw_flags;
             unsigned char (*fw_bits)[4];
             int fw_maxfd;

             int fw_result;
             int fw_errno;
             int fw_fd;
             int fw_operation;
     } fwait_t;

     The first three fields (fw_flags,  fw_bits,  and  fw_maxfd)  have  to  be
     filled-in  by  the  user.   Results  are returned in the last four fields
     (fw_result, fw_errno, fw_fd, and fw_operation) and in the fw_flags field.
     The following flags are defined for the fw_flags field:

     #define FWF_NONBLOCK 1
     #define FWF_MORE 2

     If the FWF_NONBLOCK flag is present, fwait does  not  block  but  returns
     immediately.  In this case, if no completed I/O operations are available,
     fwait sets errno(2) to EAGAIN.  If FWF_NONBLOCK is not set, fwait  blocks
     until a result can be reported, or until the process gets a signal.

     The FWF_MORE flag is ignored by fwait, but instead, fwait sets this  flag
     when  more  results  are  available, i.e. the next call to fwait will not
     block.  The user program can use this  flag  to  retrieve  all  available
     results in a loop.
     The second field, fw_bits contains a  pointer  to  a  2-dimensional  bit-
     array.     Bits   set   in   the   array   specify   about   which   file
     descriptor/operation combinations fwait should report completion results.
     The  easiest  way  to  create  such  an  array  is with the asio_fd_set_t
     datatype and the  macros  ASIO_FD_SET,  ASIO_FD_CLR,  ASIO_FD_ISSET,  and
     ASIO_FD_ZERO.  asio_fd_set_t is defined as follows:

     #define ASIO_FD_SETSIZE 64

     typedef unsigned char asio_fd_mask;

     typedef struct asio_fd_set
     {
         asio_fd_mask afds_bits[howmany(ASIO_FD_SETSIZE, ASIO_NFDBITS)][4];
     } asio_fd_set_t;

     ASIO_FD_ZERO(p), with p a pointer to a asio_fd_set structure, clears  all
     bits.   ASIO_FD_SET(n,o,p)  and ASIO_FD_CLR(n,o,p) set respectively reset
     bits in the asio_fd_set pointed to by p.  N specifies the file descriptor
     and o takes one of the following values depending on the operation:

     #define ASIO_READ 0
     #define ASIO_WRITE 1
     #define ASIO_IOCTL 2

     There is also ASIO_FD_ISSET(n,o,p) to test whether a certain bit is set.

     Using an asio_fd_set, the fw_bits field is filled in as follows:

     fw.fw_bits= afds.afds_bits;

     Finally, fw_maxfd is to be filled-in with  the  size  of  the  bit-array.
     Normally this is the value of the macro ASIO_FD_SETSIZE.

     Fwait will examine the bits set in the bit-array to see whether

     -    The file descriptor refers to an open file. If not errno is  set  to
          EBADF.

     -    The specified operation is in progress,  or  has  completed  without
          reporting it's status. If not errno is set to EINVAL.

     -    For the  first  completed  operation,  fwait  fills  in  the  fields
          fw_result,  fw_errno, fw_fd, and fw_operation with resp.  the return
          value, the error code, the file descriptor number and the  operation
          code.

     -    If a second completed operation is found, fwait  sets  the  FWF_MORE
          more flag, and updates the bit-array to reflect it's internal state.
          The nonblocking behavior of the FWF_MORE is only guaranteed  if  the
          bit-array is left unmodified.

RETURN VALUES
     Fwait returns 0 upon success and -1 upon failure.

ERRORS

     EFAULT
          Either the pointer to the fwait structure or the pointer to the bit-
          array is invalid.

     EINVAL
          Fw_maxfd is invalid, or a bit is set for a file descriptor/operation
          combination without a pending reult or a call in progress.

     EAGAIN
          FWF_NONBLOCK was set but there was no result to report.

     EINTR
          Fwait is interrupted by a signal.

SEE ALSO
     asynchio(3), errno(2), fcntl(2), ioctl(2), read(2), write(2).

AUTHOR
     Philip Homburg (philip@cs.vu.nl)