| Message ID | 1493901791-13438-1-git-send-email-adhemerval.zanella@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | [v2,1/2] manual: Add preadv and pwritev documentation | expand |
* 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.
diff --git a/ChangeLog b/ChangeLog index 29a6592..fea319a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -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. diff --git a/manual/llio.texi b/manual/llio.texi index 9643bcb..dae3754 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -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
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(+) -- 2.7.4