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