1 .\" Copyright (c) 2016, Oracle. All rights reserved.
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
4 .TH IOCTL_FICLONERANGE 2 2021-03-22 "Linux man-pages (unreleased)"
6 ioctl_ficlonerange, ioctl_ficlone \-
7 share some the data of one file with another file
10 .RI ( libc ", " \-lc )
13 .BR "#include <linux/fs.h>" " /* Definition of " FICLONE* " constants */"
14 .B #include <sys/ioctl.h>
16 .BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg );
17 .BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd );
20 If a filesystem supports files sharing physical storage between multiple
21 files ("reflink"), this
23 operation can be used to make some of the data in the
27 file by sharing the underlying storage, which is faster than making a separate
28 physical copy of the data.
29 Both files must reside within the same filesystem.
30 If a file write should occur to a shared region,
31 the filesystem must ensure that the changes remain private to the file being
33 This behavior is commonly referred to as "copy on write".
35 This ioctl reflinks up to
37 bytes from file descriptor
45 provided that both are files.
48 is zero, the ioctl reflinks to the end of the source file.
49 This information is conveyed in a structure of
54 struct file_clone_range {
63 Clones are atomic with regards to concurrent writes, so no locks need to be
64 taken to obtain a consistent cloned copy.
68 ioctl clones entire files.
70 On error, \-1 is returned, and
72 is set to indicate the error.
74 Error codes can be one of, but are not limited to, the following:
78 is not open for reading;
80 is not open for writing or is open for append-only writes;
81 or the filesystem which
83 resides on does not support reflink.
86 The filesystem does not support reflinking the ranges of the given files.
87 This error can also appear if either file descriptor represents
88 a device, FIFO, or socket.
89 Disk filesystems generally require the offset and length arguments
90 to be aligned to the fundamental block size.
91 XFS and Btrfs do not support
92 overlapping reflink ranges in the same file.
95 One of the files is a directory and the filesystem does not support shared
96 regions in directories.
99 This can appear if the filesystem does not support reflinking either file
100 descriptor, or if either file descriptor refers to special inodes.
107 One of the files is a swap file.
108 Swap files cannot share storage.
111 .IR dest_fd " and " src_fd
112 are not on the same mounted filesystem.
114 These ioctl operations first appeared in Linux 4.5.
115 They were previously known as
118 .BR BTRFS_IOC_CLONE_RANGE ,
119 and were private to Btrfs.
121 This API is Linux-specific.
123 Because a copy-on-write operation requires the allocation of new storage, the
125 operation may unshare shared blocks to guarantee that subsequent writes will
126 not fail because of lack of disk space.