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 March 30, 2020 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 .Sh RETURN VALUES 121If it succeeds, the call returns the number of bytes copied, which can be fewer 122than 123 .Fa len . 124Returning fewer bytes than 125 .Fa len 126does not necessarily indicate that EOF was reached. 127However, a return of zero for a non-zero 128 .Fa len 129argument indicates that the offset for 130 .Fa infd 131is at or beyond EOF. 132 .Fn copy_file_range 133should be used in a loop until copying of the desired byte range has been 134completed. 135If an error has occurred, a \-1 is returned and the error code is placed in 136the global variable 137 .Va errno . 138 .Sh ERRORS 139The 140 .Fn copy_file_range 141system call 142will fail if: 143 .Bl -tag -width Er 144 .It Bq Er EBADF 145If 146 .Fa infd 147is not open for reading or 148 .Fa outfd 149is not open for writing, or opened for writing with 150 .Dv O_APPEND , 151or if 152 .Fa infd 153and 154 .Fa outfd 155refer to the same file. 156 .It Bq Er EFBIG 157If the copy exceeds the process's file size limit or the maximum file size 158for the file system 159 .Fa outfd 160resides on. 161 .It Bq Er EINTR 162A signal interrupted the system call 163before it could be completed. 164This may happen for files on some NFS mounts. 165When this happens, the values pointed to by 166 .Fa inoffp 167and 168 .Fa outoffp 169are reset to the initial values for the system call. 170 .It Bq Er EINVAL 171 .Fa infd 172and 173 .Fa outfd 174refer to the same file and the byte ranges overlap or 175 .Fa flags 176is not zero. 177 .It Bq Er EIO 178An I/O error occurred while reading/writing the files. 179 .It Bq Er EINTEGRITY 180Corrupted data was detected while reading from a file system. 181 .It Bq Er EISDIR 182If either 183 .Fa infd 184or 185 .Fa outfd 186refers to a directory. 187 .It Bq Er ENOSPC 188File system that stores 189 .Fa outfd 190is full. 191 .El 192 .Sh SEE ALSO 193 .Xr lseek 2 194 .Sh STANDARDS 195The 196 .Fn copy_file_range 197system call is expected to be compatible with the Linux system call of 198the same name. 199 .Sh HISTORY 200The 201 .Fn copy_file_range 202function appeared in 203 .Fx 13.0 . 204