getgrent(3)

💖 getgrent(3) 💖

omg bestie hi!! so this is literally the getgrent page from the Library Functions Manual (that's the 3 in getgrent(3) — library functions, not syscalls, iykyk) and it's all about reading the group database. it's giving ✨group lore✨. let's get into it 🫶

---

🌸 NAME 🌸

getgrent, setgrent, endgrent — get group file entry 🎀

📚 LIBRARY 📚

Standard C library (libc, -lc) — yes queen, you gotta link the C library, that's the vibe 💅

✨ SYNOPSIS ✨

okay so first you gotta pull in the headers, no cap:

#include <sys/types.h>
#include <grp.h>

then here's the trio of functions 🦋:

struct group *getgrent(void);

void setgrent(void);
void endgrent(void);

🧚 Feature Test Macro Requirements for glibc 🧚

(go look at feature_test_macros(7) if you're lost, bestie — it explains all this)

setgrent():

_XOPEN_SOURCE >= 500
    || /* glibc >= 2.19: */ _DEFAULT_SOURCE
    || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

getgrent(), endgrent():

Since glibc 2.22:
    _XOPEN_SOURCE >= 500 || _DEFAULT_SOURCE
glibc 2.21 and earlier
    _XOPEN_SOURCE >= 500
        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
        || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

like, yes, the version matters, the #defines are NOT one-size-fits-all, periodt 😤

---

💜 DESCRIPTION 💜

okay so the main character here is getgrent(). it hands you back a pointer to a structure stuffed with the broken-out fields of a record from the group database — and when we say "the group database" we mean stuff like the local group file /etc/group, plus NIS and LDAP, she's flexible 💅.

the first time you call getgrent(), you get the first entry. after that? successive entries, one at a time, like a little conveyor belt of groups 🍓.

setgrent() is the rewind button — it goes back to the very beginning of the group database so you can scan the whole thing again 🔁.

endgrent() is the "we're done here, close the group database" function. clean up after yourself, bestie 🧹.

the group structure lives in <grp.h> and looks exactly like this, don't @ me:

struct group {
    char   *gr_name;        /* group name */
    char   *gr_passwd;      /* group password */
    gid_t   gr_gid;         /* group ID */
    char  **gr_mem;         /* NULL-terminated array of pointers
                               to names of group members */
};

want the full tea on what each field means? go read group(5), it's all there 💖

---

👑 RETURN VALUE 👑

getgrent() gives you a pointer to a group structure. or NULL — either because there are no more entries, or because an error happened 😭 (yes, same NULL, you gotta check errno to tell them apart, life is unfair).

on error, errno may be set. and if you actually wanna check errno after the call? set it to zero before the call. that's the move, no cap.

⚠️ big heads up bestie: the return value may point to a static area, and it can get overwritten by later calls to getgrent(), getgrgid(3), or getgrnam(3). so don't go holding onto it like it's yours forever. and do NOT pass that returned pointer to free(3). literally do not. it is not yours to free 💀

---

💀 ERRORS 💀

here's the whole roster of ways things can go sideways:

• EAGAIN — the service was temporarily unavailable; try again later. for NSS backends in glibc this means there was a temporary error talking to the backend. it might fix itself, so retrying later is suggested 🫠
• EINTR — a signal was caught; go see signal(7) ✋
• EIO — I/O error 😵
• EMFILE — the per-process limit on the number of open file descriptors has been reached 🚫
• ENFILE — the system-wide limit on the total number of open files has been reached 🌊
• ENOENT — a necessary input file cannot be found. for NSS backends in glibc this means the backend is not correctly configured 🔍
• ENOMEM — insufficient memory to allocate group structure 😭
• ERANGE — insufficient buffer space supplied 📏

---

📁 FILES 📁

• /etc/group — the local group database file 🗂️

---

💅 ATTRIBUTES 💅

for what all these terms even mean, check attributes(7) — it's the glossary, bestie.

(the original is a whole table, so here it is as a list, same facts, cuter packaging 🎀)

• getgrent() — Thread safety: <hotpink>MT-Unsafe race:grent race:grentbuf locale</hotpink>
• setgrent(), endgrent() — Thread safety: <hotpink>MT-Unsafe race:grent locale</hotpink>

and about that grent in race:grent: it means that if any of setgrent(), getgrent(), or endgrent() get used in parallel across different threads of your program, then data races could occur. so like… threads + grent = chaos 🌀

---

🌈 STANDARDS 🌈

POSIX.1-2008. we stan a standard 👑

---

📜 HISTORY 📜

POSIX.1-2001, SVr4, 4.3BSD — she's been around a minute, an absolute icon 🌟

---

🔥 SEE ALSO 🔥

fgetgrent(3), getgrent_r(3), getgrgid(3), getgrnam(3), getgrouplist(3), putgrent(3), group(5)

---

and that's the whole page, bestie!! this one's from Linux man-pages 6.20, dated 2026-02-08 — go forth and read your group database responsibly 💖✨🦋