FSPACECTL(2) FreeBSD System Calls Manual FSPACECTL(2)
NAME
fspacectl - space management in a file
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <fcntl.h>
int
fspacectl(int fd, int cmd, const struct spacectl_range *rqsr, int flags,
struct spacectl_range *rmsr);
DESCRIPTION
fspacectl is a system call performing space management over a file. The
fd argument specifies the file descriptor to be operated on by the cmd
argument. The rqsr argument points to a spacectl_range structure that
contains the requested operation range. The flags argument controls the
behavior of the operation to take place. If the rmsr argument is non-
NULL, the spacectl_range structure it points to is updated to contain the
unprocessed operation range after the system call returns.
For a successful completion without an unprocessed part in the requested
operation range, rmsr->r_len is updated to be the value 0, and
rmsr->r_offset is updated to be rqsr->r_offset plus the number of bytes
zeroed before the end-of-file. The file descriptor's file offset is not
used or modified by the system call. Both rqsr and rmsr arguments can
point to the same structure.
The spacectl_range structure is defined as:
struct spacectl_range {
off_t r_offset;
off_t r_len;
};
The operation specified by the cmd argument may be one of:
SPACECTL_DEALLOC Zero a region in the file specified by the rqsr
argument. The rqsr->r_offset has to be a value greater
than or equal to 0, and the rqsr->r_len has to be a
value greater than 0.
If the file system supports hole-punching, file system
space deallocation may be performed in the given
region.
The flags argument needs to be the value 0 currently.
RETURN VALUES
Upon successful completion, the value 0 is returned; otherwise the value
-1 is returned and errno is set to indicate the error.
ERRORS
Possible failure conditions:
[EBADF] The fd argument is not a valid file descriptor.
[EBADF] The fd argument references a file that was opened
without write permission.
[EINTR] A signal was caught during execution.
[EINVAL] The cmd argument is not valid.
[EINVAL] If the cmd argument is SPACECTL_DEALLOC, either the
rqsr->r_offset argument was less than zero, or the
rqsr->r_len argument was less than or equal to zero.
[EINVAL] The value of rqsr->r_offset + rqsr->r_len is greater
than OFF_MAX.
[EINVAL] An invalid or unsupported flag is included in flags.
[EINVAL] A flag included in flags is not supported by the
operation specified by the cmd argument.
[EFAULT] The rqsr or a non-NULL rmsr argument point outside the
process' allocated address space.
[EIO] An I/O error occurred while reading from or writing to
a file system.
[EINTEGRITY] Corrupted data was detected while reading from the
file system.
[ENODEV] The fd argument does not refer to a file that supports
fspacectl.
[ENOSPC] There is insufficient free space remaining on the file
system storage media.
[ENOTCAPABLE] The file descriptor fd has insufficient rights.
[ESPIPE] The fd argument is associated with a pipe or FIFO.
SEE ALSO
creat(2), ftruncate(2), open(2), unlink(2)
HISTORY
The fspacectl system call appeared in FreeBSD 14.0.
AUTHORS
fspacectl and this manual page were written by Ka Ho Ng
<
[email protected]> under sponsorship from the FreeBSD Foundation.
FreeBSD 14.1-RELEASE-p8 August 25, 2021 FreeBSD 14.1-RELEASE-p8