man2/ioctl_ficlonerange.2

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