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