Copyright (c) 2019 Rick Macklem
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
.Dd December 28, 2023 .Dt COPY_FILE_RANGE 2 .Os .Sh NAME .Nm copy_file_range .Nd kernel copy of a byte range from one regular file to another or within one regular file .Sh LIBRARY .Lb libc .Sh SYNOPSIS n sys/types.h n unistd.h .Ft ssize_t .Fo copy_file_range .Fa "int infd" .Fa "off_t *inoffp" .Fa "int outfd" .Fa "off_t *outoffp" .Fa "size_t len" .Fa "unsigned int flags" .Fc .Sh DESCRIPTION The .Fn copy_file_range system call copies up to .Fa len bytes from .Fa infd to .Fa outfd in the kernel. It may do this using a file system specific technique if .Fa infd and .Fa outfd are on the same file system. If .Fa infd and .Fa outfd refer to the same file, the byte ranges defined by the input file offset, output file offset and .Fa len cannot overlap. The .Fa infd argument must be opened for reading and the .Fa outfd argument must be opened for writing, but not .Dv O_APPEND . If .Fa inoffp or .Fa outoffp is .Dv NULL , the file offset for .Fa infd or .Fa outfd respectively will be used and updated by the number of bytes copied. If .Fa inoffp or .Fa outoffp is not .Dv NULL , the byte offset pointed to by .Fa inoffp or .Fa outoffp respectively will be used/updated and the file offset for .Fa infd or .Fa outfd respectively will not be affected. The .Fa flags argument must be 0.
p This system call attempts to maintain holes in the output file for the byte range being copied. However, this does not always work well. It is recommended that sparse files be copied in a loop using .Xr lseek 2 with .Dv SEEK_HOLE , .Dv SEEK_DATA arguments and this system call for the data ranges found.
p For best performance, call .Fn copy_file_range with the largest .Fa len value possible. It is interruptible on most file systems, so there is no penalty for using very large len values, even SSIZE_MAX.
p .Sh RETURN VALUES If it succeeds, the call returns the number of bytes copied, which can be fewer than .Fa len . Returning fewer bytes than .Fa len does not necessarily indicate that EOF was reached. However, a return of zero for a non-zero .Fa len argument indicates that the offset for .Fa infd is at or beyond EOF. .Fn copy_file_range should be used in a loop until copying of the desired byte range has been completed. If an error has occurred, a -1 is returned and the error code is placed in the global variable .Va errno . .Sh ERRORS The .Fn copy_file_range system call will fail if: l -tag -width Er t Bq Er EBADF If .Fa infd is not open for reading or .Fa outfd is not open for writing, or opened for writing with .Dv O_APPEND , or if .Fa infd and .Fa outfd refer to the same file. t Bq Er EFBIG If the copy exceeds the process's file size limit or the maximum file size for the file system .Fa outfd resides on. t Bq Er EINTR A signal interrupted the system call before it could be completed. This may happen for files on some NFS mounts. When this happens, the values pointed to by .Fa inoffp and .Fa outoffp are reset to the initial values for the system call. t Bq Er EINVAL .Fa infd and .Fa outfd refer to the same file and the byte ranges overlap. t Bq Er EINVAL The .Fa flags argument is not zero. t Bq Er EINVAL Either .Fa infd or .Fa outfd refers to a file object that is not a regular file. t Bq Er EIO An I/O error occurred while reading/writing the files. t Bq Er EINTEGRITY Corrupted data was detected while reading from a file system. t Bq Er EISDIR If either .Fa infd or .Fa outfd refers to a directory. t Bq Er ENOSPC File system that stores .Fa outfd is full. .El .Sh SEE ALSO .Xr lseek 2 .Sh STANDARDS The .Fn copy_file_range system call is expected to be compatible with the Linux system call of the same name. .Sh HISTORY The .Fn copy_file_range function appeared in .Fx 13.0 .