Differential D20584 Diff 60022 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
				.Fo copy_file_range
				.Fa "int infd"
				.Fa "off_t *inoffp"
				.Fa "int outfd"
				.Fa "off_t *outoffp"
				.Fa "size_t len"
				.Fa "unsigned int flags"
				.Fc
				.Sh DESCRIPTION
				The
				.Fn copy_file_range
				system call
				copies up to
				.Fa len
				bytes from
				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.
				.Fa infd
				to
				.Fa outfd
				in the kernel.
				It may do this using a file system specific technique if
				.Fa infd
				and
				.Fa outfd
				are on the same file system.
				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 ```
				The
				.Fa infd
				argument must be opened for reading and the
				.Fa outfd
				argument must be opened for writing, but not
				asomersUnsubmitted Done Inline Actions NULL should also be .Dv NULL asomers: NULL should also be ``` .Dv NULL ```
				.Dv O_APPEND .
				If
				.Fa inoffp
				or
				.Fa outoffp
				is
				.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 must be 0.
				.Pp
				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…
				This system call attempts to maintain holes in the output file for
				the byte range being copied.
				However, this does not always work well.
				It is recommended that sparse files be copied in a loop using
				.Xr lseek 2
				with
				.Dv SEEK_HOLE ,
				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`.
				.Dv SEEK_DATA
				arguments and this system call for the
				data ranges found.
				.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
				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
				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 EINTR
				A signal interrupted the system call
				before it could be completed.
				This may happen for files on some NFS mounts.
				When this happens, the values pointed to by
				.Fa inoffp
				and
				.Fa outoffp
				are reset to the initial values for the system call.
				.It Bq Er EINVAL
				If the initial offset for
				.Fa infd
				plus
				.Fa len
				exceeds EOF for
				.Fa infd
				or
				.Fa
				flags
				is not zero.
				.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.
				.It Bq Er ENOSPC
				File system that stores
				.Fa outfd
				is full.
				.El
				.Sh SEE ALSO
				.Xr lseek 2
				.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 .