FSPACECTL(2)

💖 FSPACECTL(2) — space management in a file 💖

okay so bestie, welcome to the fspacectl page from the System Calls Manual ✨ this one's a syscall, it lives in section 2, and it's literally all about managing space inside a file. let's get into it 🎀

---

✨ 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 💅

so fspacectl is a system call that does space management over a file. iconic behavior ngl 👑

here's the cast of characters, bestie:

• fd — the file descriptor the cmd argument is gonna operate on.
• rqsr — points to a spacectl_range structure holding the requested operation range.
• flags — controls how the operation behaves.
• rmsr — if it's non-NULL, the spacectl_range structure it points to gets updated to hold the unprocessed operation range after the system call returns.

so if everything goes great and there's no unprocessed part left in the requested operation range, then rmsr->r_len gets updated to the value 0, and rmsr->r_offset gets updated to be rqsr->r_offset plus the number of bytes zeroed before the end-of-file. cute, right? 💖

also very important: the file descriptor's file offset is not used or modified by the system call. and yes — both rqsr and rmsr arguments can point to the same structure. slay.

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. 🫶

and listen — if the file system supports hole-punching, file system space deallocation may be performed in the given region. no cap.

the flags argument needs to be the value 0 currently. that's it. that's the whole vibe check 🙈

---

🔥 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, bestie — read these, they're important:

• [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.

fr fr, two of these are both [EBADF] — that's not a typo on my part, that's exactly how the page lists them 💅

---

🌈 SEE ALSO 🌈

creat(2), ftruncate(2), open(2), unlink(2) — go read those too, iykyk 🦋

---

⭐ 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. give them their flowers 💐

---

and that's the whole page bestie!! 🎀 this version's from Debian, dated August 25, 2021, and it's FSPACECTL(2) all day — mwah 💋✨