diff mbox series

copy_file_range.2: Kernel v5.12 updates

Message ID 20210224142307.7284-1-lhenriques@suse.de
State New
Headers show
Series copy_file_range.2: Kernel v5.12 updates | expand

Commit Message

Luis Henriques Feb. 24, 2021, 2:23 p.m. UTC
Update man-page with recent changes to this syscall.

Signed-off-by: Luis Henriques <lhenriques@suse.de>
---
Hi!

Here's a suggestion for fixing the manpage for copy_file_range().  Note that
I've assumed the fix will hit 5.12.

 man2/copy_file_range.2 | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

Comments

Amir Goldstein March 1, 2021, 2:58 p.m. UTC | #1
On Mon, Mar 1, 2021 at 4:45 PM Alejandro Colomar <alx.manpages@gmail.com> wrote:
>

> Linux 5.12 fixes a regression.

>

> Cross-filesystem (introduced in 5.3) copies were buggy.

>

> Move the statements documenting cross-fs to BUGS.

> Kernels 5.3..5.11 should be patched soon.

>

> State version information for some errors related to this.

>

> Reported-by: Luis Henriques <lhenriques@suse.de>

> Reported-by: Amir Goldstein <amir73il@gmail.com>

> Related: <https://lwn.net/Articles/846403/>

> Cc: Greg KH <gregkh@linuxfoundation.org>

> Cc: Michael Kerrisk <mtk.manpages@gmail.com>

> Cc: Anna Schumaker <anna.schumaker@netapp.com>

> Cc: Jeff Layton <jlayton@kernel.org>

> Cc: Steve French <sfrench@samba.org>

> Cc: Miklos Szeredi <miklos@szeredi.hu>

> Cc: Trond Myklebust <trond.myklebust@hammerspace.com>

> Cc: Alexander Viro <viro@zeniv.linux.org.uk>

> Cc: "Darrick J. Wong" <darrick.wong@oracle.com>

> Cc: Dave Chinner <dchinner@redhat.com>

> Cc: Nicolas Boichat <drinkcat@chromium.org>

> Cc: Ian Lance Taylor <iant@google.com>

> Cc: Luis Lozano <llozano@chromium.org>

> Cc: Andreas Dilger <adilger@dilger.ca>

> Cc: Olga Kornievskaia <aglo@umich.edu>

> Cc: Christoph Hellwig <hch@infradead.org>

> Cc: ceph-devel <ceph-devel@vger.kernel.org>

> Cc: linux-kernel <linux-kernel@vger.kernel.org>

> Cc: CIFS <linux-cifs@vger.kernel.org>

> Cc: samba-technical <samba-technical@lists.samba.org>

> Cc: linux-fsdevel <linux-fsdevel@vger.kernel.org>

> Cc: Linux NFS Mailing List <linux-nfs@vger.kernel.org>

> Cc: Walter Harms <wharms@bfs.de>

> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

> ---

>

> v3:

>         - Don't remove some important text.

>         - Reword BUGS.

>

> ---

> Hi Amir,

>

> I covered your comments.  I may need to add something else after your

> discussion with Steve; please comment.

>

> I tried to reword BUGS so that it's as specific and understandable as I can.

> If you still find it not good enough, please comment :)

>

> Thanks,

>

> Alex

>

> ---

>  man2/copy_file_range.2 | 26 ++++++++++++++++++++++----

>  1 file changed, 22 insertions(+), 4 deletions(-)

>

> diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2

> index 611a39b80..1c0df3f74 100644

> --- a/man2/copy_file_range.2

> +++ b/man2/copy_file_range.2

> @@ -169,6 +169,9 @@ Out of memory.

>  .B ENOSPC

>  There is not enough space on the target filesystem to complete the copy.

>  .TP

> +.BR EOPNOTSUPP " (since Linux 5.12)"

> +The filesystem does not support this operation.

> +.TP

>  .B EOVERFLOW

>  The requested source or destination range is too large to represent in the

>  specified data types.

> @@ -184,10 +187,17 @@ or

>  .I fd_out

>  refers to an active swap file.

>  .TP

> -.B EXDEV

> +.BR EXDEV " (before Linux 5.3)"

> +The files referred to by

> +.IR fd_in " and " fd_out

> +are not on the same filesystem.

> +.TP

> +.BR EXDEV " (since Linux 5.12)"

>  The files referred to by

>  .IR fd_in " and " fd_out

> -are not on the same mounted filesystem (pre Linux 5.3).

> +are not on the same filesystem,

> +and the source and target filesystems are not of the same type,

> +or do not support cross-filesystem copy.

>  .SH VERSIONS

>  The

>  .BR copy_file_range ()

> @@ -200,8 +210,10 @@ 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.

