[v2,1/2] manual: Add preadv and pwritev documentation

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
Related show

Commit Message

Adhemerval Zanella May 4, 2017, 12:43 p.m.
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

Comments

Florian Weimer May 4, 2017, 12:51 p.m. | #1
* 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).
Adhemerval Zanella May 4, 2017, 1:47 p.m. | #2
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.
Adhemerval Zanella May 4, 2017, 6:45 p.m. | #3
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.
Florian Weimer May 4, 2017, 6:46 p.m. | #4
* 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.
Adhemerval Zanella May 4, 2017, 6:53 p.m. | #5
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.

Patch

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