From 399644e47874bff147afb19c89228901ac39340e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:40:15 +0200 Subject: Adding upstream version 6.05.01. Signed-off-by: Daniel Baumann --- man2/ioctl_ficlonerange.2 | 129 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 man2/ioctl_ficlonerange.2 (limited to 'man2/ioctl_ficlonerange.2') diff --git a/man2/ioctl_ficlonerange.2 b/man2/ioctl_ficlonerange.2 new file mode 100644 index 0000000..68cfc67 --- /dev/null +++ b/man2/ioctl_ficlonerange.2 @@ -0,0 +1,129 @@ +.\" Copyright (c) 2016, Oracle. All rights reserved. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.TH ioctl_ficlonerange 2 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +ioctl_ficlonerange, ioctl_ficlone \- +share some the data of one file with another file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " FICLONE* " constants */" +.B #include +.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 +.I src_length +bytes from file descriptor +.I src_fd +at offset +.I src_offset +into the file +.I dest_fd +at offset +.IR dest_offset , +provided that both are files. +If +.I 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 +.I src_fd +is not open for reading; +.I dest_fd +is not open for writing or is open for append-only writes; +or the filesystem which +.I 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 +.I 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 STANDARDS +Linux. +.SH HISTORY +Linux 4.5. +.PP +They were previously known as +.B BTRFS_IOC_CLONE +and +.BR BTRFS_IOC_CLONE_RANGE , +and were private to Btrfs. +.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) -- cgit v1.2.3