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.
Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.
This function copies up to length bytes from the file descriptor inputfd to the file descriptor outputfd.
The function can operate on both the current file position (like
write) and an explicit offset (like
pwrite). If the inputpos pointer is null, the file
position of inputfd is used as the starting point of the copy
operation, and the file position is advanced during it. If
inputpos is not null, then
*inputpos is used as the
starting point of the copy operation, and
incremented by the number of copied bytes, but the file position remains
unchanged. Similar rules apply to outputfd and outputpos
for the output file position.
The flags argument is currently reserved and must be zero.
copy_file_range function returns the number of bytes copied.
This can be less than the specified length in case the input file
contains fewer remaining bytes than 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,
returns the value -1 and sets
errno. The table below
lists some of the error conditions for this function.
The kernel does not implement the required functionality.
At least one of the descriptors inputfd or outputfd refers to a directory.
At least one of the descriptors inputfd or outputfd refers to a non-regular, non-directory file (such as a socket or a FIFO).
The input or output positions before are after the copy operations are outside of an implementation-defined limit.
The flags argument is not zero.
The new file size would exceed the process file size limit. See Limiting Resource Usage.
The input or output positions before are after the copy operations are
outside of an implementation-defined limit. This can happen if the file
was not opened with large file support (LFS) on 32-bit machines, and the
copy operation would create a file which is larger than what
off_t could represent.
The argument inputfd is not a valid file descriptor open for reading.
The argument outputfd is not a valid file descriptor open for
writing, or outputfd has been opened with
copy_file_range can fail with the error codes
which are used by
copy_file_range function is a cancellation point. In case of
cancellation, the input location (the file position or the value at
*inputpos) is indeterminate.