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)