share/man/man9/VOP_COPY_FILE_RANGE.9

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