[lkml]   [2014]   [Oct]   [21]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
Patch in this message
Subject[PATCH] Add preadv2/pwritev2 documentation.
New syscalls that are a variation on the preadv/pwritev but support an extra
flag argument.

Signed-off-by: Milosz Tanski <>
Suggested-by: Jeff Moyer <>
Fixes: Jeff Moyer <>
man2/readv.2 | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++---------
1 file changed, 61 insertions(+), 10 deletions(-)

diff --git a/man2/readv.2 b/man2/readv.2
index 8748efa..31b3870 100644
--- a/man2/readv.2
+++ b/man2/readv.2
@@ -45,6 +45,12 @@ readv, writev, preadv, pwritev \- read or write data into multiple buffers
.BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt ,
.BI " off_t " offset );
+.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 );
.in -4n
@@ -162,9 +168,9 @@ The
system call combines the functionality of
.BR writev ()
-.BR pwrite (2).
+.BR pwrite (2) "."
It performs the same task as
-.BR writev (),
+.BR writev () ","
but adds a fourth argument,
.IR offset ,
which specifies the file offset at which the output operation
@@ -174,15 +180,41 @@ 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()
+This pair of system calls has similar functionality to the
+.BR preadv ()
+.BR pwritev ()
+calls, but adds a fifth argument, \fIflags\fP, which modifies the behavior on a per call basis.
+Like the
+.BR preadv ()
+.BR pwritev ()
+calls, they accept an \fIoffset\fP argument. Unlike those calls, if the \fIoffset\fP argument is set to -1 then the current file offset is used and updated.
+The \fIflags\fP arguments to
+.BR preadv2 ()
+.BR pwritev2 ()
+contains a bitwise OR of one or more of the following flags:
+.BR RWF_NONBLOCK " (only " preadv2() " since Linux 3.19)"
+Performs a non-blocking operation for regular files (not sockets) opened in buffered mode (not
+.BR O_DIRECT ")."
On success,
-.BR readv ()
+.BR readv () ","
.BR preadv ()
-return the number of bytes read;
-.BR writev ()
+.BR preadv2 ()
+return the number of bytes read;
+.BR writev () ","
.BR pwritev ()
+.BR pwritev2 ()
return the number of bytes written.
On error, \-1 is returned, and \fIerrno\fP is set appropriately.
@@ -191,12 +223,22 @@ The errors are as given for
.BR write (2).
-.BR preadv ()
+.BR preadv () ","
+.BR preadv2 () ","
.BR pwritev ()
+.BR pwritev2 ()
can also fail for the same reasons as
.BR lseek (2).
-Additionally, the following error is defined:
+Additionally, the following errors are defined:
+The operation would block. This is possible if the file descriptor \fIfd\fP refers to a socket and has been marked nonblocking
+or the operation is a
+.BR preadv2
+and the \fIflags\fP argument is set to
The sum of the
@@ -205,12 +247,17 @@ values overflows an
.I ssize_t
Or, the vector count \fIiovcnt\fP is less than zero or greater than the
-permitted maximum.
+permitted maximum. Or, an unknown flag is specified in \fIflags\fP.
.BR preadv ()
.BR pwritev ()
first appeared in Linux 2.6.30; library support was added in glibc 2.10.
+.BR preadv2 ()
+.BR pwritev2 ()
+first appeared in Linux 3.19 (if we're lucky);
.BR readv (),
.BR writev ():
@@ -223,6 +270,10 @@ first appeared in Linux 2.6.30; library support was added in glibc 2.10.
.BR preadv (),
.BR pwritev ():
nonstandard, but present also on the modern BSDs.
+.BR preadv2 (),
+.BR pwritev2 ():
+nonstandard, Linux extension.
.SS C library/kernel ABI differences
POSIX.1-2001 allows an implementation to place a limit on

 \ /
  Last update: 2014-10-21 23:41    [W:0.157 / U:0.080 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site