---

13.6 Fast Scatter-Gather I/O

Some applications may need to read or write data to multiple buffers, which are separated in memory. Although this can be done easily enough with multiple calls to read and write, it is inefficient because there is overhead associated with each kernel call.

Instead, many platforms provide special high-speed primitives to perform these scatter-gather operations in a single kernel call. The GNU C Library will provide an emulation on any system that lacks these primitives, so they are not a portability threat. They are defined in sys/uio.h.

These functions are controlled with arrays of iovec structures, which describe the location and size of each buffer.

Data Type: struct iovec ¶

The iovec structure describes a buffer. It contains two fields:

void *iov_base

Contains the address of a buffer.

size_t iov_len

Contains the length of the buffer.

Function: ssize_t readv (int filedes, const struct iovec *vector, int count) ¶

Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | See POSIX Safety Concepts.

The readv function reads data from filedes and scatters it into the buffers described in vector, which is taken to be count structures long. As each buffer is filled, data is sent to the next.

Note that readv is not guaranteed to fill all the buffers. It may stop at any point, for the same reasons read would.

The return value is a count of bytes (not buffers) read, 0 indicating end-of-file, or -1 indicating an error. The possible errors are the same as in read.

Function: ssize_t writev (int filedes, const struct iovec *vector, int count) ¶

Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | See POSIX Safety Concepts.

The writev function gathers data from the buffers described in vector, which is taken to be count structures long, and writes them to filedes. As each buffer is written, it moves on to the next.

Like readv, writev may stop midstream under the same conditions write would.

The return value is a count of bytes written, or -1 indicating an error. The possible errors are the same as in write.

Note that if the buffers are small (under about 1kB), high-level streams may be easier to use than these functions. However, readv and writev are more efficient when the individual buffers themselves (as opposed to the total output), are large. In that case, a high-level stream would not be able to cache the data effectively.