copy_file_range(2)

1copy_file_range(2)            System Calls Manual           copy_file_range(2)
2
3
4

NAME

6       copy_file_range - Copy a range of data from one file to another
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #define _GNU_SOURCE
13       #include <unistd.h>
14
15       ssize_t copy_file_range(int fd_in, off64_t *_Nullable off_in,
16                               int fd_out, off64_t *_Nullable off_out,
17                               size_t len, unsigned int flags);
18

DESCRIPTION

20       The  copy_file_range()  system  call performs an in-kernel copy between
21       two file descriptors without the additional cost of  transferring  data
22       from the kernel to user space and then back into the kernel.  It copies
23       up to len bytes of data from the source file descriptor  fd_in  to  the
24       target  file descriptor fd_out, overwriting any data that exists within
25       the requested range of the target file.
26
27       The following semantics apply for off_in, and similar statements  apply
28       to off_out:
29
30       •  If  off_in is NULL, then bytes are read from fd_in starting from the
31          file offset, and the file offset is adjusted by the number of  bytes
32          copied.
33
34       •  If off_in is not NULL, then off_in must point to a buffer that spec‐
35          ifies the starting offset where bytes from fd_in will be read.   The
36          file  offset  of fd_in is not changed, but off_in is adjusted appro‐
37          priately.
38
39       fd_in and fd_out can refer to the same file.  If they refer to the same
40       file, then the source and target ranges are not allowed to overlap.
41
42       The  flags argument is provided to allow for future extensions and cur‐
43       rently must be set to 0.
44

RETURN VALUE

46       Upon successful completion, copy_file_range() will return the number of
47       bytes  copied between files.  This could be less than the length origi‐
48       nally requested.  If the file offset of fd_in is at or past the end  of
49       file, no bytes are copied, and copy_file_range() returns zero.
50
51       On error, copy_file_range() returns -1 and errno is set to indicate the
52       error.
53

ERRORS

55       EBADF  One or more file descriptors are not valid.
56
57       EBADF  fd_in is not open for reading; or fd_out is not open  for  writ‐
58              ing.
59
60       EBADF  The  O_APPEND  flag  is  set  for the open file description (see
61              open(2)) referred to by the file descriptor fd_out.
62
63       EFBIG  An attempt was made to write at a position past the maximum file
64              offset the kernel supports.
65
66       EFBIG  An  attempt  was  made to write a range that exceeds the allowed
67              maximum file  size.   The  maximum  file  size  differs  between
68              filesystem implementations and can be different from the maximum
69              allowed file offset.
70
71       EFBIG  An attempt was made to write beyond the process's file size  re‐
72              source  limit.   This may also result in the process receiving a
73              SIGXFSZ signal.
74
75       EINVAL The flags argument is not 0.
76
77       EINVAL fd_in and fd_out refer to the same file and the source and  tar‐
78              get ranges overlap.
79
80       EINVAL Either fd_in or fd_out is not a regular file.
81
82       EIO    A low-level I/O error occurred while copying.
83
84       EISDIR Either fd_in or fd_out refers to a directory.
85
86       ENOMEM Out of memory.
87
88       ENOSPC There  is  not enough space on the target filesystem to complete
89              the copy.
90
91       EOPNOTSUPP (since Linux 5.19)
92              The filesystem does not support this operation.
93
94       EOVERFLOW
95              The requested source or destination range is too large to repre‐
96              sent in the specified data types.
97
98       EPERM  fd_out refers to an immutable file.
99
100       ETXTBSY
101              Either fd_in or fd_out refers to an active swap file.
102
103       EXDEV (before Linux 5.3)
104              The  files  referred  to by fd_in and fd_out are not on the same
105              filesystem.
106
107       EXDEV (since Linux 5.19)
108              The files referred to by fd_in and fd_out are not  on  the  same
109              filesystem, and the source and target filesystems are not of the
110              same type, or do not support cross-filesystem copy.
111

VERSIONS

113       A major rework of the kernel implementation occurred in Linux 5.3.  Ar‐
114       eas  of the API that weren't clearly defined were clarified and the API
115       bounds are much more strictly checked than on earlier kernels.
116
117       Since Linux 5.19, cross-filesystem copies can  be  achieved  when  both
118       filesystems  are  of the same type, and that filesystem implements sup‐
119       port for it.  See BUGS for behavior prior to Linux 5.19.
120
121       Applications should target the  behaviour  and  requirements  of  Linux
122       5.19, that was also backported to earlier stable kernels.
123

STANDARDS

125       Linux, GNU.
126

HISTORY

128       Linux  4.5,  but  glibc 2.27 provides a user-space emulation when it is
129       not available.
130

NOTES

132       If fd_in is a sparse file, then copy_file_range() may expand any  holes
133       existing  in  the  requested  range.   Users  may  benefit from calling
134       copy_file_range() in a loop,  and  using  the  lseek(2)  SEEK_DATA  and
135       SEEK_HOLE operations to find the locations of data segments.
136
137       copy_file_range()  gives  filesystems an opportunity to implement "copy
138       acceleration" techniques, such as the use of  reflinks  (i.e.,  two  or
139       more  inodes that share pointers to the same copy-on-write disk blocks)
140       or server-side-copy (in the case of NFS).
141

BUGS

143       In Linux 5.3 to Linux 5.18, cross-filesystem copies were implemented by
144       the  kernel,  if the operation was not supported by individual filesys‐
145       tems.  However, on some virtual filesystems, the call failed  to  copy,
146       while still reporting success.
147

EXAMPLES

149       #define _GNU_SOURCE
150       #include <fcntl.h>
151       #include <stdio.h>
152       #include <stdlib.h>
153       #include <sys/stat.h>
154       #include <unistd.h>
155
156       int
157       main(int argc, char *argv[])
158       {
159           int          fd_in, fd_out;
160           off64_t      len, ret;
161           struct stat  stat;
162
163           if (argc != 3) {
164               fprintf(stderr, "Usage: %s <source> <destination>\n", argv[0]);
165               exit(EXIT_FAILURE);
166           }
167
168           fd_in = open(argv[1], O_RDONLY);
169           if (fd_in == -1) {
170               perror("open (argv[1])");
171               exit(EXIT_FAILURE);
172           }
173
174           if (fstat(fd_in, &stat) == -1) {
175               perror("fstat");
176               exit(EXIT_FAILURE);
177           }
178
179           len = stat.st_size;
180
181           fd_out = open(argv[2], O_CREAT | O_WRONLY | O_TRUNC, 0644);
182           if (fd_out == -1) {
183               perror("open (argv[2])");
184               exit(EXIT_FAILURE);
185           }
186
187           do {
188               ret = copy_file_range(fd_in, NULL, fd_out, NULL, len, 0);
189               if (ret == -1) {
190                   perror("copy_file_range");
191                   exit(EXIT_FAILURE);
192               }
193
194               len -= ret;
195           } while (len > 0 && ret > 0);
196
197           close(fd_in);
198           close(fd_out);
199           exit(EXIT_SUCCESS);
200       }
201