CAPNG_STAGE_ADDITIONAL_GROUPS(3)

💖 CAPNG_STAGE_ADDITIONAL_GROUPS 💖

okay bestie, welcome to the Libcap-ng API, section 3, page CAPNG_STAGE_ADDITIONAL_GROUPS. this one is lowkey niche but it's giving backstage-pass energy, so let's get into it 🎀

✨ NAME ✨

capng_stage_additional_groups — stage additional gids for capng_change_id

🌸 SYNOPSIS 🌸

#include <cap-ng.h>

int capng_stage_additional_groups(const gid_t *gids, size_t count);

🦋 DESCRIPTION 🦋

so here's the vibe: this function stages an additional gid list, ready and waiting for the next capng_change_id(3) call — but only if that call uses CAPNG_APPLY_STAGED_GROUPS. like, you're setting out the outfit the night before, but you only actually wear it if you pick that flag in the morning 💅

the gids get copied into libcap-ng internal state. and then? once capng_change_id returns, libcap-ng clears the staged gids. every time. no leftovers, no clingy exes. that clearing happens whether they were:

• applied ✅
• ignored because the flag was not set 🙈
• or discarded because the call failed 💀

and if staged gids somehow remain unused, libcap-ng also clears them when the thread-local state is deinitialized. so nothing's lingering, periodt ✨

passing a count of 0 clears any currently staged gids. that's your reset button, bestie 🫶

ngl, normally you should stick to using the supplemantal groups that are associated with the uid's account that is being changed to. this whole thing exists so you can simulate the gid model that systemd uses. no cap.

this interface is available in libcap-ng 0.9.3 and later ⭐

🔥 RETURN VALUE 🔥

• returns 0 on success 🎉
• returns -1 on failure 😭

a non-zero count with a NULL gids pointer fails with errno set to EINVAL. yeah, she said what she said 💅

🌈 SEE ALSO 🌈

• capng_change_id(3)
• capabilities(7)

👑 AUTHOR 👑

Steve Grubb

that's the whole page, bestie, you ate it up 🍓 thanks for reading — this one's from Red Hat, Mar 2026, and it lives in the Libcap-ng API section as CAPNG_STAGE_ADDITIONAL_GROUPS(3). go stage those groups, main character 💖✨🧚