CAP_RIGHTS_GET(3)

💅 cap_rights_get — obtaining capability rights, bestie edition 🎀

okay so this is a page from the Library Functions Manual and it's all about peeking at the capability rights of a file descriptor. it's a libc thing. let's get into it ✨

---

🌸 NAME 🌸

cap_rights_get — obtain capability rights. that's the whole vibe. you ask, it tells. 💖

🦋 LIBRARY 🦋

Standard C Library — libc, -lc. yep, the classic. no cap.

✨ SYNOPSIS ✨

#include <sys/capsicum.h>

int
cap_rights_get(int fd, cap_rights_t *rights);

so you hand it an fd and a pointer to a cap_rights_t, and it fills the thing in. iconic signature, honestly. 👑

💜 DESCRIPTION 💜

okay so the cap_rights_get function lets you obtain the current capability rights for the descriptor you pass in. literally tells you what your fd is allowed to do right now.

here's the tea: the function will fill the rights argument with all capability rights if those rights were not limited — or, if they were, it fills in the capability rights that got configured during the last successful call of cap_rights_limit(2) on that same descriptor. so it's either "yeah you got everything" or "here's exactly what survived the limit". 🫶

and once you've got them stuffed into rights, you can go ahead and inspect them with the cap_rights_init(3) family of functions. that's where the actual checking happens, iykyk.

also, the complete list of capability rights lives in the rights(4) manual page — go read it, it's giving reference material 📚

🎀 RETURN VALUES 🎀

okay so on a successful completion, the value 0 is returned. slay. otherwise the value -1 is returned and the global variable errno gets set to indicate what went wrong. classic Unix behaviour, we love to see it. 💀

🌈 EXAMPLES 🌈

here's the moment you've been waiting for — a whole demo showing how to limit file descriptor capability rights and how to obtain them. main character example fr fr:

cap_rights_t setrights, getrights;
int fd;

memset(&setrights, 0, sizeof(setrights));
memset(&getrights, 0, sizeof(getrights));

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

cap_rights_init(&setrights, CAP_FSTAT, CAP_READ);
if (cap_rights_limit(fd, &setrights) < 0 && errno != ENOSYS)
        err(1, "cap_rights_limit() failed");

if (cap_rights_get(fd, &getrights) < 0 && errno != ENOSYS)
        err(1, "cap_rights_get() failed");

assert(memcmp(&setrights, &getrights, sizeof(setrights)) == 0);

the last line is the vibe check of the whole example: what we set should equal what we got back. and if it doesn't, assert is gonna yell. 😭

🔥 ERRORS 🔥

cap_rights_get() succeeds unless one of these happens:

• [EBADF] — the fd argument is not a valid active descriptor. bestie. that's not a real open fd. 🙈
• [EFAULT] — the rights argument points at an invalid address. you gave it a pointer to nowhere, and nowhere is not a place. 💀

🌟 SEE ALSO 🌟

cap_rights_limit(2), errno(2), open(2), assert(3), cap_rights_init(3), err(3), memcmp(3), memset(3), capsicum(4), rights(4)

the whole friend group, honestly. go say hi to all of them. 🫶

🧚 HISTORY 🧚

the cap_rights_get() function first appeared in FreeBSD 9.2. and fun fact: support for capabilities and capabilities mode was developed as part of the TrustedBSD Project. history lesson over, but make it fashionable. ✨

👑 AUTHORS 👑

this function was created by Pawel Jakub Dawidek <pawel@dawidek.net> under sponsorship of the FreeBSD Foundation. respect where respect is due. 💅

---

that's the whole page, bestie, you're officially an expert on cap_rights_get 🎀 this was from the Debian build of the manual, dated May 5, 2020 — go forth and check those rights. 🌸🦋💖