CAP_FCNTLS_LIMIT(2)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 CAP_FCNTLS_LIMIT(2) — the system calls manual page, bestie edition 💖

okay so this is cap_fcntls_limit and cap_fcntls_get, two little syscalls from the System Calls Manual section of the FreeBSD man pages. they manage which fcntl commands are allowed on a file descriptor. slay. let's get into it 🦋

✨ NAME ✨

cap_fcntls_limit, cap_fcntls_get — manage allowed fcntl commands

📚 LIBRARY 📚

Standard C Library (libc, -lc)

🌸 SYNOPSIS 🌸

#include <sys/capsicum.h>

int
cap_fcntls_limit(int fd, uint32_t fcntlrights);

int
cap_fcntls_get(int fd, uint32_t *fcntlrightsp);

💅 DESCRIPTION 💅

so here's the vibe. if a file descriptor has been granted the CAP_FCNTL capability right, you can take that list of allowed fcntl(2) commands and selectively reduce it with the cap_fcntls_limit() system call. and like — reduce only. never expand. the way that it's a one-way street is honestly iconic. once you take a right away, it's gone. periodt. 💀

and if you wanna know what's still allowed? you grab a bitmask of the allowed fcntl commands for a given file descriptor with the cap_fcntls_get() system call. easy. cute. done. ✨

🎀 FLAGS 🎀

these are the flags you can shove into the fcntlrights argument, or that come back to you in the fcntlrightsp argument:

  • CAP_FCNTL_GETFL — permits the F_GETFL command. yes ma'am 🫶
  • CAP_FCNTL_SETFL — permits the F_SETFL command. 💅
  • CAP_FCNTL_GETOWN — permits the F_GETOWN command. 👑
  • CAP_FCNTL_SETOWN — permits the F_SETOWN command. 🌈

⭐ RETURN VALUES ⭐

if it works? you get 0. blessed. 🧚

if it doesn't? you get -1, and the global variable errno gets set to tell you what went wrong. not the moment. 😭

🔥 ERRORS 🔥

cap_fcntls_limit() succeeds unless:

  • [EBADF] — the fd argument is not a valid descriptor. bestie that's not a real fd, be so fr. 💀
  • [EINVAL] — an invalid flag has been passed in fcntlrights. who let that in.
  • [ENOTCAPABLE] — fcntlrights would expand the list of allowed fcntl(2) commands. nope. you can only ever shrink it, not grow it. that's the whole point. 🙈

cap_fcntls_get() succeeds unless:

  • [EBADF] — the fd argument is not a valid descriptor. again. girl.
  • [EFAULT] — the fcntlrightsp argument points at an invalid address. bad pointer energy fr fr. 😭

🌟 SEE ALSO 🌟

📜 HISTORY 📜

the cap_fcntls_get() and cap_fcntls_limit() system calls first appeared in FreeBSD 8.3. and support for capabilities and capabilities mode was developed as part of the TrustedBSD Project. lowkey a historic moment ngl. 🕰️

👑 AUTHORS 👑

this function was created by Pawel Jakub Dawidek <pawel@dawidek.net> under sponsorship of the FreeBSD Foundation. give him his flowers. 💐

also hi, quick note: this is the Debian build of the page, dated May 5, 2020. so like, shoutout to Debian for shipping it, and that's the whole page. you understood it, you're a genius, go reduce some fcntl rights responsibly. mwah. 💖✨🦋
📦 where this page comes from