lib/libc/sys/fspacectl.2

   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 FSPACECTL 2
  32 .Os
  33 .Sh NAME
  34 .Nm fspacectl
  35 .Nd space management in a file
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In fcntl.h
  40 .Ft int
  41 .Fo fspacectl
  42 .Fa "int fd"
  43 .Fa "int cmd"
  44 .Fa "const struct spacectl_range *rqsr"
  45 .Fa "int flags"
  46 .Fa "struct spacectl_range *rmsr"
  47 .Fc
  48 .Sh DESCRIPTION
  49 .Nm
  50 is a system call performing space management over a file.
  51 The
  52 .Fa fd
  53 argument specifies the file descriptor to be operated on by the
  54 .Fa cmd
  55 argument.
  56 The
  57 .Fa rqsr
  58 argument points to a
  59 .Fa spacectl_range
  60 structure that contains the requested operation range.
  61 The
  62 .Fa flags
  63 argument controls the behavior of the operation to take place.
  64 If the
  65 .Fa rmsr
  66 argument is non-NULL, the
  67 .Fa spacectl_range
  68 structure it points to is updated to contain the unprocessed operation range
  69 after the system call returns.
  70 .Pp
  71 For a successful completion without an unprocessed part in the requested
  72 operation range,
  73 .Fa "rmsr->r_len"
  74 is updated to be the value 0, and
  75 .Fa "rmsr->r_offset"
  76 is updated to be
  77 .Fa "rqsr->r_offset"
  78 plus the number of bytes zeroed before the end-of-file.
  79 The file descriptor's file offset is not used or modified by the system call.
  80 Both
  81 .Fa rqsr
  82 and
  83 .Fa rmsr
  84 arguments can point to the same structure.
  85 .Pp
  86 The
  87 .Fa spacectl_range
  88 structure is defined as:
  89 .Bd -literal
  90 struct spacectl_range {
  91         off_t r_offset;
  92         off_t r_len;
  93 };
  94 .Ed
  95 .Pp
  96 The operation specified by the
  97 .Fa cmd
  98 argument may be one of:
  99 .Bl -tag -width SPACECTL_DEALLOC
 100 .It Dv SPACECTL_DEALLOC
 101 Zero a region in the file specified by the
 102 .Fa rqsr
 103 argument.
 104 The
 105 .Fa "rqsr->r_offset"
 106 has to be a value greater than or equal to 0, and the
 107 .Fa "rqsr->r_len"
 108 has to be a value greater than 0.
 109 .Pp
 110 If the file system supports hole-punching,
 111 file system space deallocation may be performed in the given region.
 112 .El
 113 .Pp
 114 The
 115 .Fa flags
 116 argument needs to be the value 0 currently.
 117 .Sh RETURN VALUES
 118 Upon successful completion, the value 0 is returned;
 119 otherwise the value -1 is returned and
 120 .Va errno
 121 is set to indicate the error.
 122 .Sh ERRORS
 123 Possible failure conditions:
 124 .Bl -tag -width Er
 125 .It Bq Er EBADF
 126 The
 127 .Fa fd
 128 argument is not a valid file descriptor.
 129 .It Bq Er EBADF
 130 The
 131 .Fa fd
 132 argument references a file that was opened without write permission.
 133 .It Bq Er EINTR
 134 A signal was caught during execution.
 135 .It Bq Er EINVAL
 136 The
 137 .Fa cmd
 138 argument is not valid.
 139 .It Bq Er EINVAL
 140 If the
 141 .Fa cmd
 142 argument is
 143 .Dv SPACECTL_DEALLOC ,
 144 either the
 145 .Fa "rqsr->r_offset"
 146 argument was less than zero, or the
 147 .Fa "rqsr->r_len"
 148 argument was less than or equal to zero.
 149 .It Bq Er EINVAL
 150 The value of
 151 .Fa "rqsr->r_offset" +
 152 .Fa "rqsr->r_len"
 153 is greater than
 154 .Dv OFF_MAX .
 155 .It Bq Er EINVAL
 156 An invalid or unsupported flag is included in
 157 .Fa flags .
 158 .It Bq Er EINVAL
 159 A flag included in
 160 .Fa flags
 161 is not supported by the operation specified by the
 162 .Fa cmd
 163 argument.
 164 .It Bq Er EFAULT
 165 The
 166 .Fa rqsr
 167 or a non-NULL
 168 .Fa rmsr
 169 argument point outside the process' allocated address space.
 170 .It Bq Er EIO
 171 An I/O error occurred while reading from or writing to a file system.
 172 .It Bq Er EINTEGRITY
 173 Corrupted data was detected while reading from the file system.
 174 .It Bq Er ENODEV
 175 The
 176 .Fa fd
 177 argument does not refer to a file that supports
 178 .Nm .
 179 .It Bq Er ENOSPC
 180 There is insufficient free space remaining on the file system storage
 181 media.
 182 .It Bq Er ENOTCAPABLE
 183 The file descriptor
 184 .Fa fd
 185 has insufficient rights.
 186 .It Bq Er ESPIPE
 187 The
 188 .Fa fd
 189 argument is associated with a pipe or FIFO.
 190 .El
 191 .Sh SEE ALSO
 192 .Xr creat 2 ,
 193 .Xr ftruncate 2 ,
 194 .Xr open 2 ,
 195 .Xr unlink 2
 196 .Sh HISTORY
 197 The
 198 .Nm
 199 system call appeared in
 200 .Fx 14.0 .
 201 .Sh AUTHORS
 202 .Nm
 203 and this manual page were written by
 204 .An Ka Ho Ng Aq Mt khng@FreeBSD.org
 205 under sponsorship from the FreeBSD Foundation.