From patchwork Thu May 4 12:43:10 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Adhemerval Zanella Netto X-Patchwork-Id: 20271 Received: (qmail 62701 invoked by alias); 4 May 2017 12:43:21 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 62686 invoked by uid 89); 4 May 2017 12:43:20 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-25.1 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_NONE, SPF_PASS autolearn=ham version=3.3.2 spammy= X-HELO: mail-ua0-f171.google.com X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id; bh=nScFgy+tUMY91PCriMsOOzDIWiVYjf88ji2grqIg2FE=; b=BA7XsZHgchelvcFlCjtTAGeXjVYDyOBRe1wTMqZ7EKldJ7lv3xSum3DB7XqKau18V9 tbylAYezsy2QDSJDSQ6TcM+FQOLExdCzvu2xjDOJ/YdZLI7AZg3FFPo/B8c3yAGnBuWn xn20sx0iKjLqNUm1WGMIUXa+9CnmOlSAxPCQ2fsstoKssrDUrdrTru/4rA3iYfMmlq7R 7XRmpmoIzR6IXr2UDyyKdhre8bW6IVfRjBvBzT6aMdvkjTItcIUM6h+YlpYIWgxVcpkj mkhsmml+/dWE3R9YQp9ypCeuZe60tTRKdCgPDswrSYE01+V6X1FJ8WOyy9mJV1bPwtwO dLXA== X-Gm-Message-State: AN3rC/7DV3HMUyNvVqeBLMP1t2PYrB4vzQWCzCgnPw50t9TFrl9g1GC5 g6HUl3jAH+ssq+WCNfTBvw== X-Received: by 10.176.86.23 with SMTP id y23mr13916012uaa.57.1493901798548; Thu, 04 May 2017 05:43:18 -0700 (PDT) From: Adhemerval Zanella To: libc-alpha@sourceware.org Subject: [PATCH v2 1/2] manual: Add preadv and pwritev documentation Date: Thu, 4 May 2017 09:43:10 -0300 Message-Id: <1493901791-13438-1-git-send-email-adhemerval.zanella@linaro.org> 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 + * 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