1 .\" Copyright (c) 2016, Oracle. All rights reserved.
3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
4 .\" This is free documentation; you can redistribute it and/or
5 .\" modify it under the terms of the GNU General Public License as
6 .\" published by the Free Software Foundation; either version 2 of
7 .\" the License, or (at your option) any later version.
9 .\" The GNU General Public License's references to "object code"
10 .\" and "executables" are to be interpreted as the output of any
11 .\" document formatting or typesetting system, including
12 .\" intermediate and printed output.
14 .\" This manual is distributed in the hope that it will be useful,
15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 .\" GNU General Public License for more details.
19 .\" You should have received a copy of the GNU General Public
20 .\" License along with this manual; if not, see
21 .\" <http://www.gnu.org/licenses/>.
23 .TH IOCTL-FICLONERANGE 2 2016-12-12 "Linux" "Linux Programmer's Manual"
25 ioctl_ficlonerange, ioctl_ficlone \- share some the data of one file with another file
28 .B #include <sys/ioctl.h>
30 .B #include <linux/fs.h>
32 .BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg );
34 .BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd );
36 If a filesystem supports files sharing physical storage between multiple
37 files ("reflink"), this
39 operation can be used to make some of the data in the
43 file by sharing the underlying storage, which is faster than making a separate
44 physical copy of the data.
45 Both files must reside within the same filesystem.
46 If a file write should occur to a shared region,
47 the filesystem must ensure that the changes remain private to the file being
49 This behavior is commonly referred to as "copy on write".
51 This ioctl reflinks up to
53 bytes from file descriptor
61 provided that both are files.
64 is zero, the ioctl reflinks to the end of the source file.
65 This information is conveyed in a structure of
70 struct file_clone_range {
79 Clones are atomic with regards to concurrent writes, so no locks need to be
80 taken to obtain a consistent cloned copy.
84 ioctl clones entire files.
86 On error, \-1 is returned, and
88 is set to indicate the error.
91 Error codes can be one of, but are not limited to, the following:
95 is not open for reading;
97 is not open for writing or is open for append-only writes;
98 or the filesystem which
100 resides on does not support reflink.
103 The filesystem does not support reflinking the ranges of the given files.
104 This error can also appear if either file descriptor represents
105 a device, FIFO, or socket.
106 Disk filesystems generally require the offset and length arguments
107 to be aligned to the fundamental block size.
108 XFS and Btrfs do not support
109 overlapping reflink ranges in the same file.
112 One of the files is a directory and the filesystem does not support shared
113 regions in directories.
116 This can appear if the filesystem does not support reflinking either file
117 descriptor, or if either file descriptor refers to special inodes.
124 One of the files is a swap file.
125 Swap files cannot share storage.
128 .IR dest_fd " and " src_fd
129 are not on the same mounted filesystem.
131 These ioctl operations first appeared in Linux 4.5.
132 They were previously known as
135 .BR BTRFS_IOC_CLONE_RANGE ,
136 and were private to Btrfs.
138 This API is Linux-specific.
140 Because a copy-on-write operation requires the allocation of new storage, the
142 operation may unshare shared blocks to guarantee that subsequent writes will
143 not fail because of lack of disk space.