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

FreeBSD 15.1-STABLE-HBSD        August 25, 2021                   FSPACECTL(2)