Differential D20584 Diff 58815 lib/libc/sys/copy_file_range.2

Changeset View

Standalone View

lib/libc/sys/copy_file_range.2

				.\" SPDX-License-Identifier: BSD-2-Clause
				.\"
				.\" Copyright (c) 2019 Rick Macklem
				.\"
				.\" Redistribution and use in source and binary forms, with or without
				.\" modification, are permitted provided that the following conditions
				.\" are met:
				.\" 1. Redistributions of source code must retain the above copyright
				.\" notice, this list of conditions and the following disclaimer.
				.\" 2. Redistributions in binary form must reproduce the above copyright
				.\" notice, this list of conditions and the following disclaimer in the
				.\" documentation and/or other materials provided with the distribution.
				.\"
				.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
				.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
				.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
				.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
				.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
				.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
				.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
				.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
				.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
				.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
				.\" SUCH DAMAGE.
				.\"
				.\" $FreeBSD$
				.\"
				.Dd June 9, 2019
				.Dt COPY_FILE_RANGE 2
				asomersUnsubmitted Not Done Inline Actions Don't forget to bump the man page date whenever you actually commit this. asomers: Don't forget to bump the man page date whenever you actually commit this.
				.Os
				.Sh NAME
				.Nm copy_file_range
				.Nd kernel copy of a byte range from one file to another
				.Sh LIBRARY
				.Lb libc
				.Sh SYNOPSIS
				.In sys/types.h
				.In unistd.h
				.Ft ssize_t
				.Fn copy_file_range "int infd" "off_t inoffp" "int outfd" "off_t outoffp" "size_t len" "unsigned int flags"
				.Fc
				.Sh DESCRIPTION
				The
				.Fn copy_file_range
				system call
				copies
				.Fa len
				bytes from
				.Fa infd
				to
				.Fa outfd
				in the kernel.
				It may do this using a file system specific technique if
				.Fa infd
				asomersUnsubmitted Done Inline Actions The Linux man page says it will return `EXDEV` if the file descriptors are on different file systems. But I like your version better. asomers: The Linux man page says it will return `EXDEV` if the file descriptors are on different file…
				rmacklemAuthorUnsubmitted Done Inline Actions I don't see why EXDEV would be returned, so I left it off the man page. rmacklem: I don't see why EXDEV would be returned, so I left it off the man page.
				and
				.Fa outfd
				are on the same file system.
				The
				.Fa infd
				argument must be opened for reading and the
				.Fa outfd
				argument must be opened for writing, but not
				.Dv O_APPEND .
				asomersUnsubmitted Done Inline Actions O_APPEND should be on its own line like this: .Dv O_APPEND asomers: O_APPEND should be on its own line like this: ``` .Dv O_APPEND ```
				If
				.Fa inoffp
				or
				.Fa outoffp
				is
				asomersUnsubmitted Done Inline Actions NULL should also be .Dv NULL asomers: NULL should also be ``` .Dv NULL ```
				.Dv NULL ,
				the file offset for
				.Fa infd
				or
				.Fa outfd
				respectively will be used and updated by
				the number of bytes copied.
				If
				.Fa inoffp
				or
				.Fa outoffp
				is not
				.Dv NULL ,
				the byte offset pointed to by
				.Fa inoffp
				or
				.Fa outoffp
				respectively will be used/updated and the file offset for
				.Fa infd
				or
				.Fa outfd
				respectively will not be affected.
				The
				.Fa flags
				argument is currently ignored and should be set to 0.
				.Pp
				.Sh RETURN VALUES
				If it succeeds, the call returns the number of bytes copied, which can be less
				than
				.Fa len .
				.Fn copy_file_range
				should be used in a loop until copying of the desired byte range has been
				jillesUnsubmitted Done Inline Actions The Linux man page (from http://man7.org/linux/man-pages/man2/copy_file_range.2.html ) says that a non-zero flags argument will cause the call to return an [EINVAL] error. I think that is better than ignoring the argument completely since it allows adding flags more safely (since there will not be existing applications that pass in, for example, uninitialized data as flags). jilles: The Linux man page (from http://man7.org/linux/man-pages/man2/copy_file_range.2.html ) says…
				rmacklemAuthorUnsubmitted Done Inline Actions I'll take this over to FreeBSD-current@, since it is a "big picture" discussion. (If I knew how to put FreeBSD-current@ or FreeBSD-fs@ in the list(s) that get these comments, life would be simpler;-) rmacklem: I'll take this over to FreeBSD-current@, since it is a "big picture" discussion. (If I knew how…
				completed.
				If an error has occurred, a \-1 is returned and the error code is placed in
				the global variable
				.Va errno .
				.Sh ERRORS
				The
				.Fn copy_file_range
				asomersUnsubmitted Done Inline Actions SEEK_HOLE and SEEK_DATA should be marked up with `.Dv`. asomers: SEEK_HOLE and SEEK_DATA should be marked up with `.Dv`.
				system call
				will fail if:
				.Bl -tag -width Er
				.It Bq Er EBADF
				If
				.Fa
				infd
				is not open for reading or
				.Fa
				outfd
				is not open for writing, or opened for writing with
				.Dv O_APPEND ,
				or if
				.Fa infd
				and
				.Fa outfd
				refer to the same file.
				.It Bq Er EFBIG
				If the copy exceeds the process's file size limit or the maximum file size
				for the file system
				.Fa outfd
				resides on.
				.It Bq Er EINVAL
				If the initial offset for
				.Fa infd
				plus
				.Fa len
				exceeds EOF for
				.Fa infd .
				.It Bq Er EIO
				An I/O error occurred while reading/writing the files.
				.It Bq Er EISDIR
				If either
				.Fa infd
				or
				.Fa outfd
				refers to a directory.
				.El
				.Sh STANDARDS
				The
				.Fn copy_file_range
				system call is expected to be compatible with the Linux system call of
				the same name.
				.Sh HISTORY
				The
				.Fn copy_file_range
				function appeared in
				.Fx 13.0 .