]>
Commit | Line | Data |
---|---|---|
8c93a5df | 1 | .\" Copyright (c) 2016, Oracle. All rights reserved. |
9eb18e17 | 2 | .\" |
8c93a5df DW |
3 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
4 | .\" This is free documentation; you can redistribute it and/or | |
9eb18e17 | 5 | .\" modify it under the terms of the GNU General Public License as |
8c93a5df DW |
6 | .\" published by the Free Software Foundation; either version 2 of |
7 | .\" the License, or (at your option) any later version. | |
9eb18e17 | 8 | .\" |
8c93a5df DW |
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. | |
13 | .\" | |
14 | .\" This manual is distributed in the hope that it will be useful, | |
9eb18e17 DW |
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. | |
18 | .\" | |
8c93a5df DW |
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/>. | |
9eb18e17 | 22 | .\" %%%LICENSE_END |
0f1e53ec | 23 | .TH IOCTL_FICLONERANGE 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
9eb18e17 DW |
24 | .SH NAME |
25 | ioctl_ficlonerange, ioctl_ficlone \- share some the data of one file with another file | |
26 | .SH SYNOPSIS | |
27 | .br | |
28 | .B #include <sys/ioctl.h> | |
29 | .br | |
30 | .B #include <linux/fs.h> | |
68e4db0a | 31 | .PP |
70bdb9b5 | 32 | .BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg ); |
9eb18e17 DW |
33 | .br |
34 | .BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd ); | |
35 | .SH DESCRIPTION | |
36 | If a filesystem supports files sharing physical storage between multiple | |
37 | files ("reflink"), this | |
38 | .BR ioctl (2) | |
603fc95a MK |
39 | operation can be used to make some of the data in the |
40 | .I src_fd | |
9eb18e17 | 41 | file appear in the |
603fc95a | 42 | .I dest_fd |
9eb18e17 | 43 | file by sharing the underlying storage, which is faster than making a separate |
1d691add | 44 | physical copy of the data. |
8592ec74 | 45 | Both files must reside within the same filesystem. |
1d691add | 46 | If a file write should occur to a shared region, |
9eb18e17 | 47 | the filesystem must ensure that the changes remain private to the file being |
1d691add MK |
48 | written. |
49 | This behavior is commonly referred to as "copy on write". | |
efeece04 | 50 | .PP |
9eb18e17 DW |
51 | This ioctl reflinks up to |
52 | .IR src_length | |
53 | bytes from file descriptor | |
54 | .IR src_fd | |
55 | at offset | |
56 | .IR src_offset | |
57 | into the file | |
58 | .IR dest_fd | |
59 | at offset | |
60 | .IR dest_offset ", | |
1d691add | 61 | provided that both are files. |
e4fcb7bc DW |
62 | If |
63 | .IR src_length | |
64 | is zero, the ioctl reflinks to the end of the source file. | |
1d691add | 65 | This information is conveyed in a structure of |
9eb18e17 | 66 | the following form: |
b76974c1 | 67 | .PP |
9eb18e17 | 68 | .in +4n |
b76974c1 | 69 | .EX |
9eb18e17 | 70 | struct file_clone_range { |
603fc95a MK |
71 | __s64 src_fd; |
72 | __u64 src_offset; | |
73 | __u64 src_length; | |
74 | __u64 dest_offset; | |
9eb18e17 | 75 | }; |
b9c93deb | 76 | .EE |
9eb18e17 | 77 | .in |
b76974c1 | 78 | .PP |
9eb18e17 DW |
79 | Clones are atomic with regards to concurrent writes, so no locks need to be |
80 | taken to obtain a consistent cloned copy. | |
efeece04 | 81 | .PP |
603fc95a MK |
82 | The |
83 | .B FICLONE | |
84 | ioctl clones entire files. | |
9eb18e17 DW |
85 | .SH RETURN VALUE |
86 | On error, \-1 is returned, and | |
87 | .I errno | |
88 | is set to indicate the error. | |
89 | .PP | |
90 | .SH ERRORS | |
91 | Error codes can be one of, but are not limited to, the following: | |
92 | .TP | |
b2d34da5 MK |
93 | .B EBADF |
94 | .IR src_fd | |
95 | is not open for reading; | |
96 | .IR dest_fd | |
97 | is not open for writing or is open for append-only writes; | |
98 | or the filesystem which | |
99 | .IR src_fd | |
100 | resides on does not support reflink. | |
9eb18e17 DW |
101 | .TP |
102 | .B EINVAL | |
1d691add MK |
103 | The filesystem does not support reflinking the ranges of the given files. |
104 | This error can also appear if either file descriptor represents | |
603fc95a | 105 | a device, FIFO, or socket. |
1d691add MK |
106 | Disk filesystems generally require the offset and length arguments |
107 | to be aligned to the fundamental block size. | |
603fc95a | 108 | XFS and Btrfs do not support |
9eb18e17 DW |
109 | overlapping reflink ranges in the same file. |
110 | .TP | |
b2d34da5 MK |
111 | .B EISDIR |
112 | One of the files is a directory and the filesystem does not support shared | |
113 | regions in directories. | |
114 | .TP | |
115 | .B EOPNOTSUPP | |
116 | This can appear if the filesystem does not support reflinking either file | |
2046b8ac | 117 | descriptor, or if either file descriptor refers to special inodes. |
9eb18e17 DW |
118 | .TP |
119 | .B EPERM | |
120 | .IR dest_fd | |
121 | is immutable. | |
122 | .TP | |
123 | .B ETXTBSY | |
1d691add MK |
124 | One of the files is a swap file. |
125 | Swap files cannot share storage. | |
9eb18e17 | 126 | .TP |
b2d34da5 MK |
127 | .B EXDEV |
128 | .IR dest_fd " and " src_fd | |
129 | are not on the same mounted filesystem. | |
c4f9c619 MK |
130 | .SH VERSIONS |
131 | These ioctl operations first appeared in Linux 4.5. | |
132 | They were previously known as | |
133 | .B BTRFS_IOC_CLONE | |
134 | and | |
135 | .BR BTRFS_IOC_CLONE_RANGE , | |
136 | and were private to Btrfs. | |
9eb18e17 | 137 | .SH CONFORMING TO |
1d691add | 138 | This API is Linux-specific. |
603fc95a MK |
139 | .SH NOTES |
140 | Because a copy-on-write operation requires the allocation of new storage, the | |
141 | .BR fallocate (2) | |
142 | operation may unshare shared blocks to guarantee that subsequent writes will | |
143 | not fail because of lack of disk space. | |
9eb18e17 DW |
144 | .SH SEE ALSO |
145 | .BR ioctl (2) |