This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH] copy_file_range: New function to copy file data
- From: Rical Jasan <ricaljasan at pacific dot net>
- To: Florian Weimer <fweimer at redhat dot com>
- Cc: libc-alpha at sourceware dot org
- Date: Sat, 18 Nov 2017 19:17:35 -0800
- Subject: Re: [PATCH] copy_file_range: New function to copy file data
- Authentication-results: sourceware.org; auth=none
- References: <20171117145604.655D24469B999@oldenburg.str.redhat.com>
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