1iv_fd_pump(3)             ivykis programmer's manual             iv_fd_pump(3)
2
3
4

NAME

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

SYNOPSIS

10       #include <iv_fd_pump.h>
11
12       struct iv_fd_pump {
13               int             from_fd;
14               int             to_fd;
15               void            *cookie;
16               void            (*set_bands)(void *cookie, int pollin, int pollout);
17               unsigned int    flags;
18       };
19
20       void IV_FD_PUMP_INIT(struct iv_fd_pump *this);
21       void iv_fd_pump_init(struct iv_fd_pump *this);
22       void iv_fd_pump_destroy(struct iv_fd_pump *this);
23       int iv_fd_pump_pump(struct iv_fd_pump *this);
24       int iv_fd_pump_is_done(const struct iv_fd_pump *this);
25

DESCRIPTION

27       iv_fd_pump provides a way for moving data between two file descriptors.
28
29       To set up iv_fd_pump for moving data, call IV_FD_PUMP_INIT on a  struct
30       iv_fd_pump   object,   fill   in   the  ->from_fd,  ->to_fd,  ->cookie,
31       ->set_bands and ->flags members, and then call iv_fd_pump_init  on  the
32       object.
33
34       Conversely,    to    destroy   a   struct   iv_fd_pump   object,   call
35       iv_fd_pump_destroy.  There are no restrictions on  when  this  function
36       can be called.
37
38       A  call  to iv_fd_pump_pump will attempt to move data from ->from_fd to
39       ->to_fd via an internal buffer associated with  the  struct  iv_fd_pump
40       object.
41
42       During     calls    to    iv_fd_pump_init,    iv_fd_pump_destroy    and
43       iv_fd_pump_pump, the callback function specified by ->set_bands may  be
44       invoked  (with  ->cookie  as  its  first argument), by which iv_fd_pump
45       indicates under which circumstances it wishes for future invocations of
46       iv_fd_pump_pump to be done.
47
48       If  the  pollin argument to ->set_bands is true, there is space left in
49       the internal buffer (and we have not yet seen an end-of-file  condition
50       on input), and so you should call iv_fd_pump_pump again when there is a
51       POLLIN condition on ->from_fd.
52
53       If the pollout argument to ->set_bands is true, there is  data  in  the
54       internal  buffer  that  could not all be transferred to ->to_fd, and so
55       you should call iv_fd_pump_pump again when there is a POLLOUT condition
56       on ->to_fd.
57
58       If  IV_FD_PUMP_FLAG_RELAY_EOF  is  set in ->flags, iv_fd_pump_pump will
59       call shutdown(2) on ->to_fd with SHUT_WR as its  second  argument  upon
60       seeing  an  end-of-file condition on ->from_fd (but only after all data
61       from the internal buffer has been drained into ->to_fd first).
62
63       iv_fd_pump_pump will return -1 if there was an error, 0 if  we're  done
64       pumping  data  (meaning  that  an end-of-file condition was seen on the
65       input file descriptor and that all data in the internal buffer has been
66       drained  into  the  output file descriptor), or 1 if there is more data
67       left to be pumped.
68
69       iv_fd_pump_is_done will return a true value if iv_fd_pump_pump has pre‐
70       viously returned 0, otherwise it will return false.
71
72       Internally, iv_fd_pump_pump will use splice(2) if it is available, oth‐
73       erwise it will fall back to read(2) and write(2).
74

SEE ALSO

76       ivykis(3), splice(2)
77
78
79
80ivykis                            2012-06-05                     iv_fd_pump(3)
Impressum