FSPACECTL(2)

NAME
fspacectl - space management in a file

LIBRARY
libc

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 <khng@FreeBSD.org> under sponsorship from the FreeBSD Foundation.