---
name: "iv_fd_pump"
section: "3"
platform: "linux"
package: "libivykis-dev"
version: "0.43.2-1+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/iv_fd_pump"
---

# iv\_fd\_pump(3)

pump data between file descriptors

## 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(const 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)](/shutdown/2.md) 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)](/splice/2.md) if it is available, otherwise it will fall back to [**read**(2)](/read/2.md) and [**write**(2)](/write/2.md).

## SEE ALSO

[**ivykis**(3)](/ivykis/3.md), [**splice**(2)](/splice/2.md)