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