On 03/15/2016 05:48 PM, Darrick J. Wong wrote:
> Document the FICLONE and FICLONERANGE ioctls, formerly known as the
> BTRFS_IOC_CLONE and BTRFS_IOC_CLONE_RANGE ioctls.
Thanks for the nice page, Darrick. Applied!
Cheers,
Michael
> Signed-off-by: Darrick J. Wong <darrick.wong@xxxxxxxxxx>
> ---
> man2/ioctl_ficlone.2 | 1
> man2/ioctl_ficlonerange.2 | 124 +++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 125 insertions(+)
> create mode 100644 man2/ioctl_ficlone.2
> create mode 100644 man2/ioctl_ficlonerange.2
>
>
> diff --git a/man2/ioctl_ficlone.2 b/man2/ioctl_ficlone.2
> new file mode 100644
> index 0000000..19bb348
> --- /dev/null
> +++ b/man2/ioctl_ficlone.2
> @@ -0,0 +1 @@
> +.so man2/ioctl_ficlonerange.2
> diff --git a/man2/ioctl_ficlonerange.2 b/man2/ioctl_ficlonerange.2
> new file mode 100644
> index 0000000..c5c72aa
> --- /dev/null
> +++ b/man2/ioctl_ficlonerange.2
> @@ -0,0 +1,124 @@
> +.\" Copyright (C) 2016 Oracle. All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" This program is free software; you can redistribute it and/or
> +.\" modify it under the terms of the GNU General Public License as
> +.\" published by the Free Software Foundation.
> +.\"
> +.\" This program is distributed in the hope that it would be useful,
> +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
> +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> +.\" GNU General Public License for more details.
> +.\"
> +.\" You should have received a copy of the GNU General Public License
> +.\" along with this program; if not, write the Free Software Foundation,
> +.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
> +.\" %%%LICENSE_END
> +.TH IOCTL-FICLONERANGE 2 2016-02-10 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +ioctl_ficlonerange, ioctl_ficlone \- share some the data of one file with another file
> +.SH SYNOPSIS
> +.br
> +.B #include <sys/ioctl.h>
> +.br
> +.B #include <linux/fs.h>
> +.sp
> +.BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range * " arg );
> +.br
> +.BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd );
> +.SH DESCRIPTION
> +If a filesystem supports files sharing physical storage between multiple
> +files ("reflink"), this
> +.BR ioctl (2)
> +system call can be used to make some of the data in the
> +.B src_fd
> +file appear in the
> +.B dest_fd
> +file by sharing the underlying storage, which is faster than making a separate
> +physical copy of the data. 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".
> +
> +This ioctl reflinks up to
> +.IR src_length
> +bytes from file descriptor
> +.IR src_fd
> +at offset
> +.IR src_offset
> +into the file
> +.IR dest_fd
> +at offset
> +.IR dest_offset ",
> +provided that both are files. This information is conveyed in a structure of
> +the following form:
> +.in +4n
> +.nf
> +
> +struct file_clone_range {
> + __s64 src_fd;
> + __u64 src_offset;
> + __u64 src_length;
> + __u64 dest_offset;
> +};
> +
> +.fi
> +.in
> +Clones are atomic with regards to concurrent writes, so no locks need to be
> +taken to obtain a consistent cloned copy.
> +
> +The FICLONE ioctl clones entire files.
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EXDEV
> +.IR dest_fd " and " src_fd
> +are not on the same mounted filesystem.
> +.TP
> +.B EISDIR
> +One of the files is a directory and the filesystem does not support shared
> +regions in directories.
> +.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 EBADF
> +.IR src_fd
> +is not open for reading;
> +.IR dest_fd
> +is not open for writing or is open for append-only writes; or the filesystem
> +which
> +.IR src_fd
> +resides on does not support reflink.
> +.TP
> +.B EPERM
> +.IR dest_fd
> +is immutable.
> +.TP
> +.B ETXTBSY
> +One of the files is a swap file. Swap files cannot share storage.
> +.TP
> +.B EOPNOTSUPP
> +This can appear if the filesystem does not support reflinking either file
> +descriptor.
> +.SH NOTES
> +Because a copy on write operation requires the allocation of new storage, the
> +.B fallocate (2)
> +operation may un-share shared blocks to guarantee that subsequent writes will
> +not fail because of lack of disk space.
> +.SH CONFORMING TO
> +This API is Linux-specific. This ioctl was previously known as
> +.B BTRFS_IOC_CLONE_RANGE
> +and was private to btrfs.
> +.fi
> +.in
> +.SH SEE ALSO
> +.BR ioctl (2)
>
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-api" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
