git: e39c9ac21358 - main - copy_file_range.2: Document the COPY_FILE_RANGE_CLONE flag

The branch main has been updated by rmacklem:

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

commit e39c9ac213584b5398d9c1c045af5ca07c11f210
Author:     Rick Macklem <rmacklem@FreeBSD.org>
AuthorDate: 2025-08-22 22:01:59 +0000
Commit:     Rick Macklem <rmacklem@FreeBSD.org>
CommitDate: 2025-08-22 22:01:59 +0000

    copy_file_range.2: Document the COPY_FILE_RANGE_CLONE flag
    
    Commit 37b2cb5ecb0f added support for the
    COPY_FILE_RANGE_CLONE flags argument to
    copy_file_range(2).
    
    This patch documents this flags argument.
    
    This is a content change.
    
    Reviewed by:    kib
    Differential Revision:  https://reviews.freebsd.org/D51938
    Fixes:  37b2cb5ecb0f ("vfs: Add support for file cloning to VOP_COPY_FILE_RANGE")
---
 lib/libsys/copy_file_range.2 | 35 +++++++++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/lib/libsys/copy_file_range.2 b/lib/libsys/copy_file_range.2
index bcd9170842d5..829a5a5d3c13 100644
--- a/lib/libsys/copy_file_range.2
+++ b/lib/libsys/copy_file_range.2
@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd December 28, 2023
+.Dd August 16, 2025
 .Dt COPY_FILE_RANGE 2
 .Os
 .Sh NAME
@@ -74,6 +74,7 @@ argument must be opened for reading and the
 .Fa outfd
 argument must be opened for writing, but not
 .Dv O_APPEND .
+.Pp
 If
 .Fa inoffp
 or
@@ -101,9 +102,29 @@ respectively will be used/updated and the file offset for
 or
 .Fa outfd
 respectively will not be affected.
-The
+.Pp
+The only
+.Fa flags
+argument currently defined is
+.Dv COPY_FILE_RANGE_CLONE .
+When this flag is set,
+.Fn copy_file_range
+will return
+.Er EOPNOTSUPP
+if the copy cannot be done via
+block cloning.
+When
 .Fa flags
-argument must be 0.
+is 0, a file system may do the copy via block cloning
+or by data copying.
+Block cloning is only possible when the offsets (plus
+.Fa len
+if not to EOF on the input file) are block
+aligned.
+The correct block alignment can normally be acquired via the
+.Dv _PC_CLONE_BLKSIZE
+query for
+.Xr pathconf 2 .
 .Pp
 This system call attempts to maintain holes in the output file for
 the byte range being copied.
@@ -203,9 +224,15 @@ refers to a directory.
 File system that stores
 .Fa outfd
 is full.
+.It Bq Er EOPNOTSUPP
+Cannot do the copy via block cloning and the
+.Dv COPY_FILE_RANGE_CLONE
+.Fa flags
+argument is specified.
 .El
 .Sh SEE ALSO
-.Xr lseek 2
+.Xr lseek 2 ,
+.Xr pathconf 2
 .Sh STANDARDS
 The
 .Fn copy_file_range