Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751612AbaKFPog (ORCPT ); Thu, 6 Nov 2014 10:44:36 -0500 Received: from mail-qg0-f44.google.com ([209.85.192.44]:62396 "EHLO mail-qg0-f44.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751558AbaKFPob (ORCPT ); Thu, 6 Nov 2014 10:44:31 -0500 From: Milosz Tanski To: linux-kernel@vger.kernel.org Cc: Christoph Hellwig , linux-fsdevel@vger.kernel.org, linux-aio@kvack.org, Mel Gorman , Volker Lendecke , Tejun Heo , Jeff Moyer , "Theodore Ts'o" , Al Viro , linux-api@vger.kernel.org, Michael Kerrisk , linux-man@vger.kernel.org Subject: [PATCH v2 1/2] Add preadv2/pwritev2 documentation. Date: Thu, 6 Nov 2014 10:44:26 -0500 Message-Id: X-Mailer: git-send-email 2.0.0 In-Reply-To: References: Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 .sp .BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt , .BI " off_t " offset ); +.sp +.BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt , +.BI " off_t " offset ", int " flags ); +.sp +.BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt , +.BI " off_t " offset ", int " flags ); .fi .sp .in -4n @@ -162,9 +168,9 @@ The system call combines the functionality of .BR writev () and -.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 () +and +.BR pwritev () +calls, but adds a fifth argument, \fIflags\fP, which modifies the behavior on a per call basis. + +Like the +.BR preadv () +and +.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 () +and +.BR pwritev2 () +contains a bitwise OR of one or more of the following flags: +.TP +.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 ")." + .SH RETURN VALUE On success, -.BR readv () -and +.BR readv () "," .BR preadv () -return the number of bytes read; -.BR writev () and +.BR preadv2 () +return the number of bytes read; +.BR writev () "," .BR pwritev () +and +.BR pwritev2 () return the number of bytes written. On error, \-1 is returned, and \fIerrno\fP is set appropriately. .SH ERRORS @@ -191,12 +223,22 @@ The errors are as given for and .BR write (2). Furthermore, -.BR preadv () -and +.BR preadv () "," +.BR preadv2 () "," .BR pwritev () +and +.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: +.TP +.B EAGAIN +The operation would block. This is possible if the file descriptor \fIfd\fP refers to a socket and has been marked nonblocking +.RB ( O_NONBLOCK ), +or the operation is a +.BR preadv2 +and the \fIflags\fP argument is set to +.BR RWF_NONBLOCK. .TP .B EINVAL The sum of the @@ -205,12 +247,17 @@ values overflows an .I ssize_t value. 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. .SH VERSIONS .BR preadv () and .BR pwritev () first appeared in Linux 2.6.30; library support was added in glibc 2.10. +.sp +.BR preadv2 () +and +.BR pwritev2 () +first appeared in Linux 3.19 (if we're lucky); .SH CONFORMING TO .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. +.sp +.BR preadv2 (), +.BR pwritev2 (): +nonstandard, Linux extension. .SH NOTES .SS C library/kernel ABI differences POSIX.1-2001 allows an implementation to place a limit on -- 1.9.1 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/