CAPNG_CHANGE_ID(3)

💫 CAPNG_CHANGE_ID 💫

okay bestie, gather round, because this one is the glow-up page from the libcap-ng API (that's section 3 of your manual, mwah) and it's about switching who you are without losing your powers. iconic behavior, honestly.

---

✨ NAME ✨

capng_change_id — change the credentials while keeping your capabilities. yes, you get to be a whole new user AND keep the sparkle. 💅

---

✨ SYNOPSIS ✨

#include <cap-ng.h>

int capng_change_id(int uid, int gid, capng_flags_t flag);

---

✨ DESCRIPTION ✨

so like, this function changes the uid and gid to the ones you hand it, but it retains the capabilities you already specified back in capng_update. main character move: new identity, same power.

you can also pass -1 for either the uid or the gid, and in that case it just... doesn't touch that one, leaves it "as is". super useful if you literally only want the flag options applied (assuming, of course, that option doesn't need more privileges than you currently have — vibe check your own privileges first 🫶).

ngl, it's not necessary and maybe even better if capng_apply hasn't been called yet before this function runs, so all your necessary privileges are still intact. also — the caller may be required to still have the CAP_SETPCAP capability active before calling this, otherwise capabilities cannot be changed. and pls, do not specify CAP_SETPCAP in the capability sets unless you actually intend to still have it after the uid change. the library will silently add and remove it if it can — but if you specified it yourself, it will leave it alone. respect. 🙈

this function also takes a flag parameter that tailors exactly what actions get performed to secure the environment. the option may be or'ed together. the legal values are:

• CAPNG_NO_FLAG — simply change uid, retain the specified capabilities, and that's all. no extra credit, just the assignment. ✅
• CAPNG_DROP_SUPP_GRP — after changing the primary group ID, remove all supplementary groups. if no new primary group ID is supplied (gid == -1), this flag has no effect.
• CAPNG_INIT_SUPP_GRP — after changing id, initialize any supplemental groups that may come with the new account. if given together with CAPNG_DROP_SUPP_GRP it will have no effect.
• CAPNG_APPLY_STAGED_GROUPS — available in libcap-ng 0.9.3 and later. applies additional groups previously staged with capng_stage_additional_groups(3). if used by itself, the staged list is applied exactly. if combined with CAPNG_INIT_SUPP_GRP, the account's natural supplemental groups are initialized first and then the staged gids are merged in without duplicates. if combined with CAPNG_DROP_SUPP_GRP, the call fails. if this flag is set and no staged gids are present, the call fails. staged gids are intended to be used once and are always cleared before capng_change_id returns, even when the flag is omitted or the call fails.
• CAPNG_CLEAR_BOUNDING — clear the bounding set regardless to the internal representation already setup prior to changing the uid/gid.
• CAPNG_APPLY_BOUNDING — available in libcap-ng 0.9.3 and later. apply the internally prepared bounding set during capng_change_id. this only acts on bounding-set state explicitly prepared with capng_clear(3), capng_fill(3), or capng_update(3) using CAPNG_BOUNDING_SET. if no prepared bounding-set state exists, this flag is a no-op. if combined with CAPNG_CLEAR_BOUNDING, the call fails.
• CAPNG_CLEAR_AMBIENT — clear ambient capabilities regardless of the internal representation already setup prior to changing the uid/gid.

---

✨ RETURN VALUE ✨

returns 0 on success, and a negative number on failure. here's the receipts, bestie:

• -1 means capng has not been initted properly
• -2 means a failure requesting to keep capabilities across the uid change
• -3 means that applying the intermediate capabilities failed
• -4 means changing gid failed
• -5 means initializing supplemental groups failed
• -6 means changing the uid failed
• -7 means dropping the ability to retain caps across a uid change failed
• -8 means clearing the bounding set failed
• -9 means dropping CAP_SETPCAP or ambient capabilities failed
• -10 means resolving the target account for supplemental groups failed
• -11 means dropping supplemental groups failed
• -12 means CAPNG_DROP_SUPP_GRP and CAPNG_APPLY_STAGED_GROUPS were both set
• -13 means CAPNG_APPLY_STAGED_GROUPS was requested with no staged gids
• -14 means applying staged additional groups failed
• -15 means looking up a group account in additional groups failed
• -16 means merging initialized and staged additional groups failed
• -17 means CAPNG_APPLY_BOUNDING and CAPNG_CLEAR_BOUNDING were both set

applications that need to support libcap-ng releases older than 0.9.3 should detect the availability of CAPNG_APPLY_BOUNDING and CAPNG_APPLY_STAGED_SUPP_GRP and capng_stage_additional_groups(3) before using this flow. callers that need the prepared bounding-set behavior must request it explicitly with CAPNG_APPLY_BOUNDING so older callers continue to see the historical capng_change_id behavior. 🫡

⚠️ note, and this one is serious: the only safe action to do upon failure of this function is to probably exit. this is because you are likely in a situation with partial permissions and not what you intended. no cap, do not keep vibing after a failure here. 😭

---

🌈 SEE ALSO 🌈

capng_update(3), capng_apply(3), capng_stage_additional_groups(3), prctl(2), capabilities(7)

---

💖 AUTHOR 💖

Steve Grubb

---

and that's the whole page, bestie!! brought to you by Red Hat, from Mar 2026, living in section 3 of your manual as CAPNG_CHANGE_ID(3) — go change your id, keep your caps, and slay responsibly 💅✨🦋