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.\" $FreeBSD$ 27.\" 28.Dd January 2, 2021 29.Dt COPY_FILE_RANGE 2 30.Os 31.Sh NAME 32.Nm copy_file_range 33.Nd kernel copy of a byte range from one file to another 34or within one file 35.Sh LIBRARY 36.Lb libc 37.Sh SYNOPSIS 38.In sys/types.h 39.In unistd.h 40.Ft ssize_t 41.Fo copy_file_range 42.Fa "int infd" 43.Fa "off_t *inoffp" 44.Fa "int outfd" 45.Fa "off_t *outoffp" 46.Fa "size_t len" 47.Fa "unsigned int flags" 48.Fc 49.Sh DESCRIPTION 50The 51.Fn copy_file_range 52system call 53copies up to 54.Fa len 55bytes from 56.Fa infd 57to 58.Fa outfd 59in the kernel. 60It may do this using a file system specific technique if 61.Fa infd 62and 63.Fa outfd 64are on the same file system. 65If 66.Fa infd 67and 68.Fa outfd 69refer to the same file, the byte ranges defined by 70the input file offset, output file offset and 71.Fa len 72cannot overlap. 73The 74.Fa infd 75argument must be opened for reading and the 76.Fa outfd 77argument must be opened for writing, but not 78.Dv O_APPEND . 79If 80.Fa inoffp 81or 82.Fa outoffp 83is 84.Dv NULL , 85the file offset for 86.Fa infd 87or 88.Fa outfd 89respectively will be used and updated by 90the number of bytes copied. 91If 92.Fa inoffp 93or 94.Fa outoffp 95is not 96.Dv NULL , 97the byte offset pointed to by 98.Fa inoffp 99or 100.Fa outoffp 101respectively will be used/updated and the file offset for 102.Fa infd 103or 104.Fa outfd 105respectively will not be affected. 106The 107.Fa flags 108argument must be 0. 109.Pp 110This system call attempts to maintain holes in the output file for 111the byte range being copied. 112However, this does not always work well. 113It is recommended that sparse files be copied in a loop using 114.Xr lseek 2 115with 116.Dv SEEK_HOLE , 117.Dv SEEK_DATA 118arguments and this system call for the 119data ranges found. 120.Pp 121For best performance, call 122.Fn copy_file_range 123with the largest 124.Fa len 125value possible. 126It is interruptible on most file systems, 127so there is no penalty for using very large len values, even SSIZE_MAX. 128.Pp 129.Sh RETURN VALUES 130If it succeeds, the call returns the number of bytes copied, which can be fewer 131than 132.Fa len . 133Returning fewer bytes than 134.Fa len 135does not necessarily indicate that EOF was reached. 136However, a return of zero for a non-zero 137.Fa len 138argument indicates that the offset for 139.Fa infd 140is at or beyond EOF. 141.Fn copy_file_range 142should be used in a loop until copying of the desired byte range has been 143completed. 144If an error has occurred, a \-1 is returned and the error code is placed in 145the global variable 146.Va errno . 147.Sh ERRORS 148The 149.Fn copy_file_range 150system call 151will fail if: 152.Bl -tag -width Er 153.It Bq Er EBADF 154If 155.Fa infd 156is not open for reading or 157.Fa outfd 158is not open for writing, or opened for writing with 159.Dv O_APPEND , 160or if 161.Fa infd 162and 163.Fa outfd 164refer to the same file. 165.It Bq Er EFBIG 166If the copy exceeds the process's file size limit or the maximum file size 167for the file system 168.Fa outfd 169resides on. 170.It Bq Er EINTR 171A signal interrupted the system call 172before it could be completed. 173This may happen for files on some NFS mounts. 174When this happens, the values pointed to by 175.Fa inoffp 176and 177.Fa outoffp 178are reset to the initial values for the system call. 179.It Bq Er EINVAL 180.Fa infd 181and 182.Fa outfd 183refer to the same file and the byte ranges overlap or 184.Fa flags 185is not zero. 186.It Bq Er EIO 187An I/O error occurred while reading/writing the files. 188.It Bq Er EINTEGRITY 189Corrupted data was detected while reading from a file system. 190.It Bq Er EISDIR 191If either 192.Fa infd 193or 194.Fa outfd 195refers to a directory. 196.It Bq Er ENOSPC 197File system that stores 198.Fa outfd 199is full. 200.El 201.Sh SEE ALSO 202.Xr lseek 2 203.Sh STANDARDS 204The 205.Fn copy_file_range 206system call is expected to be compatible with the Linux system call of 207the same name. 208.Sh HISTORY 209The 210.Fn copy_file_range 211function appeared in 212.Fx 13.0 . 213