1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2019 Rick Macklem 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd November 9, 2019 29.Dt VOP_COPY_FILE_RANGE 9 30.Os 31.Sh NAME 32.Nm VOP_COPY_FILE_RANGE 33.Nd copy a byte range from one file to another or within one file 34in a single file system 35.Sh SYNOPSIS 36.In sys/param.h 37.In sys/vnode.h 38.Ft int 39.Fo VOP_COPY_FILE_RANGE 40.Fa "struct vnode *invp" 41.Fa "off_t *inoff" 42.Fa "struct vnode *outvp" 43.Fa "off_t *outoff" 44.Fa "size_t *len" 45.Fa "unsigned int flags" 46.Fa "struct ucred *incred" 47.Fa "struct ucred *outcred" 48.Fa "struct thread *fsize_td" 49.Sh DESCRIPTION 50This entry point copies a byte range from one regular file to another 51or within one file in a single file system. 52.Fa invp 53and 54.Fa outvp 55can refer to the same file. 56For this case, the byte ranges defined by 57.Fa *inoff , 58.Fa *outoff and 59.Fa *len 60will not overlap. 61.Pp 62The arguments are: 63.Bl -tag -width ioflag 64.It Fa invp 65The vnode of the input file. 66.It Fa inoff 67A pointer to the file offset for the input file. 68.It Fa outvp 69The vnode of the output file. 70.It Fa outoff 71A pointer to the file offset for the output file. 72.It Fa len 73A pointer to the byte count for the copy. 74.It Fa flags 75Flags, should be set to 0 for now. 76.It Fa incred 77The credentials used to read 78.Fa invp . 79.It Fa outcred 80The credentials used to write 81.Fa outvp . 82.It Fa fsize_td 83The thread pointer to be passed to vn_rlimit_fsize(). 84This will be 85.Dv NULL 86for a server thread without limits, such as for the NFS 87server or 88.Dv curthread 89otherwise. 90.El 91.Pp 92On entry and on return, the 93.Fa inoff 94and 95.Fa outoff 96arguments point to the locations of the file offsets. 97These file offsets should be updated by the number of bytes copied. 98The 99.Fa len 100argument points to the location that stores the number of bytes 101to be copied. 102Upon a successful return 103.Fa len 104will be updated to the number of bytes actually copied. 105Normally, this will be the number of bytes requested to be copied, 106however a copy of fewer bytes than requested is permitted. 107This does not necessarily indicate that the copy reached EOF on the input file. 108However, if the value pointed to by the 109.Fa len 110argument is zero upon a successful return, 111it indicates that the offset pointed to by 112.Fa inoff 113is at or beyond EOF on the input file. 114.Sh LOCKS 115The vnode are unlocked on entry and must be unlocked on return. 116The byte ranges for both 117.Fa invp 118and 119.Fa outvp 120should be range locked when this call is done. 121.Sh RETURN VALUES 122Zero is returned on success, otherwise an error code is returned. 123.Sh ERRORS 124.Bl -tag -width Er 125.It Bq Er EFBIG 126If the copy exceeds the process's file size limit or the maximum file size 127for the file system 128.Fa invp 129and 130.Fa outvp 131reside on. 132.It Bq Er EINTR 133A signal interrupted the VOP call before it could be completed. 134.It Bq Er EIO 135An I/O error occurred while reading/writing the files. 136.It Bq Er ENOSPC 137The file system is full. 138.El 139.Sh SEE ALSO 140.Xr vn_rdwr 9 , 141.Xr vnode 9 142