Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 427 insertions, 0 deletions

diff --git a/man/man2/readv.2 b/man/man2/readv.2
new file mode 100644
index 0000000..330294d
--- /dev/null
+++ b/man/man2/readv.2
@@ -0,0 +1,427 @@
+.\" 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 2024-05-02 "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.
+.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
+The vector count,
+.IR iovcnt ,
+is less than zero or greater than the permitted maximum.
+.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\en";
+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)