[v2,1/2] manual: Add preadv and pwritev documentation
Commit Message
Change from previous version:
* Fix typo in pwritev64 naming.
--
* manual/llio.texi: Add preadv and pwritev documentation.
---
ChangeLog | 2 ++
manual/llio.texi | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 96 insertions(+)
Comments
* Adhemerval Zanella:
> +@comment sys/uio.h
> +@comment BSD
> +@deftypefun ssize_t pwritev (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c This is a syscall for Linux 3.2 for all architectures but microblaze
> +@c (which was added on 3.15). The sysdeps/posix fallback emulation
> +@c is also MT-Safe since it calls pwrite, and it is now a syscall on all
> +@c targets.
> +
> +This function is similar to the @code{writev} function, with the difference
> +it adds an extra @var{offset} parameter of type @code{off_t} similar to
> +@code{pwrite}. The data is written to the file starting at position
> +@var{offset}. The position of the file descriptor itself is not affected
> +by the operation. The value is the same as before the call.
This description is incorrect for O_APPEND descriptors. pwrite
ignores the offset for them, and so does pwritev. Maybe you can fix
pwrite as well in this commit?
(The GNU implementation is not POSIX-conforming, probably because the
POSIX specification introduces a security hole.)
> +When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
> +@code{pwritev} function is in fact @code{pwritev64} and the type
> +@code{off_t} has 64 bits, which makes it possible to handle files up to
> +@twoexp{63} bytes in length.
> +
> +The return value is a count of bytes (@emph{not} buffers) written, @math{0}
> +indicating end-of-file, or @math{-1} indicating an error. The possible
> +errors are the same as in @code{writev} and @code{pwrite}.
The end-of-file part does not make sense here. I don't know what the
out-of-space behavior of our implementation is (could be 0, could be
ENOSPC).
On 04/05/2017 09:51, Florian Weimer wrote:
> * Adhemerval Zanella:
>
>> +@comment sys/uio.h
>> +@comment BSD
>> +@deftypefun ssize_t pwritev (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
>> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
>> +@c This is a syscall for Linux 3.2 for all architectures but microblaze
>> +@c (which was added on 3.15). The sysdeps/posix fallback emulation
>> +@c is also MT-Safe since it calls pwrite, and it is now a syscall on all
>> +@c targets.
>> +
>> +This function is similar to the @code{writev} function, with the difference
>> +it adds an extra @var{offset} parameter of type @code{off_t} similar to
>> +@code{pwrite}. The data is written to the file starting at position
>> +@var{offset}. The position of the file descriptor itself is not affected
>> +by the operation. The value is the same as before the call.
>
> This description is incorrect for O_APPEND descriptors. pwrite
> ignores the offset for them, and so does pwritev. Maybe you can fix
> pwrite as well in this commit?
>
> (The GNU implementation is not POSIX-conforming, probably because the
> POSIX specification introduces a security hole.)
Right, I will update the documentation.
>
>> +When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
>> +@code{pwritev} function is in fact @code{pwritev64} and the type
>> +@code{off_t} has 64 bits, which makes it possible to handle files up to
>> +@twoexp{63} bytes in length.
>> +
>> +The return value is a count of bytes (@emph{not} buffers) written, @math{0}
>> +indicating end-of-file, or @math{-1} indicating an error. The possible
>> +errors are the same as in @code{writev} and @code{pwrite}.
>
> The end-of-file part does not make sense here. I don't know what the
> out-of-space behavior of our implementation is (could be 0, could be
> ENOSPC).
>
AFAIk Linux pwritev does return ENOSPC, however I did not check our fallback
implementation regarding it. It is currently used only on microblaze, so
I am not sure if we just update the documentation to reflect it or if we
aim to check/fix the default sysdeps/posix as well.
On 04/05/2017 10:47, Adhemerval Zanella wrote:
> On 04/05/2017 09:51, Florian Weimer wrote:
>> * Adhemerval Zanella:
>>
>>> +@comment sys/uio.h
>>> +@comment BSD
>>> +@deftypefun ssize_t pwritev (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
>>> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
>>> +@c This is a syscall for Linux 3.2 for all architectures but microblaze
>>> +@c (which was added on 3.15). The sysdeps/posix fallback emulation
>>> +@c is also MT-Safe since it calls pwrite, and it is now a syscall on all
>>> +@c targets.
>>> +
>>> +This function is similar to the @code{writev} function, with the difference
>>> +it adds an extra @var{offset} parameter of type @code{off_t} similar to
>>> +@code{pwrite}. The data is written to the file starting at position
>>> +@var{offset}. The position of the file descriptor itself is not affected
>>> +by the operation. The value is the same as before the call.
>>
>> This description is incorrect for O_APPEND descriptors. pwrite
>> ignores the offset for them, and so does pwritev. Maybe you can fix
>> pwrite as well in this commit?
>>
>> (The GNU implementation is not POSIX-conforming, probably because the
>> POSIX specification introduces a security hole.)
>
> Right, I will update the documentation.
I added the paragraph:
--
However, on Linux, if a file is opened with @code{O_APPEND}, pwrite appends
data to the end of the file, regardless of the value of offset.
--
just after the one describing the offset argument.
>
>>
>>> +When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
>>> +@code{pwritev} function is in fact @code{pwritev64} and the type
>>> +@code{off_t} has 64 bits, which makes it possible to handle files up to
>>> +@twoexp{63} bytes in length.
>>> +
>>> +The return value is a count of bytes (@emph{not} buffers) written, @math{0}
>>> +indicating end-of-file, or @math{-1} indicating an error. The possible
>>> +errors are the same as in @code{writev} and @code{pwrite}.
>>
>> The end-of-file part does not make sense here. I don't know what the
>> out-of-space behavior of our implementation is (could be 0, could be
>> ENOSPC).
>>
>
> AFAIk Linux pwritev does return ENOSPC, however I did not check our fallback
> implementation regarding it. It is currently used only on microblaze, so
> I am not sure if we just update the documentation to reflect it or if we
> aim to check/fix the default sysdeps/posix as well.
I think we can left it as is, pwritev fallback algorithm uses pwrite (which
is a syscall for all current architectures). And the sysdeps/posix pwrite
also uses write, which should return ENOSPC.
* Adhemerval Zanella:
> I added the paragraph:
>
> --
> However, on Linux, if a file is opened with @code{O_APPEND}, pwrite appends
> data to the end of the file, regardless of the value of offset.
> --
>
> just after the one describing the offset argument.
@code{pwrite} and @var{offset}, please.
On 04/05/2017 15:46, Florian Weimer wrote:
> * Adhemerval Zanella:
>
>> I added the paragraph:
>>
>> --
>> However, on Linux, if a file is opened with @code{O_APPEND}, pwrite appends
>> data to the end of the file, regardless of the value of offset.
>> --
>>
>> just after the one describing the offset argument.
>
> @code{pwrite} and @var{offset}, please.
>
Fixed, I will push it today. Thanks.
@@ -1,5 +1,7 @@
2017-05-02 Adhemerval Zanella <adhemerval.zanella@linaro.org>
+ * manual/llio.texi: Add preadv and pwritev documentation.
+
* include/unistd.h (__pread): Add libc_hidden_proto.
(__pread64): Likewise.
(__pwrite): Likewise.
@@ -662,6 +662,100 @@ When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
@code{pwrite} and so transparently replaces the 32 bit interface.
@end deftypefun
+@comment sys/uio.h
+@comment BSD
+@deftypefun ssize_t preadv (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux 3.2 for all architectures but microblaze
+@c (which was added on 3.15). The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls pread, and it is now a syscall on all
+@c targets.
+
+This function is similar to the @code{readv} function, with the difference
+it adds an extra @var{offset} parameter of type @code{off_t} similar to
+@code{pread}. The data is written to the file starting at position
+@var{offset}. The position of the file descriptor itself is not affected
+by the operation. The value is the same as before the call.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{preadv} function is in fact @code{preadv64} and the type
+@code{off_t} has 64 bits, which makes it possible to handle files up to
+@twoexp{63} bytes in length.
+
+The return value is a count of bytes (@emph{not} buffers) read, @math{0}
+indicating end-of-file, or @math{-1} indicating an error. The possible
+errors are the same as in @code{readv} and @code{pread}.
+@end deftypefun
+
+@comment unistd.h
+@comment BSD
+@deftypefun ssize_t preadv64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux 3.2 for all architectures but microblaze
+@c (which was added on 3.15). The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls pread64, and it is now a syscall on all
+@c targets.
+
+This function is similar to the @code{preadv} function with the difference
+is that the @var{offset} parameter is of type @code{off64_t} instead of
+@code{off_t}. It makes it possible on 32 bit machines to address
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
+file descriptor @code{filedes} must be opened using @code{open64} since
+otherwise the large offsets possible with @code{off64_t} will lead to
+errors with a descriptor in small file mode.
+
+When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
+32 bit machine this function is actually available under the name
+@code{preadv} and so transparently replaces the 32 bit interface.
+@end deftypefun
+
+@comment sys/uio.h
+@comment BSD
+@deftypefun ssize_t pwritev (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux 3.2 for all architectures but microblaze
+@c (which was added on 3.15). The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls pwrite, and it is now a syscall on all
+@c targets.
+
+This function is similar to the @code{writev} function, with the difference
+it adds an extra @var{offset} parameter of type @code{off_t} similar to
+@code{pwrite}. The data is written to the file starting at position
+@var{offset}. The position of the file descriptor itself is not affected
+by the operation. The value is the same as before the call.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{pwritev} function is in fact @code{pwritev64} and the type
+@code{off_t} has 64 bits, which makes it possible to handle files up to
+@twoexp{63} bytes in length.
+
+The return value is a count of bytes (@emph{not} buffers) written, @math{0}
+indicating end-of-file, or @math{-1} indicating an error. The possible
+errors are the same as in @code{writev} and @code{pwrite}.
+@end deftypefun
+
+@comment unistd.h
+@comment BSD
+@deftypefun ssize_t pwritev64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux 3.2 for all architectures but microblaze
+@c (which was added on 3.15). The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls pwrite64, and it is now a syscall on all
+@c targets.
+
+This function is similar to the @code{pwritev} function with the difference
+is that the @var{offset} parameter is of type @code{off64_t} instead of
+@code{off_t}. It makes it possible on 32 bit machines to address
+files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
+file descriptor @code{filedes} must be opened using @code{open64} since
+otherwise the large offsets possible with @code{off64_t} will lead to
+errors with a descriptor in small file mode.
+
+When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
+32 bit machine this function is actually available under the name
+@code{pwritev} and so transparently replaces the 32 bit interface.
+@end deftypefun
+
@node File Position Primitive
@section Setting the File Position of a Descriptor