SETGROUPS(2)

💖 SETGROUPS(2) 💖

okay bestie, we're in the System Calls Manual today and the vibe is group access lists. yes this is a <sys/...> girlie. yes she's a syscall. let's get into it 🫶

---

✨ NAME ✨

setgroups — set the group access list. that's it, that's the whole job 💅

---

📚 LIBRARY 📚

Standard C Library (libc, -lc). the classic. the moment. 🎀

---

🦋 SYNOPSIS 🦋

#include <sys/param.h>
#include <unistd.h>

int
setgroups(int ngroups, const gid_t *gidset);

---

🌸 DESCRIPTION 🌸

so the setgroups() system call sets the group access list of the current user process according to the array gidset. like, it rewrites the whole group situation. slay.

the ngroups argument tells you how many entries are in that array — and bestie, it must be no more than {NGROUPS_MAX}+1. no cap. don't test it. 💀

only the super-user may set a new group list. that's the rule. no super-user, no group list. periodt.

now this next part is important, so lean in 🧚:

the first entry of the group array — gidset[0] — is used as the effective group-ID for the process. it's the main character. 👑

but here's the tea: that entry gets over-written when a setgid program is run. 😭 so to avoid losing access to the privileges of that gidset[0] entry, you should duplicate it later in the group array. by convention, this happens because the group value indicated in the password file also appears in /etc/group. so the group value in the password file gets placed in gidset[0], and then that same value gets added a second time when the /etc/group file is scanned to create the group set. iconic behaviour honestly.

---

⭐ RETURN VALUES ⭐

• the setgroups() function returns the value 0 if successful 😌
• otherwise the value -1 is returned and the global variable errno is set to indicate the error 🙈

---

💀 ERRORS 💀

the setgroups() system call will fail if:

• [EPERM] — the caller is not the super-user. sorry babe, you don't have the range 💅
• [EINVAL] — the number specified in the ngroups argument is larger than the {NGROUPS_MAX}+1 limit. too many groups, bestie. chill.
• [EFAULT] — the address specified for gidset is outside the process address space. that pointer is literally not real 😭

---

🔥 SEE ALSO 🔥

• getgroups(2)
• initgroups(3)

the squad 🫶 go read them, iykyk.

---

🌈 HISTORY 🌈

the setgroups() system call appeared in 4.2BSD. a true vintage queen. 👑

---

and that's the page!! this was Debian's version, dated January 19, 2018 — yes it's from SETGROUPS(2), yes she ate, no notes 💖✨ bye bestie, go set some groups (if you're root) 🎀