GETGRNAM(3P)

💖 GETGRNAM(3P) — the POSIX Programmer's Manual glow-up 💖

okay bestie, before we even start — this page is literally part of the POSIX Programmer's Manual. that means the Linux version of this interface might lowkey behave differently (so go peek at the matching Linux man page for the tea ☕), or it might just... not be implemented on Linux at all. no cap. 🙈

---

✨ NAME ✨

getgrnam, getgrnam_r — searching the group database for a name, babes 🔍

---

🌸 SYNOPSIS 🌸

#include <grp.h>

struct group *getgrnam(const char *name);
int getgrnam_r(const char *name, struct group *grp, char *buffer,
    size_t bufsize, struct group **result);

---

🦋 DESCRIPTION 🦋

so getgrnam() shall search the group database for an entry with a matching name. that's the whole mission. slay. 💅

⚠️ real talk: getgrnam() need not be thread-safe. it's giving "one person at a time, bestie".

if you're an application that wants to actually check for error situations, set errno to 0 before calling getgrnam(). then if getgrnam() returns a null pointer and errno is set to non-zero — yeah, an error happened. that's your sign. 🚨

now getgrnam_r() — the responsible sibling — shall update the group structure pointed to by grp and store a pointer to that structure at the location pointed to by result. the structure shall contain an entry from the group database with a matching name. the storage that the group structure references is allocated from the memory you hand over with the buffer parameter, which is bufsize bytes in size. and get this: a call to sysconf(_SC_GETGR_R_SIZE_MAX) returns either -1 without changing errno, or an initial value suggested for the size of this buffer. if there's an error, or the entry you asked for just isn't there, a null pointer gets returned at the location pointed to by result. 😭

---

👑 RETURN VALUE 👑

getgrnam() shall return a pointer to a struct group — with the structure defined in <grp.h> — with a matching entry, if one is found. if the requested entry wasn't found, or an error occurred, it shall return a null pointer. important distinction, so listen up: if the entry simply wasn't found, errno shall not be changed. but on error, errno shall be set to indicate the error. periodt. 💯

🙅‍♀️ do NOT modify the structure that the return value points to, and don't touch any storage areas pointed to by pointers inside that structure either. the returned pointer, and the pointers within the structure, might get invalidated — or the structure or those storage areas might get straight up overwritten — by a subsequent call to getgrent(), getgrgid(), or getgrnam(). also? the returned pointer and the pointers within the structure might get invalidated if the calling thread is terminated. it's giving fragile, handle with care. 🎀

getgrnam_r() shall return zero on success, or if the requested entry wasn't found and no error occurred. if any error happened, an error number shall be returned to indicate the error. simple. iconic. ✨

---

💀 ERRORS 💀

the getgrnam() and getgrnam_r() functions may fail if:

• EIO — an I/O error has occurred. 😵
• EINTR — a signal was caught during getgrnam().
• EMFILE — all file descriptors available to the process are currently open. every single one. no room.
• ENFILE — the maximum allowable number of files is currently open in the system.

and the getgrnam_r() function may fail if:

• ERANGE — insufficient storage was supplied via buffer and bufsize to contain the data to be referenced by the resulting group structure. your buffer was too smol, bestie. grow it. 🍓

psst — the following sections are informative.

---

🌈 EXAMPLES 🌈

heads up: sysconf(_SC_GETGR_R_SIZE_MAX) may return -1 if there's no hard limit on the size of the buffer needed to store all the groups returned. this example shows how an application can allocate a buffer of sufficient size to work with getgrnam_r(). it's the loop-to-victory arc, we love to see it 💪

long int initlen = sysconf(_SC_GETGR_R_SIZE_MAX);
size_t len;
if (initlen == -1)
    /* Default initial length. */
    len = 1024;
else
    len = (size_t) initlen;
struct group result;
struct group *resultp;
char *buffer = malloc(len);
if (buffer == NULL)
    ...handle error...
int e;
while ((e = getgrnam_r("somegroup", &result, buffer, len, &resultp))
        == ERANGE)
    {
    size_t newlen = 2 * len;
    if (newlen < len)
        ...handle error...
    len = newlen;
    char *newbuffer = realloc(buffer, len);
    if (newbuffer == NULL)
        ...handle error...
    buffer = newbuffer;
    }
if (e != 0)
    ...handle error...
free (buffer);

---

🫶 APPLICATION USAGE 🫶

the getgrnam_r() function is thread-safe and shall return values in a user-supplied buffer instead of possibly using a static data area that may be overwritten by each call. that's the whole point of the _r. main character energy, honestly. 👑

portable applications should take into account that it's usual for an implementation to return -1 from sysconf(), indicating that there is no maximum for _SC_GETGR_R_SIZE_MAX. so don't panic when you see that -1. 🧚

---

⭐ RATIONALE ⭐

None.

(yeah. that's it. nothing. moving on. 😭)

---

🎀 FUTURE DIRECTIONS 🎀

None.

(also nothing. we love a chill future. 💜)

---

🔥 SEE ALSO 🔥

• endgrent()
• getgrgid()
• sysconf()

and from the Base Definitions volume of POSIX.1‐2017: <grp.h>, <sys_types.h>

---

📜 COPYRIGHT 📜

portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. in the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. the original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. to report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

okay that's the whole page, bestie!! this one's brought to you by IEEE/The Open Group, dated 2017, and it's page GETGRNAM(3P) 🫶✨ go forth and look up your groups, you got this 💖🌸🦋