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.

1 files changed, 201 insertions, 211 deletions

diff --git a/manual/llio.texi b/manual/llio.texi
index 10ad546723..ff88805369 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