From patchwork Sat Dec 19 08:56:13 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Darrick J. Wong" X-Patchwork-Id: 7889611 Return-Path: X-Original-To: patchwork-linux-fsdevel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id 68C739F32E for ; Sat, 19 Dec 2015 08:56:26 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 190E1203C4 for ; Sat, 19 Dec 2015 08:56:25 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id C8EE3204D8 for ; Sat, 19 Dec 2015 08:56:23 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753742AbbLSI4W (ORCPT ); Sat, 19 Dec 2015 03:56:22 -0500 Received: from aserp1040.oracle.com ([141.146.126.69]:49792 "EHLO aserp1040.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753373AbbLSI4U (ORCPT ); Sat, 19 Dec 2015 03:56:20 -0500 Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id tBJ8uFJX019626 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 19 Dec 2015 08:56:16 GMT Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by userv0022.oracle.com (8.13.8/8.13.8) with ESMTP id tBJ8uFEI024897 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Sat, 19 Dec 2015 08:56:15 GMT Received: from abhmp0008.oracle.com (abhmp0008.oracle.com [141.146.116.14]) by aserv0121.oracle.com (8.13.8/8.13.8) with ESMTP id tBJ8uFiC023848; Sat, 19 Dec 2015 08:56:15 GMT Received: from localhost (/24.21.154.84) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 19 Dec 2015 00:56:14 -0800 Subject: [PATCH 1/2] man2: document FICLONE and FICLONERANGE From: "Darrick J. Wong" To: mtk.manpages@gmail.com, darrick.wong@oracle.com Cc: linux-fsdevel@vger.kernel.org, linux-api@vger.kernel.org, linux-man@vger.kernel.org Date: Sat, 19 Dec 2015 00:56:13 -0800 Message-ID: <20151219085613.12660.75735.stgit@birch.djwong.org> In-Reply-To: <20151219085607.12660.75196.stgit@birch.djwong.org> References: <20151219085607.12660.75196.stgit@birch.djwong.org> User-Agent: StGit/0.17.1-dirty MIME-Version: 1.0 X-Source-IP: userv0022.oracle.com [156.151.31.74] Sender: linux-fsdevel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fsdevel@vger.kernel.org X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Document the FICLONE and FICLONERANGE ioctls, formerly known as the BTRFS_IOC_CLONE and BTRFS_IOC_CLONE_RANGE ioctls. Signed-off-by: Darrick J. Wong --- man2/ioctl_ficlone.2 | 89 +++++++++++++++++++++++++++++++++++ man2/ioctl_ficlonerange.2 | 116 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 205 insertions(+) create mode 100644 man2/ioctl_ficlone.2 create mode 100644 man2/ioctl_ficlonerange.2 -- To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/man2/ioctl_ficlone.2 b/man2/ioctl_ficlone.2 new file mode 100644 index 0000000..ba851da --- /dev/null +++ b/man2/ioctl_ficlone.2 @@ -0,0 +1,89 @@ +.\" Copyright (C) 2015 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-FICLONE 2 2015-12-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl_ficlone \- share all the data of one file with another file +.SH SYNOPSIS +.br +.B #include +.sp +.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 all 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". +.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. +.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 +and was private to btrfs. +.fi +.in +.SH SEE ALSO +.BR ioctl (2) diff --git a/man2/ioctl_ficlonerange.2 b/man2/ioctl_ficlonerange.2 new file mode 100644 index 0000000..80263c5 --- /dev/null +++ b/man2/ioctl_ficlonerange.2 @@ -0,0 +1,116 @@ +.\" Copyright (C) 2015 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 2015-12-15 "Linux" "Linux Programmer's Manual" +.SH NAME +ioctl_ficlonerange \- share some the data of one file with another file +.SH SYNOPSIS +.br +.B #include +.sp +.BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range * " arg ); +.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 +.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. Not all filesystems 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)