Changeset View
Changeset View
Standalone 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 | |||||
asomers: Also update this date when you commit. | |||||
.Dt VOP_COPY_FILE_RANGE 9 | |||||
.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" | |||||
Done Inline ActionsUse .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 NULL for a server thread without limits, such as for the NFS | |||||
asomersUnsubmitted Done Inline ActionsNULL should use .Dv. asomers: NULL should use `.Dv`. | |||||
server or curthread otherwise. | |||||
asomersUnsubmitted Done Inline Actionscurthread should also use .Dv asomers: `curthread` should also use `.Dv` | |||||
.El | |||||
Done Inline ActionsWhen the call "is done" or "is made"? asomers: When the call "is done" or "is made"? | |||||
.Pp | |||||
When the call is done, the | |||||
Done Inline ActionsWill the byte ranges be locked on entry? asomers: Will the byte ranges be locked on entry? | |||||
.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. | |||||
Done Inline ActionsThis line should probably read "on return", too. asomers: This line should probably read "on return", too. | |||||
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. | |||||
However, a copy of less bytes than requested is permitted. | |||||
.Sh LOCKS | |||||
The vnodes are unlocked when the call is done and should be unlocked | |||||
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… | |||||
when the call returns. | |||||
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 |
Also update this date when you commit.