| .\" Copyright (c) 2016, Oracle. All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" |
| .\" The GNU General Public License's references to "object code" |
| .\" and "executables" are to be interpreted as the output of any |
| .\" document formatting or typesetting system, including |
| .\" intermediate and printed output. |
| .\" |
| .\" This manual is distributed in the hope that it will be useful, |
| .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| .\" GNU General Public License for more details. |
| .\" |
| .\" You should have received a copy of the GNU General Public |
| .\" License along with this manual; if not, see |
| .\" <http://www.gnu.org/licenses/>. |
| .\" %%%LICENSE_END |
| .TH IOCTL_FICLONERANGE 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| ioctl_ficlonerange, ioctl_ficlone \- share some the data of one file with another file |
| .SH SYNOPSIS |
| .nf |
| .BR "#include <linux/fs.h>" " /* Definition of " FICLONE* " constants */" |
| .B #include <sys/ioctl.h> |
| .PP |
| .BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg ); |
| .BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd ); |
| .fi |
| .SH DESCRIPTION |
| If a filesystem supports files sharing physical storage between multiple |
| files ("reflink"), this |
| .BR ioctl (2) |
| operation can be used to make some of the data in the |
| .I src_fd |
| file appear in the |
| .I dest_fd |
| file by sharing the underlying storage, which is faster than making a separate |
| physical copy of the data. |
| Both files must reside within the same filesystem. |
| If a file write should occur to a shared region, |
| the filesystem must ensure that the changes remain private to the file being |
| written. |
| This behavior is commonly referred to as "copy on write". |
| .PP |
| This ioctl reflinks up to |
| .IR src_length |
| bytes from file descriptor |
| .IR src_fd |
| at offset |
| .IR src_offset |
| into the file |
| .IR dest_fd |
| at offset |
| .IR dest_offset , |
| provided that both are files. |
| If |
| .IR src_length |
| is zero, the ioctl reflinks to the end of the source file. |
| This information is conveyed in a structure of |
| the following form: |
| .PP |
| .in +4n |
| .EX |
| struct file_clone_range { |
| __s64 src_fd; |
| __u64 src_offset; |
| __u64 src_length; |
| __u64 dest_offset; |
| }; |
| .EE |
| .in |
| .PP |
| Clones are atomic with regards to concurrent writes, so no locks need to be |
| taken to obtain a consistent cloned copy. |
| .PP |
| The |
| .B FICLONE |
| ioctl clones entire files. |
| .SH RETURN VALUE |
| On error, \-1 is returned, and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| Error codes can be one of, but are not limited to, the following: |
| .TP |
| .B EBADF |
| .IR src_fd |
| is not open for reading; |
| .IR dest_fd |
| is not open for writing or is open for append-only writes; |
| or the filesystem which |
| .IR src_fd |
| resides on does not support reflink. |
| .TP |
| .B EINVAL |
| The filesystem does not support reflinking the ranges of the given files. |
| This error can also appear if either file descriptor represents |
| a device, FIFO, or socket. |
| Disk filesystems generally require the offset and length arguments |
| to be aligned to the fundamental block size. |
| XFS and Btrfs do not support |
| overlapping reflink ranges in the same file. |
| .TP |
| .B EISDIR |
| One of the files is a directory and the filesystem does not support shared |
| regions in directories. |
| .TP |
| .B EOPNOTSUPP |
| This can appear if the filesystem does not support reflinking either file |
| descriptor, or if either file descriptor refers to special inodes. |
| .TP |
| .B EPERM |
| .IR dest_fd |
| is immutable. |
| .TP |
| .B ETXTBSY |
| One of the files is a swap file. |
| Swap files cannot share storage. |
| .TP |
| .B EXDEV |
| .IR dest_fd " and " src_fd |
| are not on the same mounted filesystem. |
| .SH VERSIONS |
| These ioctl operations first appeared in Linux 4.5. |
| They were previously known as |
| .B BTRFS_IOC_CLONE |
| and |
| .BR BTRFS_IOC_CLONE_RANGE , |
| and were private to Btrfs. |
| .SH CONFORMING TO |
| This API is Linux-specific. |
| .SH NOTES |
| Because a copy-on-write operation requires the allocation of new storage, the |
| .BR fallocate (2) |
| operation may unshare shared blocks to guarantee that subsequent writes will |
| not fail because of lack of disk space. |
| .SH SEE ALSO |
| .BR ioctl (2) |