public inbox for libc-alpha@sourceware.org
 help / color / mirror / Atom feed
* [PATCH v2 1/2] manual: Add preadv and pwritev documentation
@ 2017-05-04 12:43 Adhemerval Zanella
  2017-05-04 12:43 ` [PATCH v3 2/2] posix: Implement preadv2 and pwritev2 Adhemerval Zanella
  2017-05-04 12:51 ` [PATCH v2 1/2] manual: Add preadv and pwritev documentation Florian Weimer
  0 siblings, 2 replies; 38+ messages in thread
From: Adhemerval Zanella @ 2017-05-04 12:43 UTC (permalink / raw)
  To: libc-alpha

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(+)

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
-- 
2.7.4

^ permalink raw reply	[flat|nested] 38+ messages in thread
end of thread, other threads:[~2017-06-05 13:37 UTC | newest]

Thread overview: 38+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-05-04 12:43 [PATCH v2 1/2] manual: Add preadv and pwritev documentation Adhemerval Zanella
2017-05-04 12:43 ` [PATCH v3 2/2] posix: Implement preadv2 and pwritev2 Adhemerval Zanella
2017-05-11 19:02   ` Adhemerval Zanella
2017-05-30 14:19     ` Adhemerval Zanella
2017-05-31 18:51       ` Adhemerval Zanella
2017-06-01 16:40   ` Siddhesh Poyarekar
2017-06-01 18:14     ` Adhemerval Zanella
2017-06-02 13:00       ` H.J. Lu
2017-06-02 13:04         ` Zack Weinberg
2017-06-02 13:34           ` Florian Weimer
2017-06-02 14:07             ` Adhemerval Zanella
2017-06-02 14:22               ` Zack Weinberg
2017-06-02 18:20                 ` Adhemerval Zanella
2017-06-02 19:02                   ` Florian Weimer
2017-06-02 19:46                     ` Adhemerval Zanella
2017-06-03  1:47                       ` H.J. Lu
2017-06-03  8:22                         ` Andreas Schwab
2017-06-03 11:04                           ` H.J. Lu
2017-06-03 11:23                             ` Florian Weimer
2017-06-03 11:27                               ` H.J. Lu
2017-06-03 11:29                                 ` H.J. Lu
2017-06-03 12:52                                   ` Andreas Schwab
2017-06-03 12:57                                     ` H.J. Lu
2017-06-03 13:48                                 ` Zack Weinberg
2017-06-03 13:52                                   ` H.J. Lu
2017-06-03 13:58                                     ` Zack Weinberg
2017-06-03 14:16                                       ` H.J. Lu
2017-06-03 15:28                                         ` Andreas Schwab
2017-06-04 13:42                                           ` H.J. Lu
2017-06-04 15:03                                             ` Zack Weinberg
2017-06-05 13:37                                             ` Adhemerval Zanella
2017-06-02 13:04       ` Tulio Magno Quites Machado Filho
2017-06-02 14:04         ` Adhemerval Zanella
2017-05-04 12:51 ` [PATCH v2 1/2] manual: Add preadv and pwritev documentation Florian Weimer
2017-05-04 13:47   ` Adhemerval Zanella
2017-05-04 18:46     ` Adhemerval Zanella
2017-05-04 18:46       ` Florian Weimer
2017-05-04 18:53         ` Adhemerval Zanella

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).