1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2019 Rick Macklem 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd December 28, 2023 27.Dt COPY_FILE_RANGE 2 28.Os 29.Sh NAME 30.Nm copy_file_range 31.Nd kernel copy of a byte range from one regular file to another 32or within one regular file 33.Sh LIBRARY 34.Lb libc 35.Sh SYNOPSIS 36.In sys/types.h 37.In unistd.h 38.Ft ssize_t 39.Fo copy_file_range 40.Fa "int infd" 41.Fa "off_t *inoffp" 42.Fa "int outfd" 43.Fa "off_t *outoffp" 44.Fa "size_t len" 45.Fa "unsigned int flags" 46.Fc 47.Sh DESCRIPTION 48The 49.Fn copy_file_range 50system call 51copies up to 52.Fa len 53bytes from 54.Fa infd 55to 56.Fa outfd 57in the kernel. 58It may do this using a file system specific technique if 59.Fa infd 60and 61.Fa outfd 62are on the same file system. 63If 64.Fa infd 65and 66.Fa outfd 67refer to the same file, the byte ranges defined by 68the input file offset, output file offset and 69.Fa len 70cannot overlap. 71The 72.Fa infd 73argument must be opened for reading and the 74.Fa outfd 75argument must be opened for writing, but not 76.Dv O_APPEND . 77If 78.Fa inoffp 79or 80.Fa outoffp 81is 82.Dv NULL , 83the file offset for 84.Fa infd 85or 86.Fa outfd 87respectively will be used and updated by 88the number of bytes copied. 89If 90.Fa inoffp 91or 92.Fa outoffp 93is not 94.Dv NULL , 95the byte offset pointed to by 96.Fa inoffp 97or 98.Fa outoffp 99respectively will be used/updated and the file offset for 100.Fa infd 101or 102.Fa outfd 103respectively will not be affected. 104The 105.Fa flags 106argument must be 0. 107.Pp 108This system call attempts to maintain holes in the output file for 109the byte range being copied. 110However, this does not always work well. 111It is recommended that sparse files be copied in a loop using 112.Xr lseek 2 113with 114.Dv SEEK_HOLE , 115.Dv SEEK_DATA 116arguments and this system call for the 117data ranges found. 118.Pp 119For best performance, call 120.Fn copy_file_range 121with the largest 122.Fa len 123value possible. 124It is interruptible on most file systems, 125so there is no penalty for using very large len values, even SSIZE_MAX. 126.Pp 127.Sh RETURN VALUES 128If it succeeds, the call returns the number of bytes copied, which can be fewer 129than 130.Fa len . 131Returning fewer bytes than 132.Fa len 133does not necessarily indicate that EOF was reached. 134However, a return of zero for a non-zero 135.Fa len 136argument indicates that the offset for 137.Fa infd 138is at or beyond EOF. 139.Fn copy_file_range 140should be used in a loop until copying of the desired byte range has been 141completed. 142If an error has occurred, a \-1 is returned and the error code is placed in 143the global variable 144.Va errno . 145.Sh ERRORS 146The 147.Fn copy_file_range 148system call 149will fail if: 150.Bl -tag -width Er 151.It Bq Er EBADF 152If 153.Fa infd 154is not open for reading or 155.Fa outfd 156is not open for writing, or opened for writing with 157.Dv O_APPEND , 158or if 159.Fa infd 160and 161.Fa outfd 162refer to the same file. 163.It Bq Er EFBIG 164If the copy exceeds the process's file size limit or the maximum file size 165for the file system 166.Fa outfd 167resides on. 168.It Bq Er EINTR 169A signal interrupted the system call 170before it could be completed. 171This may happen for files on some NFS mounts. 172When this happens, the values pointed to by 173.Fa inoffp 174and 175.Fa outoffp 176are reset to the initial values for the system call. 177.It Bq Er EINVAL 178.Fa infd 179and 180.Fa outfd 181refer to the same file and the byte ranges overlap. 182.It Bq Er EINVAL 183The 184.Fa flags 185argument is not zero. 186.It Bq Er EINVAL 187Either 188.Fa infd 189or 190.Fa outfd 191refers to a file object that is not a regular file. 192.It Bq Er EIO 193An I/O error occurred while reading/writing the files. 194.It Bq Er EINTEGRITY 195Corrupted data was detected while reading from a file system. 196.It Bq Er EISDIR 197If either 198.Fa infd 199or 200.Fa outfd 201refers to a directory. 202.It Bq Er ENOSPC 203File system that stores 204.Fa outfd 205is full. 206.El 207.Sh SEE ALSO 208.Xr lseek 2 209.Sh STANDARDS 210The 211.Fn copy_file_range 212system call is expected to be compatible with the Linux system call of 213the same name. 214.Sh HISTORY 215The 216.Fn copy_file_range 217function appeared in 218.Fx 13.0 . 219