share/man/man9/VOP_DEALLOCATE.9

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3 .\"
   4 .\" Copyright (c) 2021 The FreeBSD Foundation
   5 .\"
   6 .\" This manual page was written by Ka Ho Ng under sponsorship from
   7 .\" the FreeBSD Foundation.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .Dd August 25, 2021
  31 .Dt VOP_DEALLOCATE 9
  32 .Os
  33 .Sh NAME
  34 .Nm VOP_DEALLOCATE
  35 .Nd zero and/or deallocate storage from a file
  36 .Sh SYNOPSIS
  37 .In sys/param.h
  38 .In sys/vnode.h
  39 .Ft int
  40 .Fo VOP_DEALLOCATE
  41 .Fa "struct vnode *vp"
  42 .Fa "off_t *offset"
  43 .Fa "off_t *len"
  44 .Fa "int flags"
  45 .Fa "int ioflag"
  46 .Fa "struct ucred *cred"
  47 .Fc
  48 .Sh DESCRIPTION
  49 This VOP call zeroes/deallocates storage for an offset range in a file.
  50 It is used to implement the
  51 .Xr fspacectl 2
  52 system call.
  53 .Pp
  54 Its arguments are:
  55 .Bl -tag -width offset
  56 .It Fa vp
  57 The vnode of the file.
  58 .It Fa offset
  59 The start of the range to deallocate storage in the file.
  60 .It Fa len
  61 The length of the range to deallocate storage in the file.
  62 .It Fa flags
  63 The flags of this call.
  64 This should be set to 0 for now.
  65 .It Fa ioflag
  66 Directives and hints to be given to the file system.
  67 .It Fa cred
  68 The credentials of the caller.
  69 .El
  70 .Pp
  71 .Fa *offset
  72 and
  73 .Fa *len
  74 are updated to reflect the portion of the range that
  75 still needs to be zeroed/deallocated on return.
  76 Partial result is considered a successful operation.
  77 For a non-partial successful completion,
  78 .Fa *len
  79 is updated to be the value 0, and
  80 .Fa *offset
  81 is incremented by the number of bytes zeroed before the end-of-file.
  82 .Sh LOCKS
  83 The vnode should be locked on entry and will still be locked on exit.
  84 .Sh RETURN VALUES
  85 Zero is returned if the call is successful, otherwise an appropriate
  86 error code is returned.
  87 .Sh ERRORS
  88 .Bl -tag -width Er
  89 .It Bq Er EINVAL
  90 Invalid
  91 .Fa offset , len
  92 or
  93 .Fa flags
  94 parameters are passed into this VOP call.
  95 .It Bq Er ENODEV
  96 The vnode type is not supported by this VOP call.
  97 .It Bq Er ENOSPC
  98 The file system is full.
  99 .It Bq Er EPERM
 100 An append-only flag is set on the file, but the caller is attempting to
 101 zero before the current end of file.
 102 .El
 103 .Sh SEE ALSO
 104 .Xr vnode 9
 105 .Sh AUTHORS
 106 .Nm
 107 and this manual page was written by
 108 .An Ka Ho Ng Aq Mt khng@FreeBSD.org
 109 under sponsorship from the FreeBSD Foundation.