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

(cherry picked from commit 84b4342c0d7ac8a3187309a978d41e6765154cc1)

1 files 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