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