man/man2/readv.2

.\" Copyright (C) 2007, 2010 Michael Kerrisk <mtk.manpages@gmail.com>
.\" and Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\" Modified Sat Jul 24 18:34:44 1993 by Rik Faith (faith@cs.unc.edu)
.\" Merged readv.[23], 2002-10-17, aeb
.\" 2007-04-30 mtk, A fairly major rewrite to fix errors and
.\"     add more details.
.\" 2010-11-16, mtk, Added documentation of preadv() and pwritev()
.\"
.TH readv 2 (date) "Linux man-pages (unreleased)"
.SH NAME
readv, writev, preadv, pwritev, preadv2, pwritev2 \-
read or write data into multiple buffers
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.B #include <sys/uio.h>
.P
.BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt );
.BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt );
.P
.BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt ,
.BI "                off_t " offset );
.BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt ,
.BI "                off_t " offset );
.P
.BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
.BI "                off_t " offset ", int " flags );
.BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
.BI "                off_t " offset ", int " flags );
.fi
.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
.P
.BR preadv (),
.BR pwritev ():
.nf
    Since glibc 2.19:
        _DEFAULT_SOURCE
    glibc 2.19 and earlier:
        _BSD_SOURCE
.fi
.SH DESCRIPTION
The
.BR readv ()
system call reads
.I iovcnt
buffers from the file associated with the file descriptor
.I fd
into the buffers described by
.I iov
("scatter input").
.P
The
.BR writev ()
system call writes
.I iovcnt
buffers of data described by
.I iov
to the file associated with the file descriptor
.I fd
("gather output").
.P
The pointer
.I iov
points to an array of
.I iovec
structures,
described in
.BR iovec (3type).
.P
The
.BR readv ()
system call works just like
.BR read (2)
except that multiple buffers are filled.
.P
The
.BR writev ()
system call works just like
.BR write (2)
except that multiple buffers are written out.
.P
Buffers are processed in array order.
This means that
.BR readv ()
completely fills
.I iov[0]
before proceeding to
.IR iov[1] ,
and so on.
(If there is insufficient data, then not all buffers pointed to by
.I iov
may be filled.)
Similarly,
.BR writev ()
writes out the entire contents of
.I iov[0]
before proceeding to
.IR iov[1] ,
and so on.
.P
The data transfers performed by
.BR readv ()
and
.BR writev ()
are atomic: the data written by
.\" Regarding atomicity, see https://bugzilla.kernel.org/show_bug.cgi?id=10596
.BR writev ()
is written as a single block that is not intermingled with output
from writes in other processes;
analogously,
.BR 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
.BR open (2)).
.SS preadv() and pwritev()
The
.BR preadv ()
system call combines the functionality of
.BR readv ()
and
.BR pread (2).
It performs the same task as
.BR readv (),
but adds a fourth argument,
.IR offset ,
which specifies the file offset at which the input operation
is to be performed.
.P
The
.BR pwritev ()
system call combines the functionality of
.BR writev ()
and
.BR pwrite (2).
It performs the same task as
.BR writev (),
but adds a fourth argument,
.IR offset ,
which specifies the file offset at which the output operation
is to be performed.
.P
The file offset is not changed by these system calls.
The file referred to by
.I fd
must be capable of seeking.
.SS preadv2() and pwritev2()
These system calls are similar to
.BR preadv ()
and
.BR pwritev ()
calls, but add a fifth argument,
.IR flags ,
which modifies the behavior on a per-call basis.
.P
Unlike
.BR preadv ()
and
.BR pwritev (),
if the
.I offset
argument is \-1, then the current file offset is used and updated.
.P
The
.I flags
argument contains a bitwise OR of zero or more of the following flags:
.TP
.BR RWF_DSYNC " (since Linux 4.7)"
.\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9
Provide a per-write equivalent of the
.B O_DSYNC
.BR open (2)
flag.
This flag is meaningful only for
.BR pwritev2 (),
and its effect applies only to the data range written by the system call.
.TP
.BR 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
.B O_DIRECT
flag.)
.TP
.BR RWF_SYNC " (since Linux 4.7)"
.\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9
Provide a per-write equivalent of the
.B O_SYNC
.BR open (2)
flag.
This flag is meaningful only for
.BR pwritev2 (),
and its effect applies only to the data range written by the system call.
.TP
.BR RWF_NOWAIT " (since Linux 4.14)"
.\" commit 3239d834847627b6634a4139cf1dc58f6f137a46
.\" commit 91f9943e1c7b6638f27312d03fe71fcc67b23571
Do not wait for data which is not immediately available.
If this flag is specified, the
.BR 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
.I errno
to
.B EAGAIN
(but see
.BR BUGS ).
Currently, this flag is meaningful only for
.BR preadv2 ().
.TP
.BR RWF_APPEND " (since Linux 4.16)"
.\" commit e1fc742e14e01d84d9693c4aca4ab23da65811fb
Provide a per-write equivalent of the
.B O_APPEND
.BR open (2)
flag.
This flag is meaningful only for
.BR pwritev2 (),
and its effect applies only to the data range written by the system call.
The
.I offset
argument does not affect the write operation;
the data is always appended to the end of the file.
However, if the
.I offset
argument is \-1, the current file offset is updated.
.TP
.BR 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
.BR 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
.RI [ stx_atomic_write_unit_min ,
.IR 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
.I iovcnt
for
.BR pwritev2 ()
is given by the value in
.I stx_atomic_write_segments_max.
Torn-write protection only works with
.B 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,
.B O_SYNC
or
.B O_DSYNC
must be specified for
.BR open (2).
The same synchronized I/O guarantees as described in
.BR open (2)
are provided when these flags
or their equivalent flags and system calls are used
(e.g., if
.B RWF_SYNC
is specified for
.BR pwritev2 ()).
.SH RETURN VALUE
On success,
.BR readv (),
.BR preadv (),
and
.BR preadv2 ()
return the number of bytes read;
.BR writev (),
.BR pwritev (),
and
.BR pwritev2 ()
return the number of bytes written.
.P
Note that it is not an error for a successful call to transfer fewer bytes
than requested (see
.BR read (2)
and
.BR write (2)).
.P
On error, \-1 is returned, and \fIerrno\fP is set to indicate the error.
.SH ERRORS
The errors are as given for
.BR read (2)
and
.BR write (2).
Furthermore,
.BR preadv (),
.BR preadv2 (),
.BR pwritev (),
and
.BR pwritev2 ()
can also fail for the same reasons as
.BR lseek (2).
Additionally, the following errors are defined:
.TP
.B EINVAL
The sum of the
.I iov_len
values overflows an
.I ssize_t
value.
.TP
.B EINVAL
If
.B RWF_ATOMIC
is specified,
the combination of the sum of the
.I iov_len
values and the
.I offset
value does not comply with the length and offset torn-write protection rules.
.TP
.B EINVAL
The vector count,
.IR iovcnt ,
is less than zero or greater than the permitted maximum.
If
.B RWF_ATOMIC
is specified,
this maximum is given by the
.I stx_atomic_write_segments_max
value from
.I statx.
.TP
.B EOPNOTSUPP
An unknown flag is specified in \fIflags\fP.
.SH VERSIONS
.SS C library/kernel differences
The raw
.BR preadv ()
and
.BR 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,
.IR offset ,
is unpacked by the wrapper functions into two arguments in the system calls:
.P
.BI "    unsigned long " pos_l ", unsigned long " pos
.P
These arguments contain, respectively, the low order and high order 32 bits of
.IR offset .
.SH STANDARDS
.TP
.BR readv ()
.TQ
.BR writev ()
POSIX.1-2008.
.TP
.BR preadv ()
.TQ
.BR pwritev ()
BSD.
.TP
.BR preadv2 ()
.TQ
.BR pwritev2 ()
Linux.
.SH HISTORY
.TP
.BR readv ()
.TQ
.BR writev ()
POSIX.1-2001,
4.4BSD (first appeared in 4.2BSD).
.\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument,
.\" and \fIint\fP as the return type.
.\" The readv/writev system calls were buggy before Linux 1.3.40.
.\" (Says release.libc.)
.P
.BR preadv (),
.BR pwritev ():
Linux 2.6.30,
glibc 2.10.
.P
.BR preadv2 (),
.BR pwritev2 ():
Linux 4.6,
glibc 2.26.
.SS Historical C library/kernel differences
To deal with the fact that
.B IOV_MAX
was so low on early versions of Linux,
the glibc wrapper functions for
.BR readv ()
and
.BR writev ()
did some extra work if they detected that the underlying kernel
system call failed because this limit was exceeded.
In the case of
.BR readv (),
the wrapper function allocated a temporary buffer large enough
for all of the items specified by
.IR iov ,
passed that buffer in a call to
.BR read (2),
copied data from the buffer to the locations specified by the
.I iov_base
fields of the elements of
.IR iov ,
and then freed the buffer.
The wrapper function for
.BR writev ()
performed the analogous task using a temporary buffer and a call to
.BR write (2).
.P
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.
.SH NOTES
POSIX.1 allows an implementation to place a limit on
the number of items that can be passed in
.IR iov .
An implementation can advertise its limit by defining
.B IOV_MAX
in
.I <limits.h>
or at run time via the return value from
.IR sysconf(_SC_IOV_MAX) .
On modern Linux systems, the limit is 1024.
Back in Linux 2.0 days, this limit was 16.
.\"
.\"
.SH BUGS
Linux 5.9 and Linux 5.10 have a bug where
.BR preadv2 ()
with the
.B RWF_NOWAIT
flag may return 0 even when not at end of file.
.\" See
.\" <https://lore.kernel.org/linux-fsdevel/fea8b16d-5a69-40f9-b123-e84dcd6e8f2e@www.fastmail.com/T/#u>
.\" The bug was introduced in
.\"    efa8480a831 fs: RWF_NOWAIT should imply IOCB_NOIO
.\"and fixed in
.\"    06c0444290 mm/filemap.c: generic_file_buffered_read() now uses find_get_pages_contig
.SH EXAMPLES
The following code sample demonstrates the use of
.BR writev ():
.P
.in +4n
.EX
char          *str0 = "hello ";
char          *str1 = "world\[rs]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);
.EE
.in
.SH SEE ALSO
.BR pread (2),
.BR read (2),
.BR write (2)