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