-.\" Copyright (C) 2016 Oracle. All rights reserved.
+.\" Copyright (c) 2016, Oracle. All rights reserved.
.\"
-.\" %%%LICENSE_START(VERBATIM)
-.\" This program is free software; you can redistribute it and/or
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
-.\" published by the Free Software Foundation.
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
.\"
-.\" This program is distributed in the hope that it would be useful,
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will 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
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
.\" %%%LICENSE_END
-.TH IOCTL-FICLONERANGE 2 2016-02-10 "Linux" "Linux Programmer's Manual"
+.TH IOCTL_FICLONERANGE 2 2017-09-15 "Linux" "Linux Programmer's Manual"
.SH NAME
ioctl_ficlonerange, ioctl_ficlone \- share some the data of one file with another file
.SH SYNOPSIS
.B #include <sys/ioctl.h>
.br
.B #include <linux/fs.h>
-.sp
-.BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range * " arg );
+.PP
+.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
.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
.IR src_length
bytes from file descriptor
at offset
.IR dest_offset ",
provided that both are files.
+If
+.IR 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
-.nf
-
+.EX
struct file_clone_range {
__s64 src_fd;
__u64 src_offset;
__u64 src_length;
__u64 dest_offset;
};
-
-.fi
+.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 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.
+.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 EINVAL
The filesystem does not support reflinking the ranges of the given files.
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.
+.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
.IR dest_fd
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.
+.B EXDEV
+.IR dest_fd " and " src_fd
+are not on the same mounted filesystem.
+.SH VERSIONS
+These ioctl operations first appeared in Linux 4.5.
+They were previously known as
+.B BTRFS_IOC_CLONE
+and
+.BR BTRFS_IOC_CLONE_RANGE ,
+and were private to Btrfs.
.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 NOTES
Because a copy-on-write operation requires the allocation of new storage, the
.BR fallocate (2)
projects / thirdparty / man-pages.git / blobdiff