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 | |||||||||
| .\" | |||||||||
| .\" 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 Feb 08, 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 | |||||||||
| .Fn fspacectl "int fd" "int cmd" "struct spacectl_range *range" "int flags" | |||||||||
| .Sh DESCRIPTION | |||||||||
| .Nm | |||||||||
| is a system call performing space management in the file referenced by | |||||||||
| .Fa fd . | |||||||||
| .Fa cmd | |||||||||
| specifies the operation to take place in the file. | |||||||||
| .Fa range | |||||||||
| is the operation range. | |||||||||
| .Fa flags | |||||||||
| controls the behavior of the operation to take place. | |||||||||
| .Pp | |||||||||
| The | |||||||||
| .Fa range | |||||||||
| argument points to a structure defined as: | |||||||||
| .Bd -literal | |||||||||
| struct spacectl_range { | |||||||||
| off_t r_offset; | |||||||||
| off_t r_len; | |||||||||
| }; | |||||||||
| .Ed | |||||||||
| .Pp | |||||||||
| The operation specified by the | |||||||||
| .Fa cmd | |||||||||
| argument may be one of: | |||||||||
| .Bl -tag -width SPACECTL_DEALLOC | |||||||||
| .It Dv SPACECTL_ALLOC | |||||||||
khng: TODO: Document SPACECTL_ALLOC | |||||||||
| Back a region in the file specified by the | |||||||||
| .Fa range | |||||||||
| argument with file system space. | |||||||||
| This operation is used to implement | |||||||||
| .Xr posix_fallocate 2 . | |||||||||
| Content will remain the same for non-hole region. | |||||||||
| Holes will be converted to non-hole region with zeroes. | |||||||||
| .It Dv SPACECTL_DEALLOC | |||||||||
| Zero a region in the file specified by the | |||||||||
| .Fa range | |||||||||
| argument. | |||||||||
| If the file system supports hole-punching, | |||||||||
| file system space deallocation may be performed in the given region. | |||||||||
| .El | |||||||||
Done Inline Actionss/needs be/needs to be/ bcr: s/needs be/needs to be/ | |||||||||
| .Pp | |||||||||
| The | |||||||||
Done Inline Actionss/If signal/If a signal/ bcr: s/If signal/If a signal/ | |||||||||
| .Fa flags | |||||||||
| argument may include one or more of the following: | |||||||||
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… | |||||||||
| .Bl -tag -width SPACECTL_F_CANEXTEND | |||||||||
| .It Dv SPACECTL_F_CANEXTEND | |||||||||
| The operation can extend the file size if | |||||||||
| .Fa range->r_offset | |||||||||
| + | |||||||||
| .Fa range->r_len | |||||||||
| is greater than the current file size. | |||||||||
| .El | |||||||||
| .Pp | |||||||||
| For | |||||||||
| .Dv SPACECTL_ALLOC | |||||||||
| and | |||||||||
| .Dv SPACECTL_DEALLOC | |||||||||
| operations, unless | |||||||||
| .Fa flags | |||||||||
| includes | |||||||||
| .Dv SPACECTL_F_CANEXTEND, region specified in | |||||||||
| .Fa range | |||||||||
| beyonds file size will not extend the file size. | |||||||||
| .Pp | |||||||||
| If signal is delivered to a thread calling this system call, | |||||||||
| the system call would either finish as if nothing has happened, | |||||||||
| or signal would be delivered after the operation finishes. | |||||||||
| .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 EFBIG | |||||||||
| The value of | |||||||||
| .Fa offset + | |||||||||
| .Fa len | |||||||||
| is greater than the maximum file size when | |||||||||
| .Dv SPACECTL_F_CANEXTEND | |||||||||
| is set. | |||||||||
| .It Bq Er EINTR | |||||||||
| A signal was caught during execution. | |||||||||
| .It Bq Er EINVAL | |||||||||
| Either the | |||||||||
| .Fa "range->r_offset" | |||||||||
| argument was less than zero, or the | |||||||||
| .Fa "range->r_len" | |||||||||
| argument was less than zero, | |||||||||
| or the operation is not supported by the file system. | |||||||||
| .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 | |||||||||
Done Inline Actions
khng: | |||||||||
| has insufficient rights. | |||||||||
| .It Bq Er ESPIPE | |||||||||
Done Inline Actions
khng: | |||||||||
| The | |||||||||
| .Fa fd | |||||||||
| argument is associated with a pipe or FIFO. | |||||||||
| .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 developed by | |||||||||
| .An Ka Ho Ng Aq Mt khng@FreeBSDFoundation.org | |||||||||
| under sponsorship from the FreeBSD Foundation. | |||||||||
TODO: Document SPACECTL_ALLOC