man2/ioctl_ficlonerange.2

   1 .\" Copyright (c) 2016, Oracle.  All rights reserved.
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   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,
  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 .\"
  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/>.
  22 .\" %%%LICENSE_END
  23 .TH IOCTL-FICLONERANGE 2 2017-09-15 "Linux" "Linux Programmer's Manual"
  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>
  31 .PP
  32 .BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg );
  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)
  39 operation can be used to make some of the data in the
  40 .I src_fd
  41 file appear in the
  42 .I dest_fd
  43 file by sharing the underlying storage, which is faster than making a separate
  44 physical copy of the data.
  45 Both files must reside within the same filesystem.
  46 If a file write should occur to a shared region,
  47 the filesystem must ensure that the changes remain private to the file being
  48 written.
  49 This behavior is commonly referred to as "copy on write".
  50 .PP
  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 ",
  61 provided that both are files.
  62 If
  63 .IR src_length
  64 is zero, the ioctl reflinks to the end of the source file.
  65 This information is conveyed in a structure of
  66 the following form:
  67 .PP
  68 .in +4n
  69 .EX
  70 struct file_clone_range {
  71     __s64 src_fd;
  72     __u64 src_offset;
  73     __u64 src_length;
  74     __u64 dest_offset;
  75 };
  76 .EE
  77 .in
  78 .PP
  79 Clones are atomic with regards to concurrent writes, so no locks need to be
  80 taken to obtain a consistent cloned copy.
  81 .PP
  82 The
  83 .B FICLONE
  84 ioctl clones entire files.
  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
  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.
 101 .TP
 102 .B EINVAL
 103 The filesystem does not support reflinking the ranges of the given files.
 104 This error can also appear if either file descriptor represents
 105 a device, FIFO, or socket.
 106 Disk filesystems generally require the offset and length arguments
 107 to be aligned to the fundamental block size.
 108 XFS and Btrfs do not support
 109 overlapping reflink ranges in the same file.
 110 .TP
 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
 117 descriptor, or if either file descriptor refers to special inodes.
 118 .TP
 119 .B EPERM
 120 .IR dest_fd
 121 is immutable.
 122 .TP
 123 .B ETXTBSY
 124 One of the files is a swap file.
 125 Swap files cannot share storage.
 126 .TP
 127 .B EXDEV
 128 .IR dest_fd " and " src_fd
 129 are not on the same mounted filesystem.
 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.
 137 .SH CONFORMING TO
 138 This API is Linux-specific.
 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.
 144 .SH SEE ALSO
 145 .BR ioctl (2)