CAPSICUM_HELPERS(3)

🌸 NAME 🌸

okay so bestie, this is CAPSICUM_HELPERS(3) — the manual page for the set of the capsicum helpers, part of the libcapsicum. Presenting the whole squad: caph_limit_stream, caph_limit_stdin, caph_limit_stderr, caph_limit_stdout, caph_limit_stdio, caph_stream_rights, caph_cache_tzdata, caph_cache_catpages, caph_enter, caph_enter_casper, caph_rights_limit, caph_ioctls_limit, and caph_fcntls_limit. 💅✨

---

📚 LIBRARY 📚

library “libcapsicum” — that's the one, bestie. 🎀

---

🧚 SYNOPSIS 🧚

#include <capsicum_helpers.h>

int
caph_enter(void);

int
caph_enter_casper(void);

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

int
caph_ioctls_limit(int fd, const unsigned long *cmds, size_t ncmds);

int
caph_fcntls_limit(int fd, uint32_t fcntlrights);

int
caph_limit_stream(int fd, int flags);

int
caph_limit_stdin(void);

int
caph_limit_stderr(void);

int
caph_limit_stdout(void);

int
caph_limit_stdio(void);

void
caph_stream_rights(cap_rights_t *, int flags);

void
caph_cache_tzdata(void);

void
caph_cache_catpages(void);

---

💖 DESCRIPTION 💖

So the way this works: caph_enter, caph_rights_limit, caph_ioctls_limit and caph_fcntls_limit are respectively equivalent to cap_enter(2), cap_rights_limit(2), cap_ioctls_limit(2) and cap_fcntls_limit(2), and it returns success when the kernel is built without support of the capability mode. no cap, that's literally in the lore. 🫶

caph_enter_casper is equivalent to caph_enter, and it returns success when the system is built without Casper support. lowkey iconic behavior. 🦋

The capsicum helpers are a set of a inline functions which simplify modifying programs to use Capsicum. The goal is to reduce duplicated code patterns. The capsicum helpers are part of libcapsicum, but there is no need to link to the library. yes bestie, you read that right — no linking required. 👑

caph_limit_stream() restricts capabilities on fd to only those needed by POSIX stream objects (that is, FILEs). 🌈

These flags can be provided:

• CAPH_IGNORE_EBADF — do not return an error if file descriptor is invalid. very forgiving, we love that.
• CAPH_READ — set CAP_READ on limited descriptor. reading rights, secured.
• CAPH_WRITE — set CAP_WRITE on limited descriptor. writing rights, also secured. 💅

caph_limit_stdin(), caph_limit_stderr() and caph_limit_stdout() limit standard descriptors using the caph_limit_stream function. standard bestie treatment. 🎀

caph_limit_stdio() limits stdin, stderr and stdout. all three, together, slay. ✨

caph_stream_rights may be used to initialize rights with the same rights that a stream would be limited to, as if caph_limit_stream() had been invoked using the same flags. iykyk. 🧚

caph_cache_tzdata() precaches all timezone data needed to use libc local time functions. timezone data? pre-cached? we love a prepared queen. 🕰️💖

caph_cache_catpages() caches Native Language Support (NLS) data. NLS data is used for localized error printing by strerror(3) and err(3), among others. cute and multilingual. 🌍🌸

---

🔥 RETURN VALUES 🔥

Upon successful completion, caph_enter(), caph_enter_casper(), caph_rights_limit(), caph_ioctls_limit(), caph_fcntls_limit(), caph_limit_stream(), caph_limit_stdin(), caph_limit_stderr(), caph_limit_stdout(), and caph_limit_stdio() return a value of 0. periodt. 💚

Otherwise, a value of -1 is returned and the global variable errno is set to indicate the error. not the vibe, but that's the rule. 😭

Functions caph_stream_rights(), caph_cache_tzdata(), and caph_cache_catpages() can not fail. cannot fail. absolute main character energy. 👑💀

---

⭐ SEE ALSO ⭐

cap_enter(2), cap_rights_limit(2), rights(4) — go read those too, bestie, they're in the group chat. 📚🫶

---

mwah 💋 this page is from Debian, dated May 16, 2024, and it's serving CAPSICUM_HELPERS(3) realness. bye bestie, go limit some rights! 🎀✨