lib/libc/sys/copy_file_range.2

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