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