git: 84b4342c0d7a - main - copy_file_range.2: Clarify that only regular files work

From: Rick Macklem <rmacklem_at_FreeBSD.org>
Date: Fri, 29 Dec 2023 23:00:50 UTC
The branch main has been updated by rmacklem:

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

commit 84b4342c0d7ac8a3187309a978d41e6765154cc1
Author:     Rick Macklem <rmacklem@FreeBSD.org>
AuthorDate: 2023-12-29 22:59:00 +0000
Commit:     Rick Macklem <rmacklem@FreeBSD.org>
CommitDate: 2023-12-29 22:59:00 +0000

    copy_file_range.2: Clarify that only regular files work
    
    PR#273962 reported that copy_file_range(2) did not work
    on shared memory objects and returned EINVAL.
    Although the reporter felt this was incorrect, it is what
    the Linux copy_file_range(2) syscall does.
    
    Since there was no collective agreement that the FreeBSD
    semantics should be changed to no longer be Linux compatible,
    copy_file_range(2) still works on regular files only.
    
    This man page update clarifies that. If, someday, copy_file_range(2)
    is changed to support non-regular files, then the man page will
    need to be updated to reflect that.
    
    PR:     273962
    Reviewed by:    karels, pauamma_gundo.com (manpages)
    MFC after:      1 week
    Differential Revision:  https://reviews.freebsd.org/D43227
---
 lib/libc/sys/copy_file_range.2 | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/lib/libc/sys/copy_file_range.2 b/lib/libc/sys/copy_file_range.2
index c9fa593b7f4c..bcd9170842d5 100644
--- a/lib/libc/sys/copy_file_range.2
+++ b/lib/libc/sys/copy_file_range.2
@@ -23,13 +23,13 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd January 2, 2021
+.Dd December 28, 2023
 .Dt COPY_FILE_RANGE 2
 .Os
 .Sh NAME
 .Nm copy_file_range
-.Nd kernel copy of a byte range from one file to another
-or within one file
+.Nd kernel copy of a byte range from one regular file to another
+or within one regular file
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
@@ -178,9 +178,17 @@ are reset to the initial values for the system call.
 .Fa infd
 and
 .Fa outfd
-refer to the same file and the byte ranges overlap or
+refer to the same file and the byte ranges overlap.
+.It Bq Er EINVAL
+The
 .Fa flags
-is not zero.
+argument is not zero.
+.It Bq Er EINVAL
+Either
+.Fa infd
+or
+.Fa outfd
+refers to a file object that is not a regular file.
 .It Bq Er EIO
 An I/O error occurred while reading/writing the files.
 .It Bq Er EINTEGRITY