Changeset View
Changeset View
Standalone View
Standalone View
lib/libc/sys/fspacectl.2
- This file was added.
.\" | |||||||||
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD | |||||||||
.\" | |||||||||
.\" Copyright (c) 2021 The FreeBSD Foundation | |||||||||
.\" | |||||||||
.\" This manual page was written by Ka Ho Ng under sponsorship from | |||||||||
.\" the FreeBSD Foundation. | |||||||||
.\" | |||||||||
.\" Redistribution and use in source and binary forms, with or without | |||||||||
.\" modification, are permitted provided that the following conditions | |||||||||
.\" are met: | |||||||||
.\" 1. Redistributions of source code must retain the above copyright | |||||||||
.\" notice, this list of conditions and the following disclaimer. | |||||||||
.\" 2. Redistributions in binary form must reproduce the above copyright | |||||||||
.\" notice, this list of conditions and the following disclaimer in the | |||||||||
.\" documentation and/or other materials provided with the distribution. | |||||||||
.\" | |||||||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | |||||||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |||||||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |||||||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | |||||||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |||||||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |||||||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |||||||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |||||||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |||||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |||||||||
.\" SUCH DAMAGE. | |||||||||
.\" | |||||||||
.Dd August 1, 2021 | |||||||||
.Dt FSPACECTL 2 | |||||||||
.Os | |||||||||
.Sh NAME | |||||||||
.Nm fspacectl | |||||||||
.Nd space management in a file | |||||||||
.Sh LIBRARY | |||||||||
.Lb libc | |||||||||
.Sh SYNOPSIS | |||||||||
.In fcntl.h | |||||||||
.Ft int | |||||||||
.Fo fspacectl | |||||||||
.Fa "int fd" | |||||||||
.Fa "int cmd" | |||||||||
.Fa "const struct spacectl_range *rqsr" | |||||||||
.Fa "int flags" | |||||||||
.Fa "struct spacectl_range *rmsr" | |||||||||
.Fc | |||||||||
.Sh DESCRIPTION | |||||||||
.Nm | |||||||||
is a system call performing space management over a file. | |||||||||
The | |||||||||
.Fa fd | |||||||||
argument specifies the file descriptor to be operated on by the | |||||||||
.Fa cmd | |||||||||
argument. | |||||||||
The | |||||||||
.Fa rqsr | |||||||||
argument points to a | |||||||||
.Fa spacectl_range | |||||||||
structure that contains the requested operation range. | |||||||||
The | |||||||||
.Fa flags | |||||||||
argument controls the behavior of the operation to take place. | |||||||||
If the | |||||||||
khng: TODO: Document SPACECTL_ALLOC | |||||||||
.Fa rmsr | |||||||||
argument is non-NULL, the | |||||||||
.Fa spacectl_range | |||||||||
structure it points to is updated to contain the unprocessed operation range | |||||||||
after the system call completes successfully. | |||||||||
Both | |||||||||
.Fa rqsr | |||||||||
and | |||||||||
.Fa rmsr | |||||||||
arguments can point to the same structure. | |||||||||
.Pp | |||||||||
The | |||||||||
.Fa spacectl_range | |||||||||
structure is defined as: | |||||||||
Done Inline Actionss/needs be/needs to be/ bcr: s/needs be/needs to be/ | |||||||||
.Bd -literal | |||||||||
struct spacectl_range { | |||||||||
Done Inline Actionss/If signal/If a signal/ bcr: s/If signal/If a signal/ | |||||||||
off_t r_offset; | |||||||||
off_t r_len; | |||||||||
Done Inline Actionss/or signal/or the signal/ bcr: s/or signal/or the signal/ | |||||||||
Not Done Inline ActionsI do not understand this sentence. Do you mean that syscall is allowed to throw out signals generated while it is running? kib: I do not understand this sentence. Do you mean that syscall is allowed to throw out signals… | |||||||||
Done Inline ActionsI meant the syscall would either return -1 with errno set to EINTR if the operation internally doesn't begin yet, or the syscall finishes the whole operation. There are no partial results to be expected if a signal was received when the syscall was ongoing. khng: I meant the syscall would either return -1 with errno set to EINTR if the operation internally… | |||||||||
}; | |||||||||
.Ed | |||||||||
.Pp | |||||||||
The operation specified by the | |||||||||
.Fa cmd | |||||||||
argument may be one of: | |||||||||
.Bl -tag -width SPACECTL_DEALLOC | |||||||||
.It Dv SPACECTL_DEALLOC | |||||||||
Zero a region in the file specified by the | |||||||||
.Fa rqsr | |||||||||
argument. | |||||||||
The | |||||||||
.Va "rqsr->r_offset" | |||||||||
has to be a value greater than or equal to 0, and the | |||||||||
.Va "rqsr->r_len" | |||||||||
has to be a value greater than 0. | |||||||||
.Pp | |||||||||
If the file system supports hole-punching, | |||||||||
file system space deallocation may be performed in the given region. | |||||||||
.El | |||||||||
.Pp | |||||||||
The | |||||||||
.Fa flags | |||||||||
argument needs to be the value 0 currently. | |||||||||
.Sh RETURN VALUES | |||||||||
Upon successful completion, the value 0 is returned; | |||||||||
otherwise the value -1 is returned and | |||||||||
.Va errno | |||||||||
is set to indicate the error. | |||||||||
.Sh ERRORS | |||||||||
Possible failure conditions: | |||||||||
.Bl -tag -width Er | |||||||||
.It Bq Er EBADF | |||||||||
The | |||||||||
.Fa fd | |||||||||
argument is not a valid file descriptor. | |||||||||
.It Bq Er EBADF | |||||||||
The | |||||||||
.Fa fd | |||||||||
argument references a file that was opened without write permission. | |||||||||
.It Bq Er EINTR | |||||||||
A signal was caught during execution. | |||||||||
.It Bq Er EINVAL | |||||||||
If the operation is | |||||||||
.Dv SPACECTL_DEALLOC , | |||||||||
either the | |||||||||
.Fa "range->r_offset" | |||||||||
argument was less than zero, or the | |||||||||
.Fa "range->r_len" | |||||||||
argument was less than or equal to zero. | |||||||||
.It Bq Er EINVAL | |||||||||
The operation is not supported by the file descriptor. | |||||||||
.It Bq Er EIO | |||||||||
An I/O error occurred while reading from or writing to a file system. | |||||||||
.It Bq Er EINTEGRITY | |||||||||
Corrupted data was detected while reading from the file system. | |||||||||
.It Bq Er ENODEV | |||||||||
The | |||||||||
.Fa fd | |||||||||
argument does not refer to a file that supports | |||||||||
.Nm . | |||||||||
.It Bq Er ENOSPC | |||||||||
There is insufficient free space remaining on the file system storage | |||||||||
media. | |||||||||
.It Bq Er ENOTCAPABLE | |||||||||
The file descriptor | |||||||||
.Fa fd | |||||||||
has insufficient rights. | |||||||||
.It Bq Er ESPIPE | |||||||||
The | |||||||||
Done Inline Actions
khng: | |||||||||
.Fa fd | |||||||||
argument is associated with a pipe or FIFO. | |||||||||
Done Inline Actions
khng: | |||||||||
.El | |||||||||
.Sh SEE ALSO | |||||||||
.Xr creat 2 , | |||||||||
.Xr ftruncate 2 , | |||||||||
.Xr open 2 , | |||||||||
.Xr unlink 2 | |||||||||
.Sh HISTORY | |||||||||
The | |||||||||
.Nm | |||||||||
system call appeared in | |||||||||
.Fx 14.0 . | |||||||||
.Sh AUTHORS | |||||||||
.Nm | |||||||||
and this manual page were written by | |||||||||
.An Ka Ho Ng Aq Mt khng@FreeBSD.org | |||||||||
under sponsorship from the FreeBSD Foundation. |
TODO: Document SPACECTL_ALLOC