| 1 |
.\" Copyright 2015, Anna Schumaker <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH copy_file_range 2 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
copy_file_range \- Copy a range of data from one file to another |
| 9 |
.SH LIBRARY |
| 10 |
Standard C library |
| 11 |
.RI ( libc ,\~ \-lc ) |
| 12 |
.SH SYNOPSIS |
| 13 |
.nf |
| 14 |
.B #define _GNU_SOURCE |
| 15 |
.B #define _FILE_OFFSET_BITS 64 |
| 16 |
.B #include <unistd.h> |
| 17 |
.P |
| 18 |
.BI "ssize_t copy_file_range(int " fd_in ", off_t *_Nullable " off_in , |
| 19 |
.BI " int " fd_out ", off_t *_Nullable " off_out , |
| 20 |
.BI " size_t " size ", unsigned int " flags ); |
| 21 |
.fi |
| 22 |
.SH DESCRIPTION |
| 23 |
The |
| 24 |
.BR copy_file_range () |
| 25 |
system call performs an in-kernel copy between two file descriptors |
| 26 |
without the additional cost of transferring data from the kernel to user space |
| 27 |
and then back into the kernel. |
| 28 |
It copies up to |
| 29 |
.I size |
| 30 |
bytes of data from the source file descriptor |
| 31 |
.I fd_in |
| 32 |
to the target file descriptor |
| 33 |
.IR fd_out , |
| 34 |
overwriting any data that exists within the requested range of the target file. |
| 35 |
.P |
| 36 |
The following semantics apply for |
| 37 |
.IR off_in , |
| 38 |
and similar statements apply to |
| 39 |
.IR off_out : |
| 40 |
.IP \[bu] 3 |
| 41 |
If |
| 42 |
.I off_in |
| 43 |
is NULL, then bytes are read from |
| 44 |
.I fd_in |
| 45 |
starting from the file offset, and the file offset is |
| 46 |
adjusted by the number of bytes copied. |
| 47 |
.IP \[bu] |
| 48 |
If |
| 49 |
.I off_in |
| 50 |
is not NULL, then |
| 51 |
.I off_in |
| 52 |
must point to a buffer that specifies the starting |
| 53 |
offset where bytes from |
| 54 |
.I fd_in |
| 55 |
will be read. |
| 56 |
The file offset of |
| 57 |
.I fd_in |
| 58 |
is not changed, but |
| 59 |
.I off_in |
| 60 |
is adjusted appropriately. |
| 61 |
.P |
| 62 |
.I fd_in |
| 63 |
and |
| 64 |
.I fd_out |
| 65 |
can refer to the same file. |
| 66 |
If they refer to the same file, then the source and target ranges are not |
| 67 |
allowed to overlap. |
| 68 |
.P |
| 69 |
The |
| 70 |
.I flags |
| 71 |
argument is provided to allow for future extensions |
| 72 |
and currently must be set to 0. |
| 73 |
.SH RETURN VALUE |
| 74 |
Upon successful completion, |
| 75 |
.BR copy_file_range () |
| 76 |
will return the number of bytes copied between files. |
| 77 |
This could be less than the size originally requested. |
| 78 |
If the file offset of |
| 79 |
.I fd_in |
| 80 |
is at or past the end of file, no bytes are copied, and |
| 81 |
.BR copy_file_range () |
| 82 |
returns zero. |
| 83 |
.P |
| 84 |
On error, |
| 85 |
.BR copy_file_range () |
| 86 |
returns \-1 and |
| 87 |
.I errno |
| 88 |
is set to indicate the error. |
| 89 |
.SH ERRORS |
| 90 |
.TP |
| 91 |
.B EBADF |
| 92 |
One or more file descriptors are not valid. |
| 93 |
.TP |
| 94 |
.B EBADF |
| 95 |
.I fd_in |
| 96 |
is not open for reading; |
| 97 |
or |
| 98 |
.I fd_out |
| 99 |
is not open for writing. |
| 100 |
.TP |
| 101 |
.B EBADF |
| 102 |
The |
| 103 |
.B O_APPEND |
| 104 |
flag is set for the open file description (see |
| 105 |
.BR open (2)) |
| 106 |
referred to by the file descriptor |
| 107 |
.IR fd_out . |
| 108 |
.TP |
| 109 |
.B EFBIG |
| 110 |
An attempt was made to write at a position past the maximum file offset the |
| 111 |
kernel supports. |
| 112 |
.TP |
| 113 |
.B EFBIG |
| 114 |
An attempt was made to write a range that exceeds the allowed maximum file size. |
| 115 |
The maximum file size differs between filesystem implementations and can be |
| 116 |
different from the maximum allowed file offset. |
| 117 |
.TP |
| 118 |
.B EFBIG |
| 119 |
An attempt was made to write beyond the process's file size resource limit. |
| 120 |
This may also result in the process receiving a |
| 121 |
.B SIGXFSZ |
| 122 |
signal. |
| 123 |
.TP |
| 124 |
.B EINVAL |
| 125 |
The |
| 126 |
.I flags |
| 127 |
argument is not 0. |
| 128 |
.TP |
| 129 |
.B EINVAL |
| 130 |
.I fd_in |
| 131 |
and |
| 132 |
.I fd_out |
| 133 |
refer to the same file and the source and target ranges overlap. |
| 134 |
.TP |
| 135 |
.B EINVAL |
| 136 |
Either |
| 137 |
.I fd_in |
| 138 |
or |
| 139 |
.I fd_out |
| 140 |
is not a regular file. |
| 141 |
.TP |
| 142 |
.B EIO |
| 143 |
A low-level I/O error occurred while copying. |
| 144 |
.TP |
| 145 |
.B EISDIR |
| 146 |
Either |
| 147 |
.I fd_in |
| 148 |
or |
| 149 |
.I fd_out |
| 150 |
refers to a directory. |
| 151 |
.TP |
| 152 |
.B ENOMEM |
| 153 |
Out of memory. |
| 154 |
.TP |
| 155 |
.B ENOSPC |
| 156 |
There is not enough space on the target filesystem to complete the copy. |
| 157 |
.TP |
| 158 |
.BR EOPNOTSUPP " (since Linux 5.19)" |
| 159 |
.\" commit 868f9f2f8e004bfe0d3935b1976f625b2924893b |
| 160 |
The filesystem does not support this operation. |
| 161 |
.TP |
| 162 |
.B EOVERFLOW |
| 163 |
The requested source or destination range is too large to represent in the |
| 164 |
specified data types. |
| 165 |
.TP |
| 166 |
.B EPERM |
| 167 |
.I fd_out |
| 168 |
refers to an immutable file. |
| 169 |
.TP |
| 170 |
.B ETXTBSY |
| 171 |
Either |
| 172 |
.I fd_in |
| 173 |
or |
| 174 |
.I fd_out |
| 175 |
refers to an active swap file. |
| 176 |
.TP |
| 177 |
.BR EXDEV " (before Linux 5.3)" |
| 178 |
.\" commit 5dae222a5ff0c269730393018a5539cc970a4726 |
| 179 |
The files referred to by |
| 180 |
.IR fd_in " and " fd_out |
| 181 |
are not on the same filesystem. |
| 182 |
.TP |
| 183 |
.BR EXDEV " (since Linux 5.19)" |
| 184 |
.\" commit 868f9f2f8e004bfe0d3935b1976f625b2924893b |
| 185 |
The files referred to by |
| 186 |
.IR fd_in " and " fd_out |
| 187 |
are not on the same filesystem, |
| 188 |
and the source and target filesystems are not of the same type, |
| 189 |
or do not support cross-filesystem copy. |
| 190 |
.SH VERSIONS |
| 191 |
A major rework of the kernel implementation occurred in Linux 5.3. |
| 192 |
Areas of the API that weren't clearly defined were clarified and the API bounds |
| 193 |
are much more strictly checked than on earlier kernels. |
| 194 |
.P |
| 195 |
Since Linux 5.19, |
| 196 |
cross-filesystem copies can be achieved |
| 197 |
when both filesystems are of the same type, |
| 198 |
and that filesystem implements support for it. |
| 199 |
See BUGS for behavior prior to Linux 5.19. |
| 200 |
.P |
| 201 |
Applications should target the behavior and requirements of Linux 5.19, |
| 202 |
that was also backported to earlier stable kernels. |
| 203 |
.SH STANDARDS |
| 204 |
Linux, GNU. |
| 205 |
.SH HISTORY |
| 206 |
Linux 4.5. |
| 207 |
.P |
| 208 |
.\" glibc.git bad7a0c81f50 (2017-12-22; "copy_file_range: New function to copy file data") |
| 209 |
Before glibc 2.30, starting with glibc 2.27, the glibc wrapper function |
| 210 |
provided a user-space fallback implementation when the kernel did not |
| 211 |
implement this system call. |
| 212 |
.\" glibc.git 5a659ccc0ec2 (2019-06-28; "io: Remove copy_file_range emulation [BZ #24744]") |
| 213 |
Since glibc 2.30, that fallback has been removed; the function now |
| 214 |
fails with ENOSYS if the kernel lacks support for .BR copy_file_range (). |
| 215 |
.SH NOTES |
| 216 |
If |
| 217 |
.I fd_in |
| 218 |
is a sparse file, then |
| 219 |
.BR copy_file_range () |
| 220 |
may expand any holes existing in the requested range. |
| 221 |
Users may benefit from calling |
| 222 |
.BR copy_file_range () |
| 223 |
in a loop, and using the |
| 224 |
.BR lseek (2) |
| 225 |
.B SEEK_DATA |
| 226 |
and |
| 227 |
.B SEEK_HOLE |
| 228 |
operations to find the locations of data segments. |
| 229 |
.P |
| 230 |
.BR copy_file_range () |
| 231 |
gives filesystems an opportunity to implement "copy acceleration" techniques, |
| 232 |
such as the use of reflinks (i.e., two or more inodes that share |
| 233 |
pointers to the same copy-on-write disk blocks) |
| 234 |
or server-side-copy (in the case of NFS). |
| 235 |
.P |
| 236 |
.B _FILE_OFFSET_BITS |
| 237 |
should be defined to be 64 in code that uses non-null |
| 238 |
.I off_in |
| 239 |
or |
| 240 |
.I off_out |
| 241 |
or that takes the address of |
| 242 |
.BR copy_file_range , |
| 243 |
if the code is intended to be portable |
| 244 |
to traditional 32-bit x86 and ARM platforms where |
| 245 |
.BR off_t 's |
| 246 |
width defaults to 32 bits. |
| 247 |
.SH BUGS |
| 248 |
In Linux 5.3 to Linux 5.18, |
| 249 |
cross-filesystem copies were implemented by the kernel, |
| 250 |
if the operation was not supported by individual filesystems. |
| 251 |
However, on some virtual filesystems, |
| 252 |
the call failed to copy, while still reporting success. |
| 253 |
.SH EXAMPLES |
| 254 |
.\" SRC BEGIN (copy_file_range.c) |
| 255 |
.EX |
| 256 |
#define _GNU_SOURCE |
| 257 |
#define _FILE_OFFSET_BITS 64 |
| 258 |
#include <fcntl.h> |
| 259 |
#include <stdio.h> |
| 260 |
#include <stdlib.h> |
| 261 |
#include <sys/stat.h> |
| 262 |
#include <sys/types.h> |
| 263 |
#include <unistd.h> |
| 264 |
\& |
| 265 |
int |
| 266 |
main(int argc, char *argv[]) |
| 267 |
{ |
| 268 |
int fd_in, fd_out; |
| 269 |
off_t size, ret; |
| 270 |
struct stat stat; |
| 271 |
\& |
| 272 |
if (argc != 3) { |
| 273 |
fprintf(stderr, "Usage: %s <source> <destination>\[rs]n", argv[0]); |
| 274 |
exit(EXIT_FAILURE); |
| 275 |
} |
| 276 |
\& |
| 277 |
fd_in = open(argv[1], O_RDONLY); |
| 278 |
if (fd_in == \-1) { |
| 279 |
perror("open (argv[1])"); |
| 280 |
exit(EXIT_FAILURE); |
| 281 |
} |
| 282 |
\& |
| 283 |
if (fstat(fd_in, &stat) == \-1) { |
| 284 |
perror("fstat"); |
| 285 |
exit(EXIT_FAILURE); |
| 286 |
} |
| 287 |
\& |
| 288 |
size = stat.st_size; |
| 289 |
\& |
| 290 |
fd_out = open(argv[2], O_CREAT | O_WRONLY | O_TRUNC, 0644); |
| 291 |
if (fd_out == \-1) { |
| 292 |
perror("open (argv[2])"); |
| 293 |
exit(EXIT_FAILURE); |
| 294 |
} |
| 295 |
\& |
| 296 |
do { |
| 297 |
ret = copy_file_range(fd_in, NULL, fd_out, NULL, size, 0); |
| 298 |
if (ret == \-1) { |
| 299 |
perror("copy_file_range"); |
| 300 |
exit(EXIT_FAILURE); |
| 301 |
} |
| 302 |
\& |
| 303 |
size \-= ret; |
| 304 |
} while (size > 0 && ret > 0); |
| 305 |
\& |
| 306 |
close(fd_in); |
| 307 |
close(fd_out); |
| 308 |
exit(EXIT_SUCCESS); |
| 309 |
} |
| 310 |
.EE |
| 311 |
.\" SRC END |
| 312 |
.SH SEE ALSO |
| 313 |
.BR lseek (2), |
| 314 |
.BR sendfile (2), |
| 315 |
.BR splice (2) |