Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
COPY_FILE_RANGE(2)	       System Calls Manual	      COPY_FILE_RANGE(2)

NAME
     copy_file_range -- kernel copy of a byte range from one regular file to an-
     other 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 read-
     ing 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  respec-
     tively  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 re-
     spectively will be used/updated and the file offset for infd or  outfd  re-
     spectively 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 can-
     not 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 recom-
     mended 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  indi-
     cate  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 ports 15.quarterly	 August 16, 2025	      COPY_FILE_RANGE(2)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=copy_file_range&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>

home | help