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 X-Patchwork-Id: 98531 Delivered-To: patch@linaro.org Received: by 10.140.89.200 with SMTP id v66csp564630qgd; Thu, 4 May 2017 05:43:38 -0700 (PDT) X-Received: by 10.98.88.4 with SMTP id m4mr10810314pfb.41.1493901818209; Thu, 04 May 2017 05:43:38 -0700 (PDT) Return-Path: Received: from sourceware.org (server1.sourceware.org. [209.132.180.131]) by mx.google.com with ESMTPS id d6si1950679pgc.206.2017.05.04.05.43.37 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 04 May 2017 05:43:38 -0700 (PDT) Received-SPF: pass (google.com: domain of libc-alpha-return-79053-patch=linaro.org@sourceware.org designates 209.132.180.131 as permitted sender) client-ip=209.132.180.131; Authentication-Results: mx.google.com; dkim=pass header.i=@sourceware.org; spf=pass (google.com: domain of libc-alpha-return-79053-patch=linaro.org@sourceware.org designates 209.132.180.131 as permitted sender) smtp.mailfrom=libc-alpha-return-79053-patch=linaro.org@sourceware.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org DomainKey-Signature: a=rsa-sha1; c=nofws; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:from:to:subject:date:message-id; q=dns; s= default; b=HYsYUcd33IQwpJ2OYYn8mQQ9JYFU2i78R6VxMGYo2x6tMteaj5GXn Y9x8BdaMPU9VU/CAc5jqaLVmmpWnLkOQM8BX0FJhkIJtruK5I8v4nNqv9fcNgbN/ p2dS9/rebAHKoEdCxAxsRQSvDDifbHq8Whb/szj5qjIo7wOwwhfA/I= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:from:to:subject:date:message-id; s=default; bh=8ztt1rchQ1WHY/Sx5DElc8dRp0A=; b=TzQ42xyMpKQESibKK/c7hQzdUce+ s+nGrglpZsSAl6BRNqVvgpaCDVrzws5HBkrMMvalGzAUT8U3b9cRmI/p+ijpLwev 0ZnPC8doGbcioGHD1ZT8ca8Dl92Apy3TAeeM5YF4Mbrjs7xPR/GQMvPxq0bLl/KH XDDIp0oVi4iqris= 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(+) -- 2.7.4 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