CAP_RIGHTS_INIT(3)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💅 CAP_RIGHTS_INIT(3) — the cap_rights_t glow-up guide ✨

okay bestie, so this whole page lives in the Library Functions Manual and honestly? it's giving "libc said lemme handle your capability rights" 🫶 and we are obsessed.

✨ NAME ✨

cap_rights_init, cap_rights_set, cap_rights_clear, cap_rights_is_set, cap_rights_is_empty, cap_rights_is_valid, cap_rights_merge, cap_rights_remove, cap_rights_contains — the whole squad that manages the cap_rights_t structure 💅

🎀 LIBRARY 🎀

Standard C Library (libc, -lc) — yeah, she's built in, no cap.

🦋 SYNOPSIS 🦋

#include <sys/capsicum.h>

cap_rights_t *
cap_rights_init(cap_rights_t *rights, ...);

cap_rights_t *
cap_rights_set(cap_rights_t *rights, ...);

cap_rights_t *
cap_rights_clear(cap_rights_t *rights, ...);

bool
cap_rights_is_set(const cap_rights_t *rights, ...);

bool
cap_rights_is_empty(const cap_rights_t *rights);

bool
cap_rights_is_valid(const cap_rights_t *rights);

cap_rights_t *
cap_rights_merge(cap_rights_t *dst, const cap_rights_t *src);

cap_rights_t *
cap_rights_remove(cap_rights_t *dst, const cap_rights_t *src);

bool
cap_rights_contains(const cap_rights_t *big,
    const cap_rights_t *little);

🌸 DESCRIPTION 🌸

so these functions are literally here to let you manage the cap_rights_t structure. that's the vibe. 🧚

okay important detail incoming — when you pass capability rights to cap_rights_init(), cap_rights_set(), cap_rights_clear() and cap_rights_is_set(), you gotta separate them with commas. like this, bestie:

cap_rights_set(&rights, CAP_READ, CAP_WRITE, CAP_FSTAT, CAP_SEEK);

and if you want the complete list of capability rights, it's all chillin' in the rights(4) manual page 👑

cap_rights_init() — initializes the cap_rights_t structure you hand it. and like, this matters: only a properly initialized structure can be passed to the rest of the functions. no skipping steps 💀 for convenience you can fill the structure with capability rights right there instead of calling cap_rights_set() later. and for even more convenience, it returns a pointer to the structure you gave it, so you can yeet it straight into cap_rights_limit(2):

cap_rights_t rights;

if (cap_rights_limit(fd, cap_rights_init(&rights, CAP_READ, CAP_WRITE)) < 0)
        err(1, "Unable to limit capability rights");

cap_rights_set() — adds the capability rights you give it to the given cap_rights_t structure. adding, slay.

cap_rights_clear() — removes the capability rights you give it from the given cap_rights_t structure. bye bestie 👋

cap_rights_is_set() — checks whether all of the capability rights you named are set in the given cap_rights_t structure.

cap_rights_is_empty() — checks if the rights structure is empty. the void. the nada. 🫥

cap_rights_is_valid() — verifies that the given cap_rights_t structure is valid. vibe check, basically.

cap_rights_merge() — merges all the capability rights present in src into dst. combining friend groups fr fr.

cap_rights_remove() — removes all the capability rights present in src from dst.

cap_rights_contains() — checks if the big structure contains all the capability rights present in the little structure. big spoon energy 🥄

🔥 RETURN VALUES 🔥

ngl these functions never fail. but 👀 if you pass an invalid capability right or an invalid cap_rights_t structure as an argument, the program will be aborted. like, not a warning, not a little oopsie — aborted. 💀

  • cap_rights_init(), cap_rights_set() and cap_rights_clear() return a pointer to the cap_rights_t structure given in the rights argument.
  • cap_rights_merge() and cap_rights_remove() return a pointer to the cap_rights_t structure given in the dst argument.
  • cap_rights_is_set() returns true if all the given capability rights are set in the rights argument.
  • cap_rights_is_empty() returns true if none of the capability rights are set in the rights structure.
  • cap_rights_is_valid() performs various checks to see if the given cap_rights_t structure is valid and returns true if it is.
  • cap_rights_contains() returns true if all capability rights set in the little structure are also present in the big structure.

⭐ EXAMPLES ⭐

okay so this example is literally showing you how to prepare a cap_rights_t structure to pass to the cap_rights_limit(2) system call. iconic behavior:

cap_rights_t rights;
int fd;

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

cap_rights_init(&rights, CAP_FSTAT, CAP_READ);

if (allow_write_and_seek)
        cap_rights_set(&rights, CAP_WRITE, CAP_SEEK);

if (dont_allow_seek)
        cap_rights_clear(&rights, CAP_SEEK);

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

see how it's all cute and conditional? main character code honestly 🎀

🌈 SEE ALSO 🌈

go read 'em, iykyk 💜

👑 HISTORY 👑

the functions cap_rights_init(), cap_rights_set(), cap_rights_clear(), cap_rights_is_set(), cap_rights_is_valid(), cap_rights_merge(), cap_rights_remove() and cap_rights_contains() first appeared in FreeBSD 8.3. and support for capabilities and capabilities mode was developed as part of the TrustedBSD Project. legacy queens 🫶

💖 AUTHORS 💖

this whole family of functions was created by Pawel Jakub Dawidek <pawel@dawidek.net> under sponsorship from the FreeBSD Foundation. we stan a sponsored icon ✨

ok that's the whole page bestie, go forth and limit those rights responsibly 💅🌸

Debian • November 25, 2023 • CAP_RIGHTS_INIT(3) — mwah, catch you in the next manpage 🎀🦋💜

📦 where this page comes from