2 .\" SPDX-License-Identifier: BSD-2-Clause
4 .\" Copyright (c) 2021 The FreeBSD Foundation
6 .\" This manual page was written by Ka Ho Ng under sponsorship from
7 .\" the FreeBSD Foundation.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
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.
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
35 .Nd space management in a file
44 .Fa "const struct spacectl_range *rqsr"
46 .Fa "struct spacectl_range *rmsr"
50 is a system call performing space management over a file.
53 argument specifies the file descriptor to be operated on by the
60 structure that contains the requested operation range.
63 argument controls the behavior of the operation to take place.
66 argument is non-NULL, the
68 structure it points to is updated to contain the unprocessed operation range
69 after the system call returns.
71 For a successful completion without an unprocessed part in the requested
74 is updated to be the value 0, and
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.
84 arguments can point to the same structure.
88 structure is defined as:
90 struct spacectl_range {
96 The operation specified by the
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
106 has to be a value greater than or equal to 0, and the
108 has to be a value greater than 0.
110 If the file system supports hole-punching,
111 file system space deallocation may be performed in the given region.
116 argument needs to be the value 0 currently.
118 Upon successful completion, the value 0 is returned;
119 otherwise the value -1 is returned and
121 is set to indicate the error.
123 Possible failure conditions:
128 argument is not a valid file descriptor.
132 argument references a file that was opened without write permission.
134 A signal was caught during execution.
138 argument is not valid.
143 .Dv SPACECTL_DEALLOC ,
146 argument was less than zero, or the
148 argument was less than or equal to zero.
151 .Fa "rqsr->r_offset" +
156 An invalid or unsupported flag is included in
161 is not supported by the operation specified by the
169 argument point outside the process' allocated address space.
171 An I/O error occurred while reading from or writing to a file system.
173 Corrupted data was detected while reading from the file system.
177 argument does not refer to a file that supports
180 There is insufficient free space remaining on the file system storage
182 .It Bq Er ENOTCAPABLE
185 has insufficient rights.
189 argument is associated with a pipe or FIFO.
199 system call appeared in
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.