iv_fd_pump

Section: ivykis programmer's manual (3)
Updated: 2012-06-05
Index Return to Main Contents
 

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)


 

Index

NAME
SYNOPSIS
DESCRIPTION
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 03:08:27 GMT, June 06, 2012