CAP_RIGHTS_LIMIT(2)

💅 cap_rights_limit(2) — the page where we lock down your file descriptors, bestie

okay so welcome to the cap_rights_limit(2) manual page (section 2 of the System Calls Manual, iykyk) — this is genuinely one of my fave little syscalls and I'm about to tell you why in the most normal amount of detail. 🎀

---

✨ NAME ✨

cap_rights_limit — limit capability rights 💖

📚 LIBRARY 📚

Standard C Library (libc, -lc) — the classic, the icon, the one you already link against 🌸

🦋 SYNOPSIS 🦋

#include <sys/capsicum.h>

int
cap_rights_limit(int fd, const cap_rights_t *rights);

👑 DESCRIPTION 👑

ok so picture this: a file descriptor gets created by a function like fhopen(2), kqueue(2), mq_open(2), open(2), pdfork(2), pipe(2), shm_open(2), socket(2) or socketpair(2) — and the moment it exists, it's assigned all the capability rights. like, every single one. main character energy fr fr. 🌈

meanwhile accept(2), accept4(2) and openat(2) are a little different — they inherit capability rights from the "parent" file descriptor instead. family business, love that for them. 🫶

and those rights can be reduced (but never, ever expanded) by calling the cap_rights_limit() system call. once you shrink those rights, every operation on the file descriptor gets limited to just what rights permits. no cap, only what's in the list. 💅

pro tip: the rights argument should be prepared using the cap_rights_init(3) family of functions. that's the correct way, that's the vibes. ✨

want to see what rights a file descriptor currently has? that's cap_rights_get(3). 🍓

and for the complete list of capability rights, go read the rights(4) manual page — that's where the full menu lives. 📖

---

🔥 RETURN VALUES 🔥

upon successful completion, the value 0 is returned. otherwise the value -1 is returned and the global variable errno is set to indicate the error. classic. 😭

🌟 EXAMPLES 🌟

here's a little demo showing how to limit file descriptor capability rights so that reading only is allowed. she's simple, she's effective, she's iconic. 💖

cap_rights_t setrights;
char buf[1];
int fd;

fd = open("/tmp/foo", O_RDWR);
if (fd < 0)
        err(1, "open() failed");

if (cap_enter() < 0)
        err(1, "cap_enter() failed");

cap_rights_init(&setrights, CAP_READ);
if (cap_rights_limit(fd, &setrights) < 0)
        err(1, "cap_rights_limit() failed");

buf[0] = 'X';

if (write(fd, buf, sizeof(buf)) > 0)
        errx(1, "write() succeeded!");

if (read(fd, buf, sizeof(buf)) < 0)
        err(1, "read() failed");

notice the write() is supposed to fail there — that's the whole point, bestie. we're testing that the limit actually holds. 🙈

💀 ERRORS 💀

cap_rights_limit() succeeds unless one of these happens:

• EBADF — the fd argument is not a valid active descriptor. she's not real, she's not here. ❌
• EINVAL — an invalid right has been requested in rights. you asked for something that doesn't exist, and honestly? bold of you. 🙈
• ENOSYS — the running kernel was compiled without options CAPABILITY_MODE. this kernel simply doesn't have the feature, no shade. 🫠
• ENOTCAPABLE — the rights argument contains capability rights not present for the given file descriptor. remember: the capability rights list is only ever reduced, never expanded. you can take away, you cannot add. periodt. 💅

💜 SEE ALSO 💜

accept(2), accept4(2), cap_enter(2), fhopen(2), kqueue(2), mq_open(2), open(2), openat(2), pdfork(2), pipe(2), read(2), shm_open(2), socket(2), socketpair(2), write(2), cap_rights_get(3), cap_rights_init(3), err(3), capsicum(4), rights(4) — go read them, they're all part of the same friend group 👯‍♀️

🌸 HISTORY 🌸

the cap_rights_limit() function first appeared in FreeBSD 8.3. and fun fact: support for capabilities and capabilities mode was developed as part of the TrustedBSD Project. we love a lore drop. 📜

⭐ AUTHORS ⭐

this function was created by Pawel Jakub Dawidek <pawel@dawidek.net> under sponsorship of the FreeBSD Foundation. thank you for your service, king 👑

---

and that's the whole page, bestie — mwah 💋

this cutie came to you from the Debian edition of the manpage, dated April 27, 2024, filed under CAP_RIGHTS_LIMIT(2) — go forth and cap your rights responsibly 🧚‍♀️✨