From: Amir Goldstein <amir73il@gmail.com>
To: "Darrick J . Wong" <darrick.wong@oracle.com>
Cc: Dave Chinner <david@fromorbit.com>,
Christoph Hellwig <hch@lst.de>,
Olga Kornievskaia <olga.kornievskaia@gmail.com>,
Luis Henriques <lhenriques@suse.com>,
Al Viro <viro@zeniv.linux.org.uk>,
linux-fsdevel@vger.kernel.org, linux-xfs@vger.kernel.org,
linux-nfs@vger.kernel.org, linux-cifs@vger.kernel.org,
ceph-devel@vger.kernel.org, linux-api@vger.kernel.org,
Dave Chinner <dchinner@redhat.com>
Subject: [PATCH v2 9/8] man-pages: copy_file_range updates
Date: Sun, 26 May 2019 09:11:00 +0300 [thread overview]
Message-ID: <20190526061100.21761-10-amir73il@gmail.com> (raw)
In-Reply-To: <20190526061100.21761-1-amir73il@gmail.com>
Update with all the missing errors the syscall can return, the
behaviour the syscall should have w.r.t. to copies within single
files, etc.
[Amir] Copying beyond EOF returns zero.
Signed-off-by: Dave Chinner <dchinner@redhat.com>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
man2/copy_file_range.2 | 93 ++++++++++++++++++++++++++++++++++--------
1 file changed, 77 insertions(+), 16 deletions(-)
diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2
index 2438b63c8..fab11f977 100644
--- a/man2/copy_file_range.2
+++ b/man2/copy_file_range.2
@@ -42,9 +42,9 @@ without the additional cost of transferring data from the kernel to user space
and then back into the kernel.
It copies up to
.I len
-bytes of data from file descriptor
+bytes of data from the source file descriptor
.I fd_in
-to file descriptor
+to target file descriptor
.IR fd_out ,
overwriting any data that exists within the requested range of the target file.
.PP
@@ -74,6 +74,11 @@ is not changed, but
.I off_in
is adjusted appropriately.
.PP
+.I fd_in
+and
+.I fd_out
+can refer to the same file. If they refer to the same file, then the source and
+target ranges are not allowed to overlap.
.PP
The
.I flags
@@ -84,6 +89,11 @@ 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.
+If the file offset of
+.I fd_in
+is at or past the end of file, no bytes are copied, and
+.BR copy_file_range ()
+returns zero.
.PP
On error,
.BR copy_file_range ()
@@ -93,12 +103,16 @@ is set to indicate the error.
.SH ERRORS
.TP
.B EBADF
-One or more file descriptors are not valid; or
+One or more file descriptors are not valid.
+.TP
+.B EBADF
.I fd_in
is not open for reading; or
.I fd_out
-is not open for writing; or
-the
+is not open for writing.
+.TP
+.B EBADF
+The
.B O_APPEND
flag is set for the open file description (see
.BR open (2))
@@ -106,17 +120,36 @@ referred to by the file descriptor
.IR fd_out .
.TP
.B EFBIG
-An attempt was made to write a file that exceeds the implementation-defined
-maximum file size or the process's file size limit,
-or to write at a position past the maximum allowed offset.
+An attempt was made to write at a position past the maximum file offset the
+kernel supports.
+.TP
+.B EFBIG
+An attempt was made to write a range that exceeds the allowed maximum file size.
+The maximum file size differs between filesystem implemenations and can be
+different to the maximum allowed file offset.
+.TP
+.B EFBIG
+An attempt was made to write beyond the process's file size resource
+limit. This may also result in the process receiving a
+.I SIGXFSZ
+signal.
.TP
.B EINVAL
-Requested range extends beyond the end of the source file; or the
+The
.I flags
argument is not 0.
.TP
-.B EIO
-A low-level I/O error occurred while copying.
+.B EINVAL
+.I fd_in
+and
+.I fd_out
+refer to the same file and the source and target ranges overlap.
+.TP
+.B EINVAL
+.I fd_in
+or
+.I fd_out
+is not a regular file.
.TP
.B EISDIR
.I fd_in
@@ -124,22 +157,50 @@ or
.I fd_out
refers to a directory.
.TP
+.B EOVERFLOW
+The requested source or destination range is too large to represent in the
+specified data types.
+.TP
+.B EIO
+A low-level I/O error occurred while copying.
+.TP
.B ENOMEM
Out of memory.
.TP
-.B ENOSPC
-There is not enough space on the target filesystem to complete the copy.
-.TP
.B EXDEV
The files referred to by
.IR file_in " and " file_out
-are not on the same mounted filesystem.
+are not on the same mounted filesystem (pre Linux 5.3).
+.TP
+.B ENOSPC
+There is not enough space on the target filesystem to complete the copy.
+.TP
+.B TXTBSY
+.I fd_in
+or
+.I fd_out
+refers to an active swap file.
+.TP
+.B EPERM
+.I fd_out
+refers to an immutable file.
+.TP
+.B EACCES
+The user does not have write permissions for the destination file.
.SH VERSIONS
The
.BR copy_file_range ()
system call first appeared in Linux 4.5, but glibc 2.27 provides a user-space
emulation when it is not available.
.\" https://sourceware.org/git/?p=glibc.git;a=commit;f=posix/unistd.h;h=bad7a0c81f501fbbcc79af9eaa4b8254441c4a1f
+.PP
+A major rework of the kernel implementation occurred in 5.3. Areas of the API
+that weren't clearly defined were clarified and the API bounds are much more
+strictly checked than on earlier kernels. Applications should target the
+behaviour and requirements of 5.3 kernels.
+.PP
+First support for cross-filesystem copies was introduced in Linux 5.3. Older
+kernels will return -EXDEV when cross-filesystem copies are attempted.
.SH CONFORMING TO
The
.BR copy_file_range ()
@@ -224,7 +285,7 @@ main(int argc, char **argv)
}
len \-= ret;
- } while (len > 0);
+ } while (len > 0 && ret > 0);
close(fd_in);
close(fd_out);
--
2.17.1
next prev parent reply other threads:[~2019-05-26 6:11 UTC|newest]
Thread overview: 28+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-05-26 6:10 [PATCH v2 0/8] Fixes for major copy_file_range() issues Amir Goldstein
2019-05-26 6:10 ` [PATCH v2 1/8] vfs: introduce generic_copy_file_range() Amir Goldstein
2019-05-28 16:11 ` Darrick J. Wong
2019-05-26 6:10 ` [PATCH v2 2/8] vfs: no fallback for ->copy_file_range Amir Goldstein
2019-05-28 16:09 ` Darrick J. Wong
2019-05-26 6:10 ` [PATCH v2 3/8] vfs: introduce generic_file_rw_checks() Amir Goldstein
2019-05-28 16:14 ` Darrick J. Wong
2019-05-26 6:10 ` [PATCH v2 4/8] vfs: add missing checks to copy_file_range Amir Goldstein
2019-05-28 16:18 ` Darrick J. Wong
2019-05-28 16:26 ` Amir Goldstein
2019-05-28 16:31 ` Darrick J. Wong
2019-05-28 16:39 ` Amir Goldstein
2019-05-26 6:10 ` [PATCH v2 5/8] vfs: copy_file_range needs to strip setuid bits Amir Goldstein
2019-05-28 16:25 ` Darrick J. Wong
2019-05-31 19:34 ` J. Bruce Fields
2019-05-26 6:10 ` [PATCH v2 6/8] vfs: copy_file_range should update file timestamps Amir Goldstein
2019-05-27 14:35 ` Luis Henriques
2019-05-27 22:05 ` Dave Chinner
2019-05-28 8:53 ` Luis Henriques
2019-05-28 16:30 ` Darrick J. Wong
2019-05-28 16:36 ` Amir Goldstein
2019-05-26 6:10 ` [PATCH v2 7/8] vfs: allow copy_file_range to copy across devices Amir Goldstein
2019-05-28 16:34 ` Darrick J. Wong
2019-05-26 6:10 ` [PATCH v2 8/8] vfs: remove redundant checks from generic_remap_checks() Amir Goldstein
2019-05-28 16:37 ` Darrick J. Wong
2019-05-26 6:11 ` Amir Goldstein [this message]
2019-05-28 16:48 ` [PATCH v2 9/8] man-pages: copy_file_range updates Darrick J. Wong
2019-05-29 16:20 ` Amir Goldstein
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190526061100.21761-10-amir73il@gmail.com \
--to=amir73il@gmail.com \
--cc=ceph-devel@vger.kernel.org \
--cc=darrick.wong@oracle.com \
--cc=david@fromorbit.com \
--cc=dchinner@redhat.com \
--cc=hch@lst.de \
--cc=lhenriques@suse.com \
--cc=linux-api@vger.kernel.org \
--cc=linux-cifs@vger.kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-nfs@vger.kernel.org \
--cc=linux-xfs@vger.kernel.org \
--cc=olga.kornievskaia@gmail.com \
--cc=viro@zeniv.linux.org.uk \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).