CAP_INIT(3)

💖 NAME 💖

okay bestie, gather round, because this is cap_init, cap_free, and cap_dup — aka the capability data object storage management trio 🎀. yes, that's the whole vibe: they make the little storage box, they empty the little storage box, and they make a copy of the little storage box. slay.

✨ SYNOPSIS ✨

like, here's how you actually get at them:

#include <sys/capability.h>

cap_t cap_init(void);
int cap_free(void *obj_d);
cap_t cap_dup(cap_t cap_p);

and don't forget to link it, bestie:

Link with -lcap.

🦋 DESCRIPTION 🦋

okay so here's the thing that lowkey changes everything: the capabilities attached to a file or a process are never edited directly. nope. not ever. instead, you get given some working storage — a whole lil scratch pad — that holds a representation of the capability state. you do all your editing and manipulating inside that working storage area, and that's it. then once you're done editing, that updated capability state gets used to replace the capability state that belongs to the actual file or process. main character workflow fr fr 💅

• cap_init() — this one creates a capability state in working storage and hands you back a pointer to it. the initial value of all flags are cleared, so it's giving fresh-start energy ✨. and the way that you're supposed to free any releasable memory once you don't need that working storage anymore? call cap_free() with the cap_t as an argument. periodt.
• cap_free() — this one liberates any releasable memory that was allocated to the capability state identified by obj_d. and here's the tea: the obj_d argument may identify either a cap_t entity, or a char * entity allocated by the cap_to_text() function. so it's flexible like that, iykyk 💜.
• cap_dup() — returns a duplicate capability state in working storage, given by the source object cap_p, allocating any memory necessary, and returning a pointer to the newly created capability state. once it's duplicated, no operation on either capability state affects the other in any way — they're fully independent, no shared group chat, no overlap, nothing 🔥. when the duplicated capability state in working storage is no longer required, the caller should free any releasable memory by calling cap_free() with the cap_t as an argument. same ritual, every time 🫶.

🌈 RETURN VALUE 🌈

• cap_init() and cap_dup() return a non-NULL value on success, and NULL on failure. so if you get NULL, that's your sign bestie 😭.
• cap_free() returns zero on success, and -1 on failure.

and on failure, errno is set to EINVAL or ENOMEM. so check your errno, it's literally telling you what went wrong 🍓.

👑 CONFORMING TO 👑

these functions are specified in the withdrawn POSIX.1e draft specification. withdrawn, as in, it's not a current standard anymore — but these functions still live here, iconic behavior honestly 💀✨.

🌸 SEE ALSO 🌸

go read these next, they're all part of the same lil universe:

• libcap(3)
• cap_clear(3)
• cap_copy_ext(3)
• cap_from_text(3)
• cap_get_file(3)
• cap_get_proc(3)
• capabilities(7)

okay that's the whole page, bestie!! this one's from the Linux Programmer's Manual, and the date on it is 2021-03-06 — so it's been out here being iconic since then. go forth and manage your capability storage responsibly 🧚💖✨