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 LIBRARY
   8 Standard C library
   9 .RI ( libc ", " \-lc )
  10 .SH SYNOPSIS
  11 .nf
  12 .BR "#include <linux/fs.h>" "        /* Definition of " FICLONE* " constants */"
  13 .B #include <sys/ioctl.h>
  14 .PP
  15 .BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg );
  16 .BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd );
  17 .fi
  18 .SH DESCRIPTION
  19 If a filesystem supports files sharing physical storage between multiple
  20 files ("reflink"), this
  21 .BR ioctl (2)
  22 operation can be used to make some of the data in the
  23 .I src_fd
  24 file appear in the
  25 .I dest_fd
  26 file by sharing the underlying storage, which is faster than making a separate
  27 physical copy of the data.
  28 Both files must reside within the same filesystem.
  29 If a file write should occur to a shared region,
  30 the filesystem must ensure that the changes remain private to the file being
  31 written.
  32 This behavior is commonly referred to as "copy on write".
  33 .PP
  34 This ioctl reflinks up to
  35 .IR src_length
  36 bytes from file descriptor
  37 .IR src_fd
  38 at offset
  39 .IR src_offset
  40 into the file
  41 .IR dest_fd
  42 at offset
  43 .IR dest_offset ,
  44 provided that both are files.
  45 If
  46 .IR src_length
  47 is zero, the ioctl reflinks to the end of the source file.
  48 This information is conveyed in a structure of
  49 the following form:
  50 .PP
  51 .in +4n
  52 .EX
  53 struct file_clone_range {
  54     __s64 src_fd;
  55     __u64 src_offset;
  56     __u64 src_length;
  57     __u64 dest_offset;
  58 };
  59 .EE
  60 .in
  61 .PP
  62 Clones are atomic with regards to concurrent writes, so no locks need to be
  63 taken to obtain a consistent cloned copy.
  64 .PP
  65 The
  66 .B FICLONE
  67 ioctl clones entire files.
  68 .SH RETURN VALUE
  69 On error, \-1 is returned, and
  70 .I errno
  71 is set to indicate the error.
  72 .SH ERRORS
  73 Error codes can be one of, but are not limited to, the following:
  74 .TP
  75 .B EBADF
  76 .IR src_fd
  77 is not open for reading;
  78 .IR dest_fd
  79 is not open for writing or is open for append-only writes;
  80 or the filesystem which
  81 .IR src_fd
  82 resides on does not support reflink.
  83 .TP
  84 .B EINVAL
  85 The filesystem does not support reflinking the ranges of the given files.
  86 This error can also appear if either file descriptor represents
  87 a device, FIFO, or socket.
  88 Disk filesystems generally require the offset and length arguments
  89 to be aligned to the fundamental block size.
  90 XFS and Btrfs do not support
  91 overlapping reflink ranges in the same file.
  92 .TP
  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
  99 descriptor, or if either file descriptor refers to special inodes.
 100 .TP
 101 .B EPERM
 102 .IR dest_fd
 103 is immutable.
 104 .TP
 105 .B ETXTBSY
 106 One of the files is a swap file.
 107 Swap files cannot share storage.
 108 .TP
 109 .B EXDEV
 110 .IR dest_fd " and " src_fd
 111 are not on the same mounted filesystem.
 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.
 119 .SH CONFORMING TO
 120 This API is Linux-specific.
 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.
 126 .SH SEE ALSO
 127 .BR ioctl (2)