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