COPY_FILE_RANGE(2)        FreeBSD System Calls Manual       COPY_FILE_RANGE(2)

NAME

     copy_file_range - kernel copy of a byte range from one regular file to
     another or within one regular file

LIBRARY

     Standard C Library (libc, -lc)

SYNOPSIS

     #include <sys/types.h>
     #include <unistd.h>

     ssize_t
     copy_file_range(int infd, off_t *inoffp, int outfd, off_t *outoffp,
         size_t len, unsigned int flags);

DESCRIPTION

     The copy_file_range() system call copies up to len bytes from infd to
     outfd in the kernel.  It may do this using a file system specific
     technique if infd and outfd are on the same file system.  If infd and
     outfd refer to the same file, the byte ranges defined by the input file
     offset, output file offset and len cannot overlap.  The infd argument
     must be opened for reading and the outfd argument must be opened for
     writing, but not O_APPEND.

     If inoffp or outoffp is NULL, the file offset for infd or outfd
     respectively will be used and updated by the number of bytes copied.  If
     inoffp or outoffp is not NULL, the byte offset pointed to by inoffp or
     outoffp respectively will be used/updated and the file offset for infd or
     outfd respectively will not be affected.

     The only flags argument currently defined is COPY_FILE_RANGE_CLONE.  When
     this flag is set, copy_file_range() will return EOPNOTSUPP if the copy
     cannot be done via block cloning.  When flags is 0, a file system may do
     the copy via block cloning or by data copying.  Block cloning is only
     possible when the offsets (plus len if not to EOF on the input file) are
     block aligned.  The correct block alignment can normally be acquired via
     the _PC_CLONE_BLKSIZE query for pathconf(2).

     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 lseek(2) with
     SEEK_HOLE, SEEK_DATA arguments and this system call for the data ranges
     found.

     For best performance, call copy_file_range() with the largest len value
     possible.  It is interruptible on most file systems, so there is no
     penalty for using very large len values, even SSIZE_MAX.

RETURN VALUES

     If it succeeds, the call returns the number of bytes copied, which can be
     fewer than len.  Returning fewer bytes than len does not necessarily
     indicate that EOF was reached.  However, a return of zero for a non-zero
     len argument indicates that the offset for infd is at or beyond EOF.
     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 errno.

ERRORS

     The copy_file_range() system call will fail if:

     [EBADF]            If infd is not open for reading or outfd is not open
                        for writing, or opened for writing with O_APPEND, or
                        if infd and outfd refer to the same file.

     [EFBIG]            If the copy exceeds the process's file size limit or
                        the maximum file size for the file system outfd
                        resides on.

     [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
                        inoffp and outoffp are reset to the initial values for
                        the system call.

     [EINVAL]           infd and outfd refer to the same file and the byte
                        ranges overlap.

     [EINVAL]           The flags argument is not zero.

     [EINVAL]           Either infd or outfd refers to a file object that is
                        not a regular file.

     [EIO]              An I/O error occurred while reading/writing the files.

     [EINTEGRITY]       Corrupted data was detected while reading from a file
                        system.

     [EISDIR]           If either infd or outfd refers to a directory.

     [ENOSPC]           File system that stores outfd is full.

     [EOPNOTSUPP]       Cannot do the copy via block cloning and the
                        COPY_FILE_RANGE_CLONE flags argument is specified.

SEE ALSO

     lseek(2), pathconf(2)

STANDARDS

     The copy_file_range() system call is expected to be compatible with the
     Linux system call of the same name.

HISTORY

     The copy_file_range() function appeared in FreeBSD 13.0.

FreeBSD 15.1-STABLE-HBSD        August 16, 2025             COPY_FILE_RANGE(2)