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