> +Since 5.12,

> +cross-filesystem copies can be achieved

> +when both filesystems are of the same type,

> +and that filesystem implements support for it.


Maybe refer to BUGS here for pre 5.12 behavior?

>  .SH CONFORMING TO

>  The

>  .BR copy_file_range ()

> @@ -226,6 +238,12 @@ gives filesystems an opportunity to implement "copy acceleration" techniques,

>  such as the use of reflinks (i.e., two or more inodes that share

>  pointers to the same copy-on-write disk blocks)

>  or server-side-copy (in the case of NFS).

> +.SH BUGS

> +In Linux kernels 5.3 to 5.11,

> +cross-filesystem copies were supported by the kernel,

> +instead of being supported by individual filesystems.


Not so clear/accurate IMO. Maybe:

cross-filesystem copies were implemented by the kernel,
if the operation was not supported by individual filesystems.

> +However, on some virtual filesystems,

> +the call failed to copy, while still reporting success.


Thanks,
Amir.
Darrick J. Wong March 4, 2021, 5:13 p.m. UTC | #2
On Thu, Mar 04, 2021 at 10:38:07AM +0100, Alejandro Colomar wrote:
> Linux 5.12 fixes a regression.

> 

> Cross-filesystem (introduced in 5.3) copies were buggy.

> 

> Move the statements documenting cross-fs to BUGS.

> Kernels 5.3..5.11 should be patched soon.

> 

> State version information for some errors related to this.

> 

> Reported-by: Luis Henriques <lhenriques@suse.de>

> Reported-by: Amir Goldstein <amir73il@gmail.com>

> Related: <https://lwn.net/Articles/846403/>

> Cc: Greg KH <gregkh@linuxfoundation.org>

> Cc: Michael Kerrisk <mtk.manpages@gmail.com>

> Cc: Anna Schumaker <anna.schumaker@netapp.com>

> Cc: Jeff Layton <jlayton@kernel.org>

> Cc: Steve French <sfrench@samba.org>

> Cc: Miklos Szeredi <miklos@szeredi.hu>

> Cc: Trond Myklebust <trond.myklebust@hammerspace.com>

> Cc: Alexander Viro <viro@zeniv.linux.org.uk>

> Cc: "Darrick J. Wong" <darrick.wong@oracle.com>

> Cc: Dave Chinner <dchinner@redhat.com>

> Cc: Nicolas Boichat <drinkcat@chromium.org>

> Cc: Ian Lance Taylor <iant@google.com>

> Cc: Luis Lozano <llozano@chromium.org>

> Cc: Andreas Dilger <adilger@dilger.ca>

> Cc: Olga Kornievskaia <aglo@umich.edu>

> Cc: Christoph Hellwig <hch@infradead.org>

> Cc: ceph-devel <ceph-devel@vger.kernel.org>

> Cc: linux-kernel <linux-kernel@vger.kernel.org>

> Cc: CIFS <linux-cifs@vger.kernel.org>

> Cc: samba-technical <samba-technical@lists.samba.org>

> Cc: linux-fsdevel <linux-fsdevel@vger.kernel.org>

> Cc: Linux NFS Mailing List <linux-nfs@vger.kernel.org>

> Cc: Walter Harms <wharms@bfs.de>

> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

> ---

> 

> v3:

>         - Don't remove some important text.

>         - Reword BUGS.

> v4:

> 	- Reword.

> 	- Link to BUGS.

> 

> Thanks, Amir, for all the help and better wordings.

> 

> Cheers,

> 

> Alex

> 

> ---

>  man2/copy_file_range.2 | 27 +++++++++++++++++++++++----

>  1 file changed, 23 insertions(+), 4 deletions(-)

> 

> diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2

> index 611a39b80..f58bfea8f 100644

> --- a/man2/copy_file_range.2

> +++ b/man2/copy_file_range.2

> @@ -169,6 +169,9 @@ Out of memory.

>  .B ENOSPC

>  There is not enough space on the target filesystem to complete the copy.

>  .TP

> +.BR EOPNOTSUPP " (since Linux 5.12)"

> +The filesystem does not support this operation.

> +.TP

>  .B EOVERFLOW

>  The requested source or destination range is too large to represent in the

>  specified data types.

> @@ -184,10 +187,17 @@ or

>  .I fd_out

>  refers to an active swap file.

>  .TP

> -.B EXDEV

> +.BR EXDEV " (before Linux 5.3)"

> +The files referred to by

> +.IR fd_in " and " fd_out

> +are not on the same filesystem.

> +.TP

> +.BR EXDEV " (since Linux 5.12)"

>  The files referred to by

>  .IR fd_in " and " fd_out

> -are not on the same mounted filesystem (pre Linux 5.3).

