1 .\"This manpage is Copyright (C) 2015 Anna Schumaker <Anna.Schumaker@Netapp.com>
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of
9 .\" this manual under the conditions for verbatim copying, provided that
10 .\" the entire resulting derived work is distributed under the terms of
11 .\" a permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume
15 .\" no responsibility for errors or omissions, or for damages resulting
16 .\" from the use of the information contained herein. The author(s) may
17 .\" not have taken the same level of care in the production of this
18 .\" manual, which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
25 .TH COPY_FILE_RANGE 2 2021-03-22 "Linux" "Linux Programmer's Manual"
27 copy_file_range \- Copy a range of data from one file to another
30 .B #define _GNU_SOURCE
31 .B #include <unistd.h>
33 .BI "ssize_t copy_file_range(int " fd_in ", off64_t *" off_in ,
34 .BI " int " fd_out ", off64_t *" off_out ,
35 .BI " size_t " len ", unsigned int " flags );
39 .BR copy_file_range ()
40 system call performs an in-kernel copy between two file descriptors
41 without the additional cost of transferring data from the kernel to user space
42 and then back into the kernel.
45 bytes of data from the source file descriptor
47 to the target file descriptor
49 overwriting any data that exists within the requested range of the target file.
51 The following semantics apply for
53 and similar statements apply to
58 is NULL, then bytes are read from
60 starting from the file offset, and the file offset is
61 adjusted by the number of bytes copied.
67 must point to a buffer that specifies the starting
68 offset where bytes from
75 is adjusted appropriately.
80 can refer to the same file.
81 If they refer to the same file, then the source and target ranges are not
86 argument is provided to allow for future extensions
87 and currently must be set to 0.
89 Upon successful completion,
90 .BR copy_file_range ()
91 will return the number of bytes copied between files.
92 This could be less than the length originally requested.
95 is at or past the end of file, no bytes are copied, and
96 .BR copy_file_range ()
100 .BR copy_file_range ()
103 is set to indicate the error.
107 One or more file descriptors are not valid.
111 is not open for reading; or
113 is not open for writing.
118 flag is set for the open file description (see
120 referred to by the file descriptor
124 An attempt was made to write at a position past the maximum file offset the
128 An attempt was made to write a range that exceeds the allowed maximum file size.
129 The maximum file size differs between filesystem implementations and can be
130 different from the maximum allowed file offset.
133 An attempt was made to write beyond the process's file size resource limit.
134 This may also result in the process receiving a
147 refer to the same file and the source and target ranges overlap.
154 is not a regular file.
157 A low-level I/O error occurred while copying.
164 refers to a directory.
170 There is not enough space on the target filesystem to complete the copy.
173 The requested source or destination range is too large to represent in the
174 specified data types.
178 refers to an immutable file.
185 refers to an active swap file.
188 The files referred to by
189 .IR fd_in " and " fd_out
190 are not on the same mounted filesystem (pre Linux 5.3).
193 .BR copy_file_range ()
194 system call first appeared in Linux 4.5, but glibc 2.27 provides a user-space
195 emulation when it is not available.
196 .\" https://sourceware.org/git/?p=glibc.git;a=commit;f=posix/unistd.h;h=bad7a0c81f501fbbcc79af9eaa4b8254441c4a1f
198 A major rework of the kernel implementation occurred in 5.3.
199 Areas of the API that weren't clearly defined were clarified and the API bounds
200 are much more strictly checked than on earlier kernels.
201 Applications should target the behaviour and requirements of 5.3 kernels.
203 First support for cross-filesystem copies was introduced in Linux 5.3.
204 Older kernels will return -EXDEV when cross-filesystem copies are attempted.
207 .BR copy_file_range ()
208 system call is a nonstandard Linux and GNU extension.
212 is a sparse file, then
213 .BR copy_file_range ()
214 may expand any holes existing in the requested range.
215 Users may benefit from calling
216 .BR copy_file_range ()
217 in a loop, and using the
222 operations to find the locations of data segments.
224 .BR copy_file_range ()
225 gives filesystems an opportunity to implement "copy acceleration" techniques,
226 such as the use of reflinks (i.e., two or more inodes that share
227 pointers to the same copy-on-write disk blocks)
228 or server-side-copy (in the case of NFS).
235 #include <sys/stat.h>
239 main(int argc, char *argv[])
246 fprintf(stderr, "Usage: %s <source> <destination>\en", argv[0]);
250 fd_in = open(argv[1], O_RDONLY);
252 perror("open (argv[1])");
256 if (fstat(fd_in, &stat) == \-1) {
263 fd_out = open(argv[2], O_CREAT | O_WRONLY | O_TRUNC, 0644);
265 perror("open (argv[2])");
270 ret = copy_file_range(fd_in, NULL, fd_out, NULL, len, 0);
272 perror("copy_file_range");
277 } while (len > 0 && ret > 0);