git: d189a74dfdcd - main - copy_file_range(2): add recommendation to use large "len"

[Rick Macklem]

The branch main has been updated by rmacklem:

URL: https://cgit.FreeBSD.org/src/commit/?id=d189a74dfdcd4a89c92a48ecbf8fcb6f6903f9b6

commit d189a74dfdcd4a89c92a48ecbf8fcb6f6903f9b6
Author:     Rick Macklem <rmacklem at FreeBSD.org>
AuthorDate: 2021-01-03 01:21:21 +0000
Commit:     Rick Macklem <rmacklem at FreeBSD.org>
CommitDate: 2021-01-03 01:21:21 +0000

    copy_file_range(2): add recommendation to use large "len"
    
    PR#252358 reported a serious performance problem w.r.t.
    cp(1) when copying large non-sparse files.
    This problem appears to have been caused by cp(1)
    calling copy_file_range(2) with a small "len" argument.
    
    This patch adds a recommendation to use a large "len"
    value where possible, for performance reasons.
    
    Reviewed by:    asomers
    Differential Revision:  https://reviews.freebsd.org/D27935
---
 lib/libc/sys/copy_file_range.2 | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/lib/libc/sys/copy_file_range.2 b/lib/libc/sys/copy_file_range.2
index a3f714f0e7e8..22106b397ef2 100644
--- a/lib/libc/sys/copy_file_range.2
+++ b/lib/libc/sys/copy_file_range.2
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 30, 2020
+.Dd January 2, 2021
 .Dt COPY_FILE_RANGE 2
 .Os
 .Sh NAME
@@ -117,6 +117,15 @@ with
 .Dv SEEK_DATA
 arguments and this system call for the
 data ranges found.
+.Pp
+For best performance, call
+.Fn copy_file_range
+with the largest
+.Fa len
+value possible.
+It is interruptible on most file systems,
+so there is no penalty for using very large len values, even SSIZE_MAX.
+.Pp
 .Sh RETURN VALUES
 If it succeeds, the call returns the number of bytes copied, which can be fewer
 than