Re: [PATCH] copy_file_range: New function to copy file data

[Rical Jasan <ricaljasan at pacific dot net>]

On 11/17/2017 06:56 AM, Florian Weimer wrote:
> diff --git a/manual/llio.texi b/manual/llio.texi
> index 825fd94e32..d56dadae12 100644
> --- a/manual/llio.texi
> +++ b/manual/llio.texi
> @@ -41,6 +41,7 @@ directly.)
>  * Stream/Descriptor Precautions::       Precautions needed if you use both
>                                           descriptors and streams.
>  * Scatter-Gather::                      Fast I/O to discontinuous buffers.
> +* Copying File Data::                   Copying data between files.
>  * Memory-mapped I/O::                   Using files like memory.
>  * Waiting for I/O::                     How to check for input or output
>  					 on multiple file descriptors.
> @@ -1363,6 +1364,80 @@ may be easier to use than these functions.  However, @code{readv} and
>  (as opposed to the total output), are large.  In that case, a high-level
>  stream would not be able to cache the data efficiently.
>  
> +@node Copying File Data
> +@section Copying data between two files
> +@cindex copying files
> +@cindex file copy
> +
> +A special function is provided to copy data between two files on the
> +same file system.  The system can optimize such copy operations.  This
> +is particularly important on network file systems, where the data would
> +otherwise have to be transferred twice over the network.
> +
> +Note that this function only copies file data, but not metadata such as
> +file permissions or extended attributes.
> +
> +@deftypefun ssize_t copy_file_range (int @var{inputfd}, off64_t *@var{inputpos}, int @var{outputfd}, off64_t *@var{outputpos}, ssize_t @var{length}, unsigned int @var{flags})
> +@standards{GNU, unistd.h}
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +
> +This function copies up to @var{length} bytes from the file descriptor
> +@var{inputfd} to the file descriptor @var{outputfd}.
> +
> +The function can operate on both the current file position (like
> +@code{read} and @code{write}) and an explicit offset (like @code{pread}
> +and @code{pwrite}).  If the @var{inputpos} pointer is null, the file
> +position of @var{inputfd} is used as the starting point of the copy
> +operation, and the file position is advanced during it.  If
> +@var{inputpos} is not null, then @code{*@var{inputpos}} is used as the
> +starting point of the copy operation, and @code{*@var{inputpos}} is
> +incremented by the number of copied bytes, but the file position remains
> +unchanged.  Similar rules apply to @var{outputfd} and @var{outputpos}
> +for the output file position.
> +
> +The @var{flags} argument is currently reserved and must be zero.
> +
> +The @code{copy_file_range} function returns the number of bytes copied.
> +This can be less than the specified @var{length} in case the input file
> +contains fewer remaining bytes than @var{length}, or if a read or write
> +failure occurs.  The return value is zero if the end of the input file
> +is encountered immediately.
> +
> +If no bytes can be copied, to report an error, @code{copy_file_range}
> +returns the value @math{-1} and sets @code{errno}.  The following

Perhaps others will weigh in, but I lean towards @code for return
values.  The manual clearly doesn't have a preference at this point,
though, and uses both heavily.

> +@code{errno} error conditions are specific to this function.

"function:"

> +
> +@table @code
> +@item EISDIR
> +At least one of the descriptors @var{inputfd} or @var{outputfd} refers
> +to a directory.
> +
> +@item EINVAL
> +At least one of the descriptors @var{inputfd} or @var{outputfd} refers
> +to a non-regular, non-directory file (such as a socket or a FIFO).
> +
> +The @var{flags} argument is not zero.
> +
> +@item EBADF
> +The argument @var{inputfd} is not a valid file descriptor open for
> +reading.
> +
> +The argument @var{outputfd} is not a valid file descriptor open for
> +writing, or @var{outputfd} has been opened with @code{O_APPEND}.
> +
> +@item EXDEV
> +The input and output files reside on different file systems.
> +@end table
> +
> +In addition, @code{copy_file_range} can result with the error codes

"can result in" (or maybe change "result" to something different)

> +which are used by @code{read}, @code{pread}, @code{write}, and
> +@code{pwrite}.
> +
> +The @code{copy_file_range} is a cancellation point.  In case of

"The ... function" (or drop "The")

> +cancellation, the input location (the file position or the value at
> +@code{@var{inputpos}}) is indeterminate.

Did you mean @code{*@var{inputpos}}?  (That isn't a stamp of approval on
how we should format dereferencing; I've been arguing with myself over
that for a long time, but this form at least has precedent, so is fine.)

Thank you,
Rical