readv

readv, writev - read or write data into multiple buffers

#include <sys/uio.h>
 I ssize_t readv(int  fd , const struct iovec * iov , int  iovcnt );
 I ssize_t writev(int  fd , const struct iovec * iov , int  iovcnt );

The R readv () function reads iovcnt buffers from the file associated with the file descriptor fd into the buffers described by R iov ("scatter input").

The R writev () function writes iovcnt buffers of data described by iov to the file associated with the file descriptor R fd ("gather output").

The pointer iov points to an array of iovec structures, defined in <sys/uio.h> as:

struct iovec {
    void  *iov_base;    /* Starting address */
    size_t iov_len;     /* Number of bytes to transfer */
};

The R readv () function works just like read(2) except that multiple buffers are filled.

The R writev () function works just like write(2) except that multiple buffers are written out.

Buffers are processed in array order. This means that R readv () completely fills R iov [0] before proceeding to R iov [1], and so on. (If there is insufficient data, then not all buffers pointed to by iov may be filled.) Similarly, R writev () writes out the entire contents of R iov [0] before proceeding to R iov [1], and so on.

The data transfers performed by R readv () and R writev () are atomic: the data written by R writev () is written as a single block that is not intermingled with output from writes in other processes (but see pipe(7) for an exception); analogously, R readv () is guaranteed to read a contiguous block of data from the file, regardless of read operations performed in other threads or processes that have file descriptors referring to the same open file description (see open(2)).

On success, the R readv () function returns the number of bytes read; the R writev () function returns the number of bytes written. On error, -1 is returned, and errno is set appropriately.

The errors are as given for read(2) and write(2). Additionally the following error is defined:

EINVAL

4.4BSD (the R readv () and R writev () functions first appeared in 4.2BSD), POSIX.1-2001. Linux libc5 used size_t as the type of the iovcnt parameter, and int as return type for these functions.

Linux Notes

POSIX.1-2001 allows an implementation to place a limit on the number of items that can be passed in R iov . An implementation can advertise its limit by defining IOV_MAX in R <limits.h> or at run time via the return value from R sysconf(_SC_IOV_MAX) . On Linux, the limit advertised by these mechanisms is 1024, which is the true kernel limit. However, the glibc wrapper functions do some extra work if they detect that the underlying kernel system call failed because this limit was exceeded. In the case of R readv () the wrapper function allocates a temporary buffer large enough for all of the items specified by R iov , passes that buffer in a call to read(2), copies data from the buffer to the locations specified by the iov_base fields of the elements of R iov , and then frees the buffer. The wrapper function for R writev () performs the analogous task using a temporary buffer and a call to write(2).

It is not advisable to mix calls to functions like R readv () or R writev (), which operate on file descriptors, with the functions from the stdio library; the results will be undefined and probably not what you want.

The following code sample demonstrates the use of R writev ():

char *str0 = "hello ";
char *str1 = "world\n";
struct iovec iov[2];
ssize_t nwritten;

iov[0].iov_base = str0;
iov[0].iov_len = strlen(str0);
iov[1].iov_base = str1;
iov[1].iov_len = strlen(str1);

nwritten = writev(STDOUT_FILENO, iov, 2);

read(2), write(2)