Debian Codegraph @

upstream/debian-unstable/man2/copy_file_range.2

raw
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)