Manpages - readv.2

readv, writev, preadv, pwritev, preadv2, pwritev2 - read or write data into multiple buffers

  #include <sys/uio.h>

  ssize_t readv(int fd, const struct iovec *iov, int iovcnt);
  ssize_t writev(int fd, const struct iovec *iov, int iovcnt);

  ssize_t preadv(int fd, const struct iovec *iov, int iovcnt,
   off_t offset);
  ssize_t pwritev(int fd, const struct iovec *iov, int iovcnt,
   off_t offset);

  ssize_t preadv2(int fd, const struct iovec *iov, int iovcnt,
   off_t offset, int flags);
  ssize_t pwritev2(int fd, const struct iovec *iov, int iovcnt,
   off_t offset, int flags);

Feature Test Macro Requirements for glibc (see *feature_test_macros*(7)):

*preadv*(), *pwritev*():

      Since glibc 2.19:
          _DEFAULT_SOURCE
      Glibc 2.19 and earlier:
          _BSD_SOURCE

The *readv*() system call reads iovcnt buffers from the file associated with the file descriptor fd into the buffers described by iov (“scatter input”).

The *writev*() system call writes iovcnt buffers of data described by iov to the file associated with the file descriptor 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 *readv*() system call works just like *read*(2) except that multiple buffers are filled.

The *writev*() system call works just like *write*(2) except that multiple buffers are written out.

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

The data transfers performed by *readv*() and *writev*() are atomic: the data written by *writev*() is written as a single block that is not intermingled with output from writes in other processes; analogously, *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, *readv*(), *preadv*(), and *preadv2*() return the number of bytes read; *writev*(), *pwritev*(), and *pwritev2*() return the number of bytes written.

Note that it is not an error for a successful call to transfer fewer bytes than requested (see *read*(2) and *write*(2)).

On error, -1 is returned, and errno is set to indicate the error.

The errors are as given for *read*(2) and *write*(2). Furthermore, *preadv*(), *preadv2*(), *pwritev*(), and *pwritev2*() can also fail for the same reasons as *lseek*(2). Additionally, the following errors are defined:

EINVAL

The sum of the iov_len values overflows an ssize_t value.

EINVAL

The vector count, iovcnt, is less than zero or greater than the permitted maximum.

EOPNOTSUPP

An unknown flag is specified in flags.

*preadv*() and *pwritev*() first appeared in Linux 2.6.30; library support was added in glibc 2.10.

*preadv2*() and *pwritev2*() first appeared in Linux 4.6. Library support was added in glibc 2.26.

*readv*(), *writev*(): POSIX.1-2001, POSIX.1-2008, 4.4BSD (these system calls first appeared in 4.2BSD).

*preadv*(), *pwritev*(): nonstandard, but present also on the modern BSDs.

*preadv2*(), *pwritev2*(): nonstandard Linux extension.

POSIX.1 allows an implementation to place a limit on the number of items that can be passed in iov. An implementation can advertise its limit by defining IOV_MAX in <limits.h> or at run time via the return value from sysconf(_SC_IOV_MAX). On modern Linux systems, the limit is 1024. Back in Linux 2.0 days, this limit was 16.

These arguments contain, respectively, the low order and high order 32 bits of offset.

Linux 5.9 and 5.10 have a bug where preadv2() with the RWF_NOWAIT flag may return 0 even when not at end of file.

The following code sample demonstrates the use of *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);

*pread*(2), *read*(2), *write*(2)

This page is part of release 5.13 of the Linux man-pages project. A description of the project, information about reporting bugs, and the latest version of this page, can be found at https://www.kernel.org/doc/man-pages/.