| 1 |
.\" Copyright 2016, Oracle |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: GPL-2.0-or-later |
| 5 |
.\" |
| 6 |
.TH FICLONE 2const 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
FICLONE, |
| 9 |
FICLONERANGE |
| 10 |
\- |
| 11 |
share some the data of one file with another file |
| 12 |
.SH LIBRARY |
| 13 |
Standard C library |
| 14 |
.RI ( libc ,\~ \-lc ) |
| 15 |
.SH SYNOPSIS |
| 16 |
.nf |
| 17 |
.BR "#include <linux/fs.h>" " /* Definition of " FICLONE* " constants */" |
| 18 |
.B #include <sys/ioctl.h> |
| 19 |
.P |
| 20 |
.BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg ); |
| 21 |
.BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd ); |
| 22 |
.fi |
| 23 |
.SH DESCRIPTION |
| 24 |
If a filesystem supports files sharing physical storage between multiple |
| 25 |
files ("reflink"), this |
| 26 |
.BR ioctl (2) |
| 27 |
operation can be used to make some of the data in the |
| 28 |
.I src_fd |
| 29 |
file appear in the |
| 30 |
.I dest_fd |
| 31 |
file by sharing the underlying storage, which is faster than making a separate |
| 32 |
physical copy of the data. |
| 33 |
Both files must reside within the same filesystem. |
| 34 |
If a file write should occur to a shared region, |
| 35 |
the filesystem must ensure that the changes remain private to the file being |
| 36 |
written. |
| 37 |
This behavior is commonly referred to as "copy on write". |
| 38 |
.P |
| 39 |
This ioctl reflinks up to |
| 40 |
.I src_length |
| 41 |
bytes from file descriptor |
| 42 |
.I src_fd |
| 43 |
at offset |
| 44 |
.I src_offset |
| 45 |
into the file |
| 46 |
.I dest_fd |
| 47 |
at offset |
| 48 |
.IR dest_offset , |
| 49 |
provided that both are files. |
| 50 |
If |
| 51 |
.I src_length |
| 52 |
is zero, the ioctl reflinks to the end of the source file. |
| 53 |
This information is conveyed in a structure of |
| 54 |
the following form: |
| 55 |
.P |
| 56 |
.in +4n |
| 57 |
.EX |
| 58 |
struct file_clone_range { |
| 59 |
__s64 src_fd; |
| 60 |
__u64 src_offset; |
| 61 |
__u64 src_length; |
| 62 |
__u64 dest_offset; |
| 63 |
}; |
| 64 |
.EE |
| 65 |
.in |
| 66 |
.P |
| 67 |
Clones are atomic with regards to concurrent writes, so no locks need to be |
| 68 |
taken to obtain a consistent cloned copy. |
| 69 |
.P |
| 70 |
The |
| 71 |
.B FICLONE |
| 72 |
ioctl clones entire files. |
| 73 |
.SH RETURN VALUE |
| 74 |
On error, \-1 is returned, and |
| 75 |
.I errno |
| 76 |
is set to indicate the error. |
| 77 |
.SH ERRORS |
| 78 |
Error codes can be one of, but are not limited to, the following: |
| 79 |
.TP |
| 80 |
.B EBADF |
| 81 |
.I src_fd |
| 82 |
is not open for reading; |
| 83 |
.I dest_fd |
| 84 |
is not open for writing or is open for append-only writes; |
| 85 |
or the filesystem which |
| 86 |
.I src_fd |
| 87 |
resides on does not support reflink. |
| 88 |
.TP |
| 89 |
.B EINVAL |
| 90 |
The filesystem does not support reflinking the ranges of the given files. |
| 91 |
This error can also appear if either file descriptor represents |
| 92 |
a device, FIFO, or socket. |
| 93 |
Disk filesystems generally require the offset and length arguments |
| 94 |
to be aligned to the fundamental block size. |
| 95 |
XFS and Btrfs do not support |
| 96 |
overlapping reflink ranges in the same file. |
| 97 |
.TP |
| 98 |
.B EISDIR |
| 99 |
One of the files is a directory and the filesystem does not support shared |
| 100 |
regions in directories. |
| 101 |
.TP |
| 102 |
.B EOPNOTSUPP |
| 103 |
This can appear if the filesystem does not support reflinking either file |
| 104 |
descriptor, or if either file descriptor refers to special inodes. |
| 105 |
.TP |
| 106 |
.B EPERM |
| 107 |
.I dest_fd |
| 108 |
is immutable. |
| 109 |
.TP |
| 110 |
.B ETXTBSY |
| 111 |
One of the files is a swap file. |
| 112 |
Swap files cannot share storage. |
| 113 |
.TP |
| 114 |
.B EXDEV |
| 115 |
.IR dest_fd " and " src_fd |
| 116 |
are not on the same mounted filesystem. |
| 117 |
.SH STANDARDS |
| 118 |
Linux. |
| 119 |
.SH HISTORY |
| 120 |
Linux 4.5. |
| 121 |
.P |
| 122 |
They were previously known as |
| 123 |
.B BTRFS_IOC_CLONE |
| 124 |
and |
| 125 |
.BR BTRFS_IOC_CLONE_RANGE , |
| 126 |
and were private to Btrfs. |
| 127 |
.SH CAVEATS |
| 128 |
Because a copy-on-write operation requires the allocation of new storage, the |
| 129 |
.BR fallocate (2) |
| 130 |
operation may unshare shared blocks to guarantee that subsequent writes will |
| 131 |
not fail because of lack of disk space. |
| 132 |
.SH SEE ALSO |
| 133 |
.BR ioctl (2) |