HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |VERSIONS |STANDARDS |HISTORY |NOTES |BUGS |EXAMPLES |SEE ALSO |COLOPHON | |
readv(2) System Calls Manualreadv(2)readv, writev, preadv, pwritev, preadv2, pwritev2 - read or write data into multiple buffers
Standard C library (libc,-lc)
#include <sys/uio.h>ssize_t readv(intfd, const struct iovec *iov, intiovcnt);ssize_t writev(intfd, const struct iovec *iov, intiovcnt);ssize_t preadv(intfd, const struct iovec *iov, intiovcnt,off_toffset);ssize_t pwritev(intfd, const struct iovec *iov, intiovcnt,off_toffset);ssize_t preadv2(intfd, const struct iovec *iov, intiovcnt,off_toffset, intflags);ssize_t pwritev2(intfd, const struct iovec *iov, intiovcnt,off_toffset, intflags); Feature Test Macro Requirements for glibc (seefeature_test_macros(7)):preadv(),pwritev(): Since glibc 2.19: _DEFAULT_SOURCE glibc 2.19 and earlier: _BSD_SOURCE
Thereadv() system call readsiovcnt buffers from the file associated with the file descriptorfd into the buffers described byiov ("scatter input"). Thewritev() system call writesiovcnt buffers of data described byiov to the file associated with the file descriptorfd ("gather output"). The pointeriov points to an array ofiovec structures, described iniovec(3type). Thereadv() system call works just likeread(2) except that multiple buffers are filled. Thewritev() system call works just likewrite(2) except that multiple buffers are written out. Buffers are processed in array order. This means thatreadv() completely fillsiov[0] before proceeding toiov[1], and so on. (If there is insufficient data, then not all buffers pointed to byiov may be filled.) Similarly,writev() writes out the entire contents ofiov[0] before proceeding toiov[1], and so on. The data transfers performed byreadv() andwritev() are atomic: the data written bywritev() 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 (seeopen(2)).preadv() and pwritev() Thepreadv() system call combines the functionality ofreadv() andpread(2). It performs the same task asreadv(), but adds a fourth argument,offset, which specifies the file offset at which the input operation is to be performed. Thepwritev() system call combines the functionality ofwritev() andpwrite(2). It performs the same task aswritev(), 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 byfd must be capable of seeking.preadv2() and pwritev2() These system calls are similar topreadv() andpwritev() calls, but add a fifth argument,flags, which modifies the behavior on a per-call basis. Unlikepreadv() andpwritev(), if theoffset argument is -1, then the current file offset is used and updated. Theflags 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 theO_DSYNC open(2) flag. This flag is meaningful only forpwritev2(), 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 theO_DIRECTflag.)RWF_SYNC(since Linux 4.7) Provide a per-write equivalent of theO_SYNC open(2) flag. This flag is meaningful only forpwritev2(), 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, thepreadv2() 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 seterrno toEAGAIN(but seeBUGS). Currently, this flag is meaningful only forpreadv2().RWF_APPEND(since Linux 4.16) Provide a per-write equivalent of theO_APPEND open(2) flag. This flag is meaningful only forpwritev2(), and its effect applies only to the data range written by the system call. Theoffset argument does not affect the write operation; the data is always appended to the end of the file. However, if theoffset argument is -1, the current file offset is updated.RWF_NOAPPEND(since Linux 6.9) Do not honor theO_APPEND open(2) flag. This flag is meaningful only forpwritev2(). Historically, Linux honoredO_APPENDflag if set and ignored the offset argument, which is a bug. Forpwritev2(), theoffset argument is honored as expected ifRWF_NOAPPENDflag is set, the same as ifO_APPENDflag 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 forpwritev2(), 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 ofiovcnt forpwritev2() is given by the value instx_atomic_write_segments_max. Torn- write protection only works withO_DIRECTflag, 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_SYNCorO_DSYNCmust be specified foropen(2). The same synchronized I/O guarantees as described inopen(2) are provided when these flags or their equivalent flags and system calls are used (e.g., ifRWF_SYNCis specified forpwritev2()).On success,readv(),preadv(), andpreadv2() return the number of bytes read;writev(),pwritev(), andpwritev2() return the number of bytes written. Note that it is not an error for a successful call to transfer fewer bytes than requested (seeread(2) andwrite(2)). On error, -1 is returned, anderrno is set to indicate the error.
The errors are as given forread(2) andwrite(2). Furthermore,preadv(),preadv2(),pwritev(), andpwritev2() can also fail for the same reasons aslseek(2). Additionally, the following errors are defined:EINVALThe sum of theiov_len values overflows anssize_t value.EINVALIfRWF_ATOMICis specified, the combination of the sum of theiov_len values and theoffset value does not comply with the length and offset torn-write protection rules.EINVALThe vector count,iovcnt, is less than zero or greater than the permitted maximum. IfRWF_ATOMICis specified, this maximum is given by thestx_atomic_write_segments_max value fromstatx.EOPNOTSUPP An unknown flag is specified inflags.
C library/kernel differences The rawpreadv() andpwritev() 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 longpos_l, unsigned longpos These arguments contain, respectively, the low order and high order 32 bits ofoffset.
readv()writev() POSIX.1-2008.preadv()pwritev() BSD.preadv2()pwritev2() Linux.
readv()writev() POSIX.1-2001, 4.4BSD (first appeared in 4.2BSD).preadv(),pwritev(): Linux 2.6.30, glibc 2.10.preadv2(),pwritev2(): Linux 4.6, glibc 2.26.Historical C library/kernel differences To deal with the fact thatIOV_MAXwas so low on early versions of Linux, the glibc wrapper functions forreadv() andwritev() did some extra work if they detected that the underlying kernel system call failed because this limit was exceeded. In the case ofreadv(), the wrapper function allocated a temporary buffer large enough for all of the items specified byiov, passed that buffer in a call toread(2), copied data from the buffer to the locations specified by theiov_base fields of the elements ofiov, and then freed the buffer. The wrapper function forwritev() performed the analogous task using a temporary buffer and a call towrite(2). The need for this extra effort in the glibc wrapper functions went away with Linux 2.2 and later. However, glibc continued to provide this behavior until glibc 2.10. Starting with glibc 2.9, the wrapper functions provide this behavior only if the library detects that the system is running a Linux kernel older than Linux 2.6.18 (an arbitrarily selected kernel version). And since glibc 2.20 (which requires a minimum of Linux 2.6.32), the glibc wrapper functions always just directly invoke the system calls.
POSIX.1 allows an implementation to place a limit on the number of items that can be passed iniov. An implementation can advertise its limit by definingIOV_MAXin<limits.h> or at run time via the return value fromsysconf(_SC_IOV_MAX). On modern Linux systems, the limit is 1024. Back in Linux 2.0 days, this limit was 16.
Linux 5.9 and Linux 5.10 have a bug wherepreadv2() with theRWF_NOWAITflag may return 0 even when not at end of file.
The following code sample demonstrates the use ofwritev(): 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);
pread(2),read(2),write(2)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-17readv(2)Pages that refer to this page:strace(1), F_NOTIFY(2const), fsync(2), io_submit(2), io_uring_enter2(2), io_uring_enter(2), io_uring_setup(2), pread(2), process_vm_readv(2), read(2), recv(2), send(2), statx(2), syscall(2), syscalls(2), write(2), iovec(3type), size_t(3type), io_uring(7), signal(7), socket(7), spufs(7), xfs_io(8)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |