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 July 24, 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 regular file to another within a file system
  34 .Sh SYNOPSIS
  35 .In sys/param.h
  36 .In sys/vnode.h
  37 .Ft int
  38 .Fo VOP_COPY_FILE_RANGE
  39 .Fa "struct vnode *invp"
  40 .Fa "off_t *inoff"
  41 .Fa "struct vnode *outvp"
  42 .Fa "off_t *outoff"
  43 .Fa "size_t *len"
  44 .Fa "unsigned int flags"
  45 .Fa "struct ucred *incred"
  46 .Fa "struct ucred *outcred"
  47 .Fa "struct thread *fsize_td"
  48 .Sh DESCRIPTION
  49 This entry point copies a byte range from one regular file to another within a
  50 file system.
  51 .Pp
  52 The arguments are:
  53 .Bl -tag -width ioflag
  54 .It Fa invp
  55 The vnode of the input file.
  56 .It Fa inoff
  57 A pointer to the file offset for the input file.
  58 .It Fa outvp
  59 The vnode of the output file.
  60 .It Fa outoff
  61 A pointer to the file offset for the output file.
  62 .It Fa len
  63 A pointer to the number of bytes to be copied.
  64 .It Fa flags
  65 Flags, should be set to 0 for now.
  66 .It Fa incred
  67 The credentials used to read
  68 .Fa invp .
  69 .It Fa outcred
  70 The credentials used to write
  71 .Fa outvp .
  72 .It Fa fsize_td
  73 The thread pointer to be passed to vn_rlimit_fsize().
  74 This will be
  75 .Dv NULL
  76 for a server thread without limits, such as for the NFS
  77 server or
  78 .Dv curthread
  79 otherwise.
  80 .El
  81 .Pp
  82 On entry and on return, the
  83 .Fa inoff
  84 and
  85 .Fa outoff
  86 arguments point to the locations of the file offsets.
  87 These file offsets should be updated by the number of bytes copied.
  88 The
  89 .Fa len
  90 argument points to the location that stores the number of bytes
  91 to be copied.
  92 It should be reduced by the number of bytes copied, which implies that
  93 the value pointed to by
  94 .Fa len
  95 will normally be zero for a non-error return.
  96 However, a copy of fewer bytes than requested is permitted.
  97 .Sh LOCKS
  98 The vnode are unlocked on entry and must be unlocked on return.
  99 The byte ranges for both
 100 .Fa invp
 101 and
 102 .Fa outvp
 103 should be range locked when this call is done.
 104 .Sh RETURN VALUES
 105 Zero is returned on success, otherwise an error code is returned.
 106 .Sh ERRORS
 107 .Bl -tag -width Er
 108 .It Bq Er EFBIG
 109 If the copy exceeds the process's file size limit or the maximum file size
 110 for the file system
 111 .Fa invp
 112 and
 113 .Fa outvp
 114 reside on.
 115 .It Bq Er EINTR
 116 A signal interrupted the VOP call before it could be completed.
 117 .It Bq Er EIO
 118 An I/O error occurred while reading/writing the files.
 119 .It Bq Er ENOSPC
 120 The file system is full.
 121 .El
 122 .Sh SEE ALSO
 123 .Xr vn_rdwr 9 ,
 124 .Xr vnode 9