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 inefficent
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.
The iovec
structure describes a buffer. It contains two fields:
void *iov_base
size_t iov_len
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, @math{0}
indicating end-of-file, or @math{-1} indicating an error. The possible
errors are the same as in read
.
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 @math{-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.
Go to the first, previous, next, last section, table of contents.