GNU C Library master sources branch master updated. glibc-2.26.9000-792-gf6e965e

[fw at sourceware dot org]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU C Library master sources".

The branch, master has been updated
       via  f6e965ee94b37289f64ecd3253021541f7c214c3 (commit)
      from  5f9d19490b24a28e1445a8ed30cdcc727be6432c (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
http://sourceware.org/git/gitweb.cgi?p=glibc.git;a=commitdiff;h=f6e965ee94b37289f64ecd3253021541f7c214c3

commit f6e965ee94b37289f64ecd3253021541f7c214c3
Author: Florian Weimer <fweimer@redhat.com>
Date:   Sun Nov 19 08:58:31 2017 +0100

    manual: Move preadv/writev variants to Scatter-Gather section
    
    Also remove a comment about performance.  fwrite vs writev performance
    is a very complex topic and cannot be reduced to a simple advice based
    on transfer size.

diff --git a/ChangeLog b/ChangeLog
index 6071316..06e88aa 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2017-11-19  Florian Weimer  <fweimer@redhat.com>
+
+	* manual/llio.texi (I/O Primitives): Move preadv, preadv64,
+	pwritev, pwritev64, preadv2, preadv64v2, pwritev2, pwritev64v2 ...
+	(Scatter-Gather): ... to here.  Remove misleading comment.
+
 2017-11-18  Christian Brauner <christian.brauner@ubuntu.com>
 
 	* support/support_become_root.c (setup_uid_gid_mapping): Fix comment
diff --git a/manual/llio.texi b/manual/llio.texi
index 10ad546..ff88805 100644
--- a/manual/llio.texi
+++ b/manual/llio.texi
@@ -654,210 +654,6 @@ 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
 
-@deftypefun ssize_t preadv (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
-@standards{BSD, sys/uio.h}
-@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
-
-@deftypefun ssize_t preadv64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset})
-@standards{BSD, unistd.h}
-@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
-
-@deftypefun ssize_t pwritev (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
-@standards{BSD, sys/uio.h}
-@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.
-
-However, on Linux, if a file is opened with @code{O_APPEND},  @code{pwrite}
-appends data to the end of the file, regardless of the value of
-@code{offset}.
-
-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
-
-@deftypefun ssize_t pwritev64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset})
-@standards{BSD, unistd.h}
-@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
-
-@deftypefun ssize_t preadv2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags})
-@standards{GNU, sys/uio.h}
-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-@c This is a syscall for Linux v4.6.  The sysdeps/posix fallback emulation
-@c is also MT-Safe since it calls preadv.
-
-This function is similar to the @code{preadv} function, with the difference
-it adds an extra @var{flags} parameter of type @code{int}.  The supported
-@var{flags} are dependent of the underlying system.  For Linux it supports:
-
-@vtable @code
-@item RWF_HIPRI
-High priority request.  This adds a flag that tells the file system that
-this is a high priority request for which it is worth to poll the hardware.
-The flag is purely advisory and can be ignored if not supported.  The
-@var{fd} must be opened using @code{O_DIRECT}.
-
-@item RWF_DSYNC
-Per-IO synchronization as if the file was opened with @code{O_DSYNC} flag.
-
-@item RWF_SYNC
-Per-IO synchronization as if the file was opened with @code{O_SYNC} flag.
-
-@item RWF_NOWAIT
-Use nonblocking mode for this operation; that is, this call to @code{preadv2}
-will fail and set @code{errno} to @code{EAGAIN} if the operation would block.
-@end vtable
-
-When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
-@code{preadv2} function is in fact @code{preadv64v2} 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{preadv} with the addition of:
-
-@table @code
-
-@item EOPNOTSUPP
-
-@c The default sysdeps/posix code will return it for any flags value
-@c different than 0.
-An unsupported @var{flags} was used.
-
-@end table
-
-@end deftypefun
-
-@deftypefun ssize_t preadv64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags})
-@standards{GNU, unistd.h}
-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-@c This is a syscall for Linux v4.6.  The sysdeps/posix fallback emulation
-@c is also MT-Safe since it calls preadv.
-
-This function is similar to the @code{preadv2} 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{preadv2} and so transparently replaces the 32 bit interface.
-@end deftypefun
-
-
-@deftypefun ssize_t pwritev2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags})
-@standards{GNU, sys/uio.h}
-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-@c This is a syscall for Linux v4.6.  The sysdeps/posix fallback emulation
-@c is also MT-Safe since it calls pwritev.
-
-This function is similar to the @code{pwritev} function, with the difference
-it adds an extra @var{flags} parameter of type @code{int}.  The supported
-@var{flags} are dependent of the underlying system and for Linux it supports
-the same ones as for @code{preadv2}.
-
-When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
-@code{pwritev2} function is in fact @code{pwritev64v2} 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) write, @math{0}
-indicating end-of-file, or @math{-1} indicating an error.  The possible
-errors are the same as in @code{preadv2}.
-@end deftypefun
-
-@deftypefun ssize_t pwritev64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags})
-@standards{GNU, unistd.h}
-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-@c This is a syscall for Linux v4.6.  The sysdeps/posix fallback emulation
-@c is also MT-Safe since it calls pwritev.
-
-This function is similar to the @code{pwritev2} 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{pwritev2} and so transparently replaces the 32 bit interface.
-@end deftypefun
-
-
 @node File Position Primitive
 @section Setting the File Position of a Descriptor
 
@@ -1354,14 +1150,208 @@ error.  The possible errors are the same as in @code{write}.
 
 @end deftypefun
 
-@c Note - I haven't read this anywhere.  I surmised it from my knowledge
-@c of computer science.  Thus, there could be subtleties I'm missing.
+@deftypefun ssize_t preadv (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
+@standards{BSD, sys/uio.h}
+@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
+
+@deftypefun ssize_t preadv64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset})
+@standards{BSD, unistd.h}
+@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
+
+@deftypefun ssize_t pwritev (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
+@standards{BSD, sys/uio.h}
+@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.
+
+However, on Linux, if a file is opened with @code{O_APPEND},  @code{pwrite}
+appends data to the end of the file, regardless of the value of
+@code{offset}.
+
+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
+
+@deftypefun ssize_t pwritev64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset})
+@standards{BSD, unistd.h}
+@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
+
+@deftypefun ssize_t preadv2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags})
+@standards{GNU, sys/uio.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux v4.6.  The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls preadv.
+
+This function is similar to the @code{preadv} function, with the difference
+it adds an extra @var{flags} parameter of type @code{int}.  The supported
+@var{flags} are dependent of the underlying system.  For Linux it supports:
+
+@vtable @code
+@item RWF_HIPRI
+High priority request.  This adds a flag that tells the file system that
+this is a high priority request for which it is worth to poll the hardware.
+The flag is purely advisory and can be ignored if not supported.  The
+@var{fd} must be opened using @code{O_DIRECT}.
+
+@item RWF_DSYNC
+Per-IO synchronization as if the file was opened with @code{O_DSYNC} flag.
+
+@item RWF_SYNC
+Per-IO synchronization as if the file was opened with @code{O_SYNC} flag.
+
+@item RWF_NOWAIT
+Use nonblocking mode for this operation; that is, this call to @code{preadv2}
+will fail and set @code{errno} to @code{EAGAIN} if the operation would block.
+@end vtable
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{preadv2} function is in fact @code{preadv64v2} 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{preadv} with the addition of:
+
+@table @code
+
+@item EOPNOTSUPP
+
+@c The default sysdeps/posix code will return it for any flags value
+@c different than 0.
+An unsupported @var{flags} was used.
+
+@end table
+
+@end deftypefun
+
+@deftypefun ssize_t preadv64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags})
+@standards{GNU, unistd.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux v4.6.  The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls preadv.
 
-Note that if the buffers are small (under about 1kB), high-level streams
-may be easier to use than these functions.  However, @code{readv} and
-@code{writev} are more efficient when the individual buffers themselves
-(as opposed to the total output), are large.  In that case, a high-level
-stream would not be able to cache the data efficiently.
+This function is similar to the @code{preadv2} 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{preadv2} and so transparently replaces the 32 bit interface.
+@end deftypefun
+
+
+@deftypefun ssize_t pwritev2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags})
+@standards{GNU, sys/uio.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux v4.6.  The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls pwritev.
+
+This function is similar to the @code{pwritev} function, with the difference
+it adds an extra @var{flags} parameter of type @code{int}.  The supported
+@var{flags} are dependent of the underlying system and for Linux it supports
+the same ones as for @code{preadv2}.
+
+When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
+@code{pwritev2} function is in fact @code{pwritev64v2} 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) write, @math{0}
+indicating end-of-file, or @math{-1} indicating an error.  The possible
+errors are the same as in @code{preadv2}.
+@end deftypefun
+
+@deftypefun ssize_t pwritev64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags})
+@standards{GNU, unistd.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c This is a syscall for Linux v4.6.  The sysdeps/posix fallback emulation
+@c is also MT-Safe since it calls pwritev.
+
+This function is similar to the @code{pwritev2} 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{pwritev2} and so transparently replaces the 32 bit interface.
+@end deftypefun
 
 @node Memory-mapped I/O
 @section Memory-mapped I/O

-----------------------------------------------------------------------

Summary of changes:
 ChangeLog        |    6 +
 manual/llio.texi |  412 ++++++++++++++++++++++++++----------------------------
 2 files changed, 207 insertions(+), 211 deletions(-)


hooks/post-receive
-- 
GNU C Library master sources