GETGROUPS(2)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ GETGROUPS(2) ✨

okay bestie, this is the System Calls Manual page for getgroups, and it's genuinely one of the cutest little syscalls to exist 💖 it lives in section 2 of the manual, iykyk.

🎀 NAME 🎀

getgroups — get group access list

📚 LIBRARY 📚

Standard C Library (libc, -lc) — she's in libc, bestie, no extra linking drama 🫶

🌸 SYNOPSIS 🌸

#include <unistd.h>

int
getgroups(int gidsetlen, gid_t *gidset);

💅 DESCRIPTION 💅

so, the getgroups() system call grabs the current group access list of the user process and drops it into the array gidset. that's the whole vibe. 👑

the gidsetlen argument is basically saying "bestie, here's how many entries you're allowed to put in gidset" — it's the capacity, not a request. and then getgroups() comes back and tells you the actual number of groups it returned in gidset. not the capacity, the real count. periodt.

and here's the range, no cap: at least one and as many as {NGROUPS_MAX}+1 values may be returned. so like, it's never zero, and it can go one over {NGROUPS_MAX}. iconic behavior honestly. ✨

now the fun part: if gidsetlen is zero, getgroups() just returns the number of supplementary group IDs chillin' with the calling process, and it does not touch the array that gidset points to. so you can ask "how many groups do I have?" without committing to a buffer yet. main character move. 💅

heads up though — the value of {NGROUPS_MAX} should be obtained using sysconf(3), so please please please don't hard-code it into your executable. that's the one thing the manpage is literally begging you not to do 🙈

🔥 RETURN VALUES 🔥

a successful call returns the number of groups in the group set. slay. ✅

a value of -1 means something went wrong 😭 and the error code gets stashed in the global variable errno.

💀 ERRORS 💀

here's the possible error list for getgroups(), bestie — it's short, we love a low-drama syscall:

  • [EINVAL] — the argument gidsetlen is smaller than the number of groups in the group set. your buffer said "I can hold this much" and the group set said "no you cannot" 💀
  • [EFAULT] — the argument gidset specifies an invalid address. that pointer is giving nothing. 🚫

🦋 SEE ALSO 🦋

go read those too, they're all in the same friend group 🫶

🌈 STANDARDS 🌈

the getgroups() system call conforms to IEEE Std 1003.1-2008 ("POSIX.1") — certified, standard, no notes. 👑

⭐ HISTORY ⭐

the getgroups() system call appeared in 4.2BSD. an elder. a legend. we respect her. 🌸

and that's the page, bestie!! this one's from the Debian folks, dated January 21, 2011, so shoutout to them for keeping the group list lore alive 🎀✨ love u, go call sysconf(3) instead of hard-coding things, mwah 💖

📦 where this page comes from