getgrnam(3)

✨ getgrnam(3) — get group file entry ✨

ok so bestie, this one's from the Library Functions Manual and it's about looking up group entries. It's lowkey one of the most useful things in libc and you're gonna slay it. 💖

🌈 LIBRARY

Standard C library (libc, -lc) — iconic, we stan.

🎀 SYNOPSIS

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

struct group *getgrnam(const char *name);
struct group *getgrgid(gid_t gid);

int getgrnam_r(size_t size;
               const char *restrict name, struct group *restrict grp,
               char buf[restrict size], size_t size,
               struct group **restrict result);
int getgrgid_r(size_t size;
               gid_t gid, struct group *restrict grp,
               char buf[restrict size], size_t size,
               struct group **restrict result);

🦋 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

• getgrnam_r(), getgrgid_r():
  • _POSIX_C_SOURCE
    • || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

(no cap, you gotta define those macros or glibc will simply not let you see these girls 😤)

---

💅 DESCRIPTION

okay so, getgrnam() — it returns a pointer to a structure holding the broken-out fields of the record in the group database that matches the group name name. And bestie, "the group database" is not just one thing: it's like, the local group file /etc/group, but also NIS, and LDAP. She's versatile. 👑

getgrgid() does the exact same thing but you look up by the group ID gid instead of by name. Same broken-out fields, same energy. ✨

The group structure is defined in <grp.h> and she looks like this:

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 */
};

(for the full tea on what all those fields mean, go read group(5) 🫶)

Now — getgrnam_r() and getgrgid_r() are the reentrant girlies. They get you the exact same info as getgrnam() and getgrgid(), but instead of handing you a static thing they store the retrieved group structure in the space pointed to by grp. The string fields that the members of the group structure point at get stashed in the buffer buf of size size. And a pointer to the result gets written to *result — that's the actual struct on success, or NULL when there's no entry found or a lil error happened. 💀

And this call right here:

sysconf(_SC_GETGR_R_SIZE_MAX)

returns either -1, and she does that without changing errno (periodt, she's polite), or it gives you an initial suggested size for buf. And if that size turns out too small? The call fails with ERANGE, and in that case you just retry with a bigger buffer. growth mindset fr fr. 🌱

---

🔥 RETURN VALUE

getgrnam() and getgrgid() hand you back a pointer to a group structure, or NULL if the matching entry isn't found or an error goes down. If there's an error, errno gets set to say which one. And here's the trick bestie: if you wanna check errno after the call, you gotta set it to zero before the call. Otherwise you're just reading stale vibes. 🙈

Also, the return value may point into a static area, and it can get overwritten by later calls to getgrent(3), getgrgid(), or getgrnam(). So heads up:

⚠️ Do not pass that returned pointer to free(3). Not even once. She is not yours to free, bestie, she lives in static-land and she stays there. 💀

For the _r versions: on success, getgrnam_r() and getgrgid_r() return zero and set *result to grp. If no matching group record was found, they return 0 and store NULL in *result (yes, zero AND null, that's the bit, don't @ me). And if there's an error, they return an error number and store NULL in *result. Clean, consistent, queen behavior. 👑

---

🌸 ERRORS

• 0 or ENOENT or ESRCH or EBADF or EPERM or ... — the given name or gid was not found. (yeah she's messy like that, whole buffet of possible values)
• EINTR — a signal got caught; see signal(7).
• EIO — I/O error. hardware said "not today".
• EMFILE — the per-process limit on the number of open file descriptors has been reached. too many files open, bestie, close some tabs 😭
• ENFILE — the system-wide limit on the total number of open files has been reached. not just you, the whole system is struggling.
• ENOMEM — not enough memory to allocate the group structure. she needed a bigger plate. 🍓
• ERANGE — insufficient buffer space supplied. your buf was too smol.

---

🧚 FILES

• /etc/group — the local group database file. the OG. the source. 💖

---

👑 ATTRIBUTES

for what all these terms even mean, peep attributes(7). here's the breakdown:

• getgrnam() — Thread safety: MT-Unsafe race:grnam locale
• getgrgid() — Thread safety: MT-Unsafe race:grgid locale
• getgrnam_r(), getgrgid_r() — Thread safety: MT-Safe locale

so like. the non-_r ones are racing, and the _r ones are safe. that's literally the whole point of existing, bestie. 🏁

---

⭐ VERSIONS

the formulation given above under "RETURN VALUE" is from POSIX.1. And here's the drama: it does not call "not found" an error, hence it does not specify what value errno might have in that situation. But that makes it impossible to recognize errors. Some might argue that according to POSIX, errno should be left unchanged if an entry is not found. But experiments on various UNIX-like systems show that lots of different values occur in this situation:

0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others.

(and probably others. iconic chaos. nobody's checking. 💅)

---

💜 STANDARDS

POSIX.1-2008

---

🦋 HISTORY

POSIX.1-2001, SVr4, 4.3BSD — she's been around, she's got lore, respect the elders.

---

🌈 SEE ALSO

endgrent(3), fgetgrent(3), getgrent(3), getpwnam(3), setgrent(3), group(5)

---

okay that's the whole page, you're officially a group-database girlie now 🫶 and just so you know, this was pulled from Linux man-pages 6.20 and the page itself is dated 2026-02-08 — so yeah, go forth and getgrnam() responsibly, bestie. mwah 💖✨