# readv

## NAME



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


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#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
    


## DESCRIPTION



           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, described
           in iovec(3type).
    
           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)).
    
       **preadv() and pwritev()**
           The **preadv**() system call combines the functionality of **readv**() and
           pread(2).  It performs the same task as **readv**(), but adds a fourth
           argument, _offset_ , which specifies the file offset at which the
           input operation is to be performed.
    
           The **pwritev**() system call combines the functionality of **writev**()
           and pwrite(2).  It performs the same task as **writev**(), but adds a
           fourth argument, _offset_ , which specifies the file offset at which
           the output operation is to be performed.
    
           The file offset is not changed by these system calls.  The file
           referred to by _fd_ must be capable of seeking.
    
       **preadv2() and pwritev2()**
           These system calls are similar to **preadv**() and **pwritev**() calls,
           but add a fifth argument, _flags_ , which modifies the behavior on a
           per-call basis.
    
           Unlike **preadv**() and **pwritev**(), if the _offset_ argument is -1, then
           the current file offset is used and updated.
    
           The _flags_ argument contains a bitwise OR of zero or more of the
           following flags:
    
           **RWF_DSYNC**(since Linux 4.7)
                  Provide a per-write equivalent of the **O_DSYNC open**(2) flag.
                  This flag is meaningful only for **pwritev2**(), and its effect
                  applies only to the data range written by the system call.
    
           **RWF_HIPRI**(since Linux 4.6)
                  High priority read/write.  Allows block-based filesystems
                  to use polling of the device, which provides lower latency,
                  but may use additional resources.  (Currently, this feature
                  is usable only on a file descriptor opened using the
                  **O_DIRECT** flag.)
    
           **RWF_SYNC**(since Linux 4.7)
                  Provide a per-write equivalent of the **O_SYNC open**(2) flag.
                  This flag is meaningful only for **pwritev2**(), and its effect
                  applies only to the data range written by the system call.
    
           **RWF_NOWAIT**(since Linux 4.14)
                  Do not wait for data which is not immediately available.
                  If this flag is specified, the **preadv2**() system call will
                  return instantly if it would have to read data from the
                  backing storage or wait for a lock.  If some data was
                  successfully read, it will return the number of bytes read.
                  If no bytes were read, it will return -1 and set _errno_ to
                  **EAGAIN**(but see **BUGS**).  Currently, this flag is meaningful
                  only for **preadv2**().
    
           **RWF_APPEND**(since Linux 4.16)
                  Provide a per-write equivalent of the **O_APPEND open**(2)
                  flag.  This flag is meaningful only for **pwritev2**(), and its
                  effect applies only to the data range written by the system
                  call.  The _offset_ argument does not affect the write
                  operation; the data is always appended to the end of the
                  file.  However, if the _offset_ argument is -1, the current
                  file offset is updated.
    
           **RWF_NOAPPEND**(since Linux 6.9)
                  Do not honor the **O_APPEND open**(2) flag.  This flag is
                  meaningful only for **pwritev2**().  Historically, Linux
                  honored **O_APPEND** flag if set and ignored the offset
                  argument, which is a bug.  For **pwritev2**(), the _offset_
                  argument is honored as expected if **RWF_NOAPPEND** flag is
                  set, the same as if **O_APPEND** flag were not set.
    
           **RWF_ATOMIC**(since Linux 6.11)
                  Requires that writes to regular files in block-based
                  filesystems be issued with torn-write protection.  Torn-
                  write protection means that for a power or any other
                  hardware failure, all or none of the data from the write
                  will be stored, but never a mix of old and new data.  This
                  flag is meaningful only for **pwritev2**(), and its effect
                  applies only to the data range written by the system call.
                  The total write length must be power-of-2 and must be sized
                  in the range [_stx_atomic_write_unit_min_ ,
                  _stx_atomic_write_unit_max_].  The write must be at a
                  naturally-aligned offset within the file with respect to
                  the total write length.  For example, a write of length
                  32KiB at a file offset of 32KiB is permitted, however a
                  write of length 32KiB at a file offset of 48KiB is not
                  permitted.  The upper limit of _iovcnt_ for **pwritev2**() is
                  given by the value in _stx_atomic_write_segments_max._  Torn-
                  write protection only works with **O_DIRECT** flag, i.e.
                  buffered writes are not supported.  To guarantee
                  consistency from the write between a file's in-core state
                  with the storage device, **O_SYNC** or **O_DSYNC** must be
                  specified for open(2).  The same synchronized I/O
                  guarantees as described in open(2) are provided when these
                  flags or their equivalent flags and system calls are used
                  (e.g., if **RWF_SYNC** is specified for **pwritev2**()).
    


## RETURN VALUE



           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.
    


## ERRORS



           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** If **RWF_ATOMIC** is specified, the combination of the sum of
                  the _iov_len_ values and the _offset_ value does not comply
                  with the length and offset torn-write protection rules.
    
           **EINVAL** The vector count, _iovcnt_ , is less than zero or greater than
                  the permitted maximum.  If **RWF_ATOMIC** is specified, this
                  maximum is given by the _stx_atomic_write_segments_max_ value
                  from _statx._
    
           **EOPNOTSUPP**
                  An unknown flag is specified in _flags_.
    


## VERSIONS



       **C library/kernel differences**
           The raw **preadv**() and **pwritev**() system calls have call signatures
           that differ slightly from that of the corresponding GNU C library
           wrapper functions shown in the SYNOPSIS.  The final argument,
           _offset_ , is unpacked by the wrapper functions into two arguments in
           the system calls:
    
               **unsigned long** _pos_l_**, unsigned long** _pos_
    
           These arguments contain, respectively, the low order and high
           order 32 bits of _offset_.
    


## STANDARDS



           **readv**()
           **writev**()
                  POSIX.1-2008.
    
           **preadv**()
           **pwritev**()
                  BSD.
    
           **preadv2**()
           **pwritev2**()
                  Linux.
    


## NOTES



           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.
    


## BUGS



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


## EXAMPLES



           The following code sample demonstrates the use of **writev**():
    
               char          *str0 = "hello ";
               char          *str1 = "world\n";
               ssize_t       nwritten;
               struct iovec  iov[2];
    
               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);
    


* * *