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