Re: [PATCH v2 1/2] manual: Add preadv and pwritev documentation

[Florian Weimer <fw at deneb dot enyo dot de>]

* Adhemerval Zanella:

> +@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.

This description is incorrect for O_APPEND descriptors.  pwrite
ignores the offset for them, and so does pwritev.  Maybe you can fix
pwrite as well in this commit?

(The GNU implementation is not POSIX-conforming, probably because the
POSIX specification introduces a security hole.)

> +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}.

The end-of-file part does not make sense here.  I don't know what the
out-of-space behavior of our implementation is (could be 0, could be
ENOSPC).