Differential D20584 Diff 60007 share/man/man9/VOP_COPY_FILE_RANGE.9

Changeset View

Standalone View

share/man/man9/VOP_COPY_FILE_RANGE.9

				.\" 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 20, 2019
				.Dt VOP_COPY_FILE_RANGE 9
				asomersUnsubmitted Not Done Inline Actions Also update this date when you commit. asomers: Also update this date when you commit.
				.Os
				.Sh NAME
				.Nm VOP_COPY_FILE_RANGE
				.Nd copy a byte range from one regular file to another within a file system
				.Sh SYNOPSIS
				.In sys/param.h
				.In sys/vnode.h
				.Ft int
				.Fo VOP_COPY_FILE_RANGE
				.Fa "struct vnode *invp"
				kibUnsubmitted Done Inline Actions Use .Fo to avoid such long line. kib: Use .Fo to avoid such long line.
				.Fa "off_t *inoff"
				.Fa "struct vnode *outvp"
				.Fa "off_t *outoff"
				.Fa "size_t *len"
				.Fa "unsigned int flags"
				.Fa "struct ucred *incred"
				.Fa "struct ucred *outcred"
				.Fa "struct thread *fsize_td"
				.Sh DESCRIPTION
				This entry point copies a byte range from one regular file to another within a
				file system.
				.Pp
				The arguments are:
				.Bl -tag -width ioflag
				.It Fa invp
				The vnode of the input file.
				.It Fa inoff
				A pointer to the file offset for the input file.
				.It Fa outvp
				The vnode of the output file.
				.It Fa outoff
				A pointer to the file offset for the output file.
				.It Fa len
				A pointer to the number of bytes to be copied.
				.It Fa flags
				Flags, should be set to 0 for now.
				.It Fa incred
				The credentials used to read
				.Fa invp .
				.It Fa outcred
				The credentials used to write
				.Fa outvp .
				.It Fa fsize_td
				The thread pointer to be passed to vn_rlimit_fsize().
				This will be
				.Dv NULL
				asomersUnsubmitted Done Inline Actions NULL should use `.Dv`. asomers: NULL should use `.Dv`.
				for a server thread without limits, such as for the NFS
				asomersUnsubmitted Done Inline Actions When the call "is done" or "is made"? asomers: When the call "is done" or "is made"?
				asomersUnsubmitted Done Inline Actions `curthread` should also use `.Dv` asomers: `curthread` should also use `.Dv`
				server or
				.Dv curthread
				asomersUnsubmitted Done Inline Actions Will the byte ranges be locked on entry? asomers: Will the byte ranges be locked on entry?
				otherwise.
				.El
				.Pp
				When the call is done, the
				asomersUnsubmitted Done Inline Actions This line should probably read "on return", too. asomers: This line should probably read "on return", too.
				.Fa inoff
				and
				.Fa outoff
				arguments point to the locations of the file offsets.
				These file offsets should be updated by the number of bytes copied.
				The
				.Fa len
				argument points to the location that stores the number of bytes
				to be copied.
				It should be reduced by the number of bytes copied, which implies that
				the value pointed to by
				.Fa len
				will normally be zero for a non-error return.
				asomersUnsubmitted Done Inline Actions "is done" is ambiguous. Does that refer to before or after? Better to use the terminology used by other VOP man pages: "on entry" and "on return". asomers: "is done" is ambiguous. Does that refer to before or after? Better to use the terminology…
				However, a copy of less bytes than requested is permitted.
				.Sh LOCKS
				The vnode are unlocked on entry and must be unlocked on return.
				The byte ranges for both
				.Fa invp
				and
				.Fa outvp
				should be range locked when this call is done.
				.Sh RETURN VALUES
				Zero is returned on success, otherwise an error code is returned.
				.Sh ERRORS
				.Bl -tag -width Er
				.It Bq Er EFBIG
				If the copy exceeds the process's file size limit or the maximum file size
				for the file system
				.Fa invp
				and
				.Fa outvp
				reside on.
				.It Bq Er EINTR
				A signal interrupted the VOP call before it could be completed.
				.It Bq Er EIO
				An I/O error occurred while reading/writing the files.
				.It Bq Er ENOSPC
				The file system is full.
				.El
				.Sh SEE ALSO
				.Xr vn_rdwr 9 ,
				.Xr vnode 9