From patchwork Fri Sep 4 20:17:03 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Schumaker, Anna" X-Patchwork-Id: 7126201 Return-Path: X-Original-To: patchwork-linux-btrfs@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 6AA779F402 for ; Fri, 4 Sep 2015 20:27:12 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 785ED208A9 for ; Fri, 4 Sep 2015 20:27:11 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id B9D93208B0 for ; Fri, 4 Sep 2015 20:27:09 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S933254AbbIDU1G (ORCPT ); Fri, 4 Sep 2015 16:27:06 -0400 Received: from mx143.netapp.com ([216.240.21.24]:36322 "EHLO mx143.netapp.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S933130AbbIDU0z (ORCPT ); Fri, 4 Sep 2015 16:26:55 -0400 X-IronPort-AV: E=Sophos;i="5.17,470,1437462000"; d="scan'208";a="64796195" Received: from vmwexchts01-prd.hq.netapp.com ([10.122.105.12]) by mx143-out.netapp.com with ESMTP; 04 Sep 2015 13:17:23 -0700 Received: from smtp2.corp.netapp.com (10.57.159.114) by VMWEXCHTS01-PRD.hq.netapp.com (10.122.105.12) with Microsoft SMTP Server id 15.0.1076.9; Fri, 4 Sep 2015 13:17:23 -0700 Received: from davros.com ([10.63.224.137]) by smtp2.corp.netapp.com (8.13.1/8.13.1/NTAP-1.6) with ESMTP id t84KH4kv024651; Fri, 4 Sep 2015 13:17:21 -0700 (PDT) From: Anna Schumaker To: , , , , , , , , , , Subject: [PATCH v1 9/8] copy_file_range.2: New page documenting copy_file_range() Date: Fri, 4 Sep 2015 16:17:03 -0400 Message-ID: <1441397823-1203-10-git-send-email-Anna.Schumaker@Netapp.com> X-Mailer: git-send-email 2.5.1 In-Reply-To: <1441397823-1203-1-git-send-email-Anna.Schumaker@Netapp.com> References: <1441397823-1203-1-git-send-email-Anna.Schumaker@Netapp.com> MIME-Version: 1.0 Sender: linux-btrfs-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-btrfs@vger.kernel.org X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, 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 copy_file_range() is a new system call for copying ranges of data completely in the kernel. This gives filesystems an opportunity to implement some kind of "copy acceleration", such as reflinks or server-side-copy (in the case of NFS). Signed-off-by: Anna Schumaker --- man2/copy_file_range.2 | 168 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 man2/copy_file_range.2 diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2 new file mode 100644 index 0000000..4a4cb73 --- /dev/null +++ b/man2/copy_file_range.2 @@ -0,0 +1,168 @@ +.\"This manpage is Copyright (C) 2015 Anna Schumaker +.TH COPY 2 2015-8-31 "Linux" "Linux Programmer's Manual" +.SH NAME +copy_file_range \- Copy a range of data from one file to another +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include + +.BI "ssize_t syscall(__NR_copy_file_range, int " fd_in ", loff_t * " off_in ", +.BI " int " fd_out ", loff_t * " off_out ", size_t " len ", +.BI " unsigned int " flags ); +.fi +.SH DESCRIPTION +The +.BR copy_file_range () +system call performs an in-kernel copy between two file descriptors +without all that tedious mucking about in userspace. +It copies up to +.I len +bytes of data from file descriptor +.I fd_in +to file descriptor +.I fd_out +at +.IR off_out . +The file descriptors must not refer to the same file. + +The following semantics apply for +.IR fd_in , +and similar statements apply to +.IR off_out : +.IP * 3 +If +.I off_in +is NULL, then bytes are read from +.I fd_in +starting from the current file offset and the current +file offset is adjusted appropriately. +.IP * +If +.I off_in +is not NULL, then +.I off_in +must point to a buffer that specifies the starting +offset where bytes from +.I fd_in +will be read. The current file offset of +.I fd_in +is not changed, but +.I off_in +is adjusted appropriately. +.PP +The default behavior of +.BR copy_file_range () +is filesystem specific, and might result in creating a +copy-on-write reflink. +In the event that a given filesystem does not implement +any form of copy acceleration, the kernel will perform +a deep copy of the requested range by reading bytes from +.I fd_in +and writing them to +.IR fd_out . + +Currently, Linux only supports the following flag: +.TP 1.9i +.B COPY_REFLINK +Only perform the copy if the filesystem can do it as a reflink. +Do not fall back on performing a deep copy. +.SH RETURN VALUE +Upon successful completion, +.BR copy_file_range () +will return the number of bytes copied between files. +This could be less than the length originally requested. + +On error, +.BR copy_file_range () +returns \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +One or more file descriptors are not valid, +or do not have proper read-write mode. +.TP +.B EINVAL +Requested range extends beyond the end of the file; +.I flags +argument is set to an invalid value. +.TP +.B EOPNOTSUPP +.B COPY_REFLINK +was specified in +.IR flags , +but the target filesystem does not support reflinks. +.TP +.B EXDEV +Target filesystem doesn't support cross-filesystem copies. +.SH VERSIONS +The +.BR copy_file_range () +system call first appeared in Linux 4.3. +.SH CONFORMING TO +The +.BR copy_file_range () +system call is a nonstandard Linux extension. +.SH EXAMPLE +.nf + +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include + + +int main(int argc, char **argv) +{ + int fd_in, fd_out; + struct stat stat; + loff_t len, ret; + + if (argc != 3) { + fprintf(stderr, "Usage: %s \n", argv[0]); + exit(EXIT_FAILURE); + } + + fd_in = open(argv[1], O_RDONLY); + if (fd_in == -1) { + perror("open (argv[1])"); + exit(EXIT_FAILURE); + } + + if (fstat(fd_in, &stat) == -1) { + perror("fstat"); + exit(EXIT_FAILURE); + } + len = stat.st_size; + + fd_out = open(argv[2], O_WRONLY | O_CREAT, 0644); + if (fd_out == -1) { + perror("open (argv[2])"); + exit(EXIT_FAILURE); + } + + do { + ret = syscall(__NR_copy_file_range, fd_in, NULL, + fd_out, NULL, len, 0); + if (ret == -1) { + perror("copy_file_range"); + exit(EXIT_FAILURE); + } + + len -= ret; + } while (len > 0); + + close(fd_in); + close(fd_out); + exit(EXIT_SUCCESS); +} +.fi +.SH SEE ALSO +.BR splice (2)