> +are not on the same filesystem,

> +and the source and target filesystems are not of the same type,

> +or do not support cross-filesystem copy.

>  .SH VERSIONS

>  The

>  .BR copy_file_range ()

> @@ -200,8 +210,11 @@ 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.

> +Since Linux 5.12,

> +cross-filesystem copies can be achieved

> +when both filesystems are of the same type,

> +and that filesystem implements support for it.

> +See BUGS for behavior prior to 5.12.

>  .SH CONFORMING TO

>  The

>  .BR copy_file_range ()

> @@ -226,6 +239,12 @@ gives filesystems an opportunity to implement "copy acceleration" techniques,

>  such as the use of reflinks (i.e., two or more inodes that share

>  pointers to the same copy-on-write disk blocks)

>  or server-side-copy (in the case of NFS).

> +.SH BUGS

> +In Linux kernels 5.3 to 5.11,

> +cross-filesystem copies were implemented by the kernel,

> +if the operation was not supported by individual filesystems.

> +However, on some virtual filesystems,

> +the call failed to copy, while still reporting success.


...success, or merely a short copy?

(The rest looks reasonable (at least by c_f_r standards) to me.)

--D

>  .SH EXAMPLES

>  .EX

>  #define _GNU_SOURCE

> -- 

> 2.30.1.721.g45526154a5

>
Alejandro Colomar March 4, 2021, 6:24 p.m. UTC | #3
Hi Darrick,

On 3/4/21 6:13 PM, Darrick J. Wong wrote:
> On Thu, Mar 04, 2021 at 10:38:07AM +0100, Alejandro Colomar wrote:

>> +However, on some virtual filesystems,

>> +the call failed to copy, while still reporting success.

> 

> ...success, or merely a short copy?


Okay.

> 

> (The rest looks reasonable (at least by c_f_r standards) to me.)


I'm curious, what does "c_f_r standards" mean? :)

Cheers,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
Darrick J. Wong March 4, 2021, 11:50 p.m. UTC | #4
On Thu, Mar 04, 2021 at 07:24:02PM +0100, Alejandro Colomar (man-pages) wrote:
> Hi Darrick,
> 
> On 3/4/21 6:13 PM, Darrick J. Wong wrote:
> > On Thu, Mar 04, 2021 at 10:38:07AM +0100, Alejandro Colomar wrote:
> > > +However, on some virtual filesystems,
> > > +the call failed to copy, while still reporting success.
> > 
> > ...success, or merely a short copy?
> 
> Okay.
> 
> > 
> > (The rest looks reasonable (at least by c_f_r standards) to me.)
> 
> I'm curious, what does "c_f_r standards" mean? :)

c_f_r is shorthand for "copy_file_range".

As for standards... well... I'll just say that this being the /second/
major shift in behavior reflects our poor community development
processes.  The door to general cross-fs copies should not have been
thrown open with as little testing as it did.  There are legendary
dchinner rants about how obviously broken the generic fallback was when
it was introduced.

There's a reason why we usually wire up new kernel functionality on an
opt-in basis, and that is to foster gradual enablement as QA resources
permit.  It's one thing for maintainers to blow up their own subsystems
in isolation, and an entirely different thing to do it between projects
with no coordination.

Did c_f_r work between an ext4 and an xfs?  I have no idea.  It seemed
to work between xfses of a similar vintage and featureset, at least, but
that's about as much testing as I have ever managed.

--D

> 
> Cheers,
> 
> Alex
> 
> -- 
> Alejandro Colomar
> Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
> http://www.alejandro-colomar.es/
diff mbox series

Patch

diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2
index 611a39b8026b..b0fd85e2631e 100644
--- a/man2/copy_file_range.2
+++ b/man2/copy_file_range.2
@@ -169,6 +169,9 @@  Out of memory.
 .B ENOSPC
 There is not enough space on the target filesystem to complete the copy.
 .TP
+.B EOPNOTSUPP
+The filesystem does not support this operation.
+.TP
 .B EOVERFLOW
 The requested source or destination range is too large to represent in the
 specified data types.
@@ -187,7 +190,7 @@  refers to an active swap file.
 .B EXDEV
 The files referred to by
 .IR fd_in " and " fd_out
-are not on the same mounted filesystem (pre Linux 5.3).
+are not on the same mounted filesystem (pre Linux 5.3 and post Linux 5.12).
 .SH VERSIONS
 The
 .BR copy_file_range ()
@@ -202,6 +205,11 @@  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.
+.PP
+After Linux 5.12, support for copies between different filesystems was dropped.
+However, individual filesystems may still provide
+.BR copy_file_range ()
+implementations that allow copies across different devices.
 .SH CONFORMING TO
 The
 .BR copy_file_range ()