Re: [PATCH 2/6] vfs: vfs: Define new syscalls preadv2,pwritev2

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hello Christoph,

On 03/11/2016 09:53 AM, Christoph Hellwig wrote:
> On Thu, Mar 10, 2016 at 07:15:04PM +0100, Michael Kerrisk (man-pages) wrote:
>> Hi Christoph,
>>
>> On 03/03/2016 04:03 PM, Christoph Hellwig wrote:
>>> From: Milosz Tanski <milosz@adfin.com>
>>>
>>> New syscalls that take an flag argument.   No flags are added yet in this
>>> patch.
>>
>> Are there some man pages patches for these proposed system calls?
> 
> This is what I have:

Thanks. I applied the patch, but I see one point where the doc
and code differ, and I suspect that the code needs to be fixed.
See below.

> ---
>>>From d33a02d56f447a6cb223b3964e1dd894f2921d5c Mon Sep 17 00:00:00 2001
> From: Milosz Tanski <milosz@adfin.com>
> Date: Fri, 11 Mar 2016 10:52:31 +0100
> Subject: 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 <milosz@adfin.com>
> [hch: added RWF_HIPRI documentation]
> Signed-off-by: Christoph Hellwig <hch@lst.de>
> ---
>  man2/readv.2 | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++---------
>  1 file changed, 54 insertions(+), 9 deletions(-)
> 
> diff --git a/man2/readv.2 b/man2/readv.2
> index 93f2b6f..5cba5e2 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
> @@ -166,9 +172,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
> @@ -178,15 +184,43 @@ 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_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 ressources.  (Currently
> +only usable on a file descriptor opened using the
> +.BR O_DIRECT " flag)."
> +
>  .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.
>  
>  Note that is not an error for a successful call to transfer fewer bytes
> @@ -202,9 +236,11 @@ 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:
> @@ -218,12 +254,17 @@ value.
>  .TP
>  .B EINVAL
>  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.

In the case described in the last sentence, the code currently appears
to be returning EOPNOTSUPP. EINVAL is more usual here, so I think the
code needs adjusting. Your thoughts?

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/