2016-06-09 17:36:58 +00:00
|
|
|
.\" Copyright (c) 2016, Oracle. All rights reserved.
|
2016-03-15 16:48:10 +00:00
|
|
|
.\"
|
2016-06-09 17:36:58 +00:00
|
|
|
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
|
|
|
|
.\" This is free documentation; you can redistribute it and/or
|
2016-03-15 16:48:10 +00:00
|
|
|
.\" modify it under the terms of the GNU General Public License as
|
2016-06-09 17:36:58 +00:00
|
|
|
.\" published by the Free Software Foundation; either version 2 of
|
|
|
|
.\" the License, or (at your option) any later version.
|
2016-03-15 16:48:10 +00:00
|
|
|
.\"
|
2016-06-09 17:36:58 +00:00
|
|
|
.\" 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,
|
2016-03-15 16:48:10 +00:00
|
|
|
.\" 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.
|
|
|
|
.\"
|
2016-06-09 17:36:58 +00:00
|
|
|
.\" You should have received a copy of the GNU General Public
|
|
|
|
.\" License along with this manual; if not, see
|
|
|
|
.\" <http://www.gnu.org/licenses/>.
|
2016-03-15 16:48:10 +00:00
|
|
|
.\" %%%LICENSE_END
|
bind.2, chmod.2, chown.2, chroot.2, clock_getres.2, clone.2, connect.2, dup.2, fallocate.2, get_mempolicy.2, getpeername.2, getpriority.2, getsockname.2, getsockopt.2, gettimeofday.2, ioctl_ficlonerange.2, ioctl_fideduperange.2, kill.2, mbind.2, mmap.2, mount.2, mprotect.2, nfsservctl.2, nice.2, open.2, perf_event_open.2, pipe.2, pkey_alloc.2, prctl.2, ptrace.2, quotactl.2, remap_file_pages.2, sched_setscheduler.2, set_mempolicy.2, signal.2, signalfd.2, swapon.2, sync_file_range.2, syscalls.2, timer_create.2, timerfd_create.2, utime.2, utimensat.2, wait.2, atof.3, ctime.3, errno.3, fclose.3, fflush.3, insque.3, malloc_get_state.3, mallopt.3, mbsnrtowcs.3, mq_close.3, mq_open.3, mq_receive.3, mq_send.3, printf.3, pthread_attr_init.3, pthread_create.3, pthread_setaffinity_np.3, ptsname.3, remainder.3, strtod.3, tgamma.3, timegm.3, tmpnam.3, ttyname.3, console_ioctl.4, elf.5, filesystems.5, proc.5, utmp.5, capabilities.7, cgroups.7, credentials.7, ddp.7, feature_test_macros.7, fifo.7, inotify.7, libc.7, mount_namespaces.7, namespaces.7, netlink.7, pid_namespaces.7, pkeys.7, shm_overview.7, standards.7, uri.7, user_namespaces.7: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2016-12-12 09:45:24 +00:00
|
|
|
.TH IOCTL-FICLONERANGE 2 2016-12-12 "Linux" "Linux Programmer's Manual"
|
2016-03-15 16:48:10 +00:00
|
|
|
.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)
|
2016-06-08 10:17:02 +00:00
|
|
|
operation can be used to make some of the data in the
|
|
|
|
.I src_fd
|
2016-03-15 16:48:10 +00:00
|
|
|
file appear in the
|
2016-06-08 10:17:02 +00:00
|
|
|
.I dest_fd
|
2016-03-15 16:48:10 +00:00
|
|
|
file by sharing the underlying storage, which is faster than making a separate
|
2016-06-08 10:10:48 +00:00
|
|
|
physical copy of the data.
|
2016-06-08 16:40:40 +00:00
|
|
|
Both files must reside within the same filesystem.
|
2016-06-08 10:10:48 +00:00
|
|
|
If a file write should occur to a shared region,
|
2016-03-15 16:48:10 +00:00
|
|
|
the filesystem must ensure that the changes remain private to the file being
|
2016-06-08 10:10:48 +00:00
|
|
|
written.
|
|
|
|
This behavior is commonly referred to as "copy on write".
|
2016-03-15 16:48:10 +00:00
|
|
|
|
|
|
|
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 ",
|
2016-06-08 10:10:48 +00:00
|
|
|
provided that both are files.
|
2016-07-14 18:11:11 +00:00
|
|
|
If
|
|
|
|
.IR src_length
|
|
|
|
is zero, the ioctl reflinks to the end of the source file.
|
2016-06-08 10:10:48 +00:00
|
|
|
This information is conveyed in a structure of
|
2016-03-15 16:48:10 +00:00
|
|
|
the following form:
|
|
|
|
.in +4n
|
|
|
|
.nf
|
|
|
|
|
|
|
|
struct file_clone_range {
|
2016-06-08 10:17:02 +00:00
|
|
|
__s64 src_fd;
|
|
|
|
__u64 src_offset;
|
|
|
|
__u64 src_length;
|
|
|
|
__u64 dest_offset;
|
2016-03-15 16:48:10 +00:00
|
|
|
};
|
|
|
|
|
|
|
|
.fi
|
|
|
|
.in
|
|
|
|
Clones are atomic with regards to concurrent writes, so no locks need to be
|
|
|
|
taken to obtain a consistent cloned copy.
|
|
|
|
|
2016-06-08 10:17:02 +00:00
|
|
|
The
|
|
|
|
.B FICLONE
|
|
|
|
ioctl clones entire files.
|
2016-03-15 16:48:10 +00:00
|
|
|
.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
|
2016-08-07 16:58:36 +00:00
|
|
|
.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.
|
2016-03-15 16:48:10 +00:00
|
|
|
.TP
|
|
|
|
.B EINVAL
|
2016-06-08 10:10:48 +00:00
|
|
|
The filesystem does not support reflinking the ranges of the given files.
|
|
|
|
This error can also appear if either file descriptor represents
|
2016-06-08 10:17:02 +00:00
|
|
|
a device, FIFO, or socket.
|
2016-06-08 10:10:48 +00:00
|
|
|
Disk filesystems generally require the offset and length arguments
|
|
|
|
to be aligned to the fundamental block size.
|
2016-06-08 10:17:02 +00:00
|
|
|
XFS and Btrfs do not support
|
2016-03-15 16:48:10 +00:00
|
|
|
overlapping reflink ranges in the same file.
|
|
|
|
.TP
|
2016-08-07 16:58:36 +00:00
|
|
|
.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
|
2016-10-18 01:54:35 +00:00
|
|
|
descriptor, or if either file descriptor refers to special inodes.
|
2016-03-15 16:48:10 +00:00
|
|
|
.TP
|
|
|
|
.B EPERM
|
|
|
|
.IR dest_fd
|
|
|
|
is immutable.
|
|
|
|
.TP
|
|
|
|
.B ETXTBSY
|
2016-06-08 10:10:48 +00:00
|
|
|
One of the files is a swap file.
|
|
|
|
Swap files cannot share storage.
|
2016-03-15 16:48:10 +00:00
|
|
|
.TP
|
2016-08-07 16:58:36 +00:00
|
|
|
.B EXDEV
|
|
|
|
.IR dest_fd " and " src_fd
|
|
|
|
are not on the same mounted filesystem.
|
2016-06-08 10:19:19 +00:00
|
|
|
.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.
|
2016-03-15 16:48:10 +00:00
|
|
|
.SH CONFORMING TO
|
2016-06-08 10:10:48 +00:00
|
|
|
This API is Linux-specific.
|
2016-06-08 10:17:02 +00:00
|
|
|
.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.
|
2016-03-15 16:48:10 +00:00
|
|
|
.SH SEE ALSO
|
|
|
|
.BR ioctl (2)
|