NAME

       IV_FD_PUMP_INIT,  iv_fd_pump_init, iv_fd_pump_destroy, iv_fd_pump_pump, iv_fd_pump_is_done
       - pump data between file descriptors

SYNOPSIS

       #include <iv_fd_pump.h>

       struct iv_fd_pump {
               int             from_fd;
               int             to_fd;
               void            *cookie;
               void            (*set_bands)(void *cookie, int pollin, int pollout);
               unsigned int    flags;
       };

       void IV_FD_PUMP_INIT(struct iv_fd_pump *this);
       void iv_fd_pump_init(struct iv_fd_pump *this);
       void iv_fd_pump_destroy(struct iv_fd_pump *this);
       int iv_fd_pump_pump(struct iv_fd_pump *this);
       int iv_fd_pump_is_done(struct iv_fd_pump *this);

DESCRIPTION

       iv_fd_pump provides a way for moving data between two file descriptors.

       To set up iv_fd_pump for moving data, call IV_FD_PUMP_INIT on a struct iv_fd_pump  object,
       fill  in  the ->from_fd, ->to_fd, ->cookie, ->set_bands and ->flags members, and then call
       iv_fd_pump_init on the object.

       Conversely, to destroy a struct iv_fd_pump object, call iv_fd_pump_destroy.  There are  no
       restrictions on when this function can be called.

       A  call  to  iv_fd_pump_pump  will  attempt  to move data from ->from_fd to ->to_fd via an
       internal buffer associated with the struct iv_fd_pump object.

       During calls to iv_fd_pump_init,  iv_fd_pump_destroy  and  iv_fd_pump_pump,  the  callback
       function specified by ->set_bands may be invoked (with ->cookie as its first argument), by
       which iv_fd_pump indicates under which circumstances it wishes for future  invocations  of
       iv_fd_pump_pump to be done.

       If  the pollin argument to ->set_bands is true, there is space left in the internal buffer
       (and we have not yet seen an end-of-file condition on  input),  and  so  you  should  call
       iv_fd_pump_pump again when there is a POLLIN condition on ->from_fd.

       If  the pollout argument to ->set_bands is true, there is data in the internal buffer that
       could not all be transferred to ->to_fd, and so you should call iv_fd_pump_pump again when
       there is a POLLOUT condition on ->to_fd.

       If  IV_FD_PUMP_FLAG_RELAY_EOF  is set in ->flags, iv_fd_pump_pump will call shutdown(2) on
       ->to_fd with SHUT_WR as its second  argument  upon  seeing  an  end-of-file  condition  on
       ->from_fd  (but only after all data from the internal buffer has been drained into ->to_fd
       first).

       iv_fd_pump_pump will return -1 if there was  an  error,  0  if  we're  done  pumping  data
       (meaning  that an end-of-file condition was seen on the input file descriptor and that all
       data in the internal buffer has been drained into the output file  descriptor),  or  1  if
       there is more data left to be pumped.

       iv_fd_pump_is_done  will return a true value if iv_fd_pump_pump has previously returned 0,
       otherwise it will return false.

       Internally, iv_fd_pump_pump will use splice(2) if it is available, otherwise it will  fall
       back to read(2) and write(2).

SEE ALSO

       ivykis(3), splice(2)