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 March 30, 2020 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.Fc 50.Sh DESCRIPTION 51This entry point copies a byte range from one regular file to another 52or within one file in a single file system. 53.Fa invp 54and 55.Fa outvp 56can refer to the same file. 57For this case, the byte ranges defined by 58.Fa *inoff , 59.Fa *outoff and 60.Fa *len 61will not overlap. 62.Pp 63The arguments are: 64.Bl -tag -width ioflag 65.It Fa invp 66The vnode of the input file. 67.It Fa inoff 68A pointer to the file offset for the input file. 69.It Fa outvp 70The vnode of the output file. 71.It Fa outoff 72A pointer to the file offset for the output file. 73.It Fa len 74A pointer to the byte count for the copy. 75.It Fa flags 76Flags, should be set to 0 for now. 77.It Fa incred 78The credentials used to read 79.Fa invp . 80.It Fa outcred 81The credentials used to write 82.Fa outvp . 83.It Fa fsize_td 84The thread pointer to be passed to vn_rlimit_fsize(). 85This will be 86.Dv NULL 87for a server thread without limits, such as for the NFS 88server or 89.Dv curthread 90otherwise. 91.El 92.Pp 93On entry and on return, the 94.Fa inoff 95and 96.Fa outoff 97arguments point to the locations of the file offsets. 98These file offsets should be updated by the number of bytes copied. 99The 100.Fa len 101argument points to the location that stores the number of bytes 102to be copied. 103Upon a successful return 104.Fa len 105will be updated to the number of bytes actually copied. 106Normally, this will be the number of bytes requested to be copied, 107however a copy of fewer bytes than requested is permitted. 108This does not necessarily indicate that the copy reached EOF on the input file. 109However, if the value pointed to by the 110.Fa len 111argument is zero upon a successful return, 112it indicates that the offset pointed to by 113.Fa inoff 114is at or beyond EOF on the input file. 115.Sh LOCKS 116The vnode are unlocked on entry and must be unlocked on return. 117The byte ranges for both 118.Fa invp 119and 120.Fa outvp 121should be range locked when this call is done. 122.Sh RETURN VALUES 123Zero is returned on success, otherwise an error code is returned. 124.Sh ERRORS 125.Bl -tag -width Er 126.It Bq Er EFBIG 127If the copy exceeds the process's file size limit or the maximum file size 128for the file system 129.Fa invp 130and 131.Fa outvp 132reside on. 133.It Bq Er EINTR 134A signal interrupted the VOP call before it could be completed. 135.It Bq Er EIO 136An I/O error occurred while reading/writing the files. 137.It Bq Er EINTEGRITY 138Corrupted data was detected while reading/writing the files. 139.It Bq Er ENOSPC 140The file system is full. 141.El 142.Sh SEE ALSO 143.Xr vn_rdwr 9 , 144.Xr vnode 9 145