---
name: "getgrgid_r"
section: "3"
platform: "linux"
package: "man-pages"
version: "6.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/getgrnam"
---

# getgrgid\_r(3)

get group file entry

Part of [getgrnam(3)](/getgrnam/3.md).

## NAME

getgrnam, getgrnam\_r, getgrgid, getgrgid\_r - get group file entry

## LIBRARY

Standard C library (*libc*, *-lc*)

## 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)](/feature_test_macros/7.md)):

**getgrnam\_r**(), **getgrgid\_r**():

```
    _POSIX_C_SOURCE
        || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
```

## DESCRIPTION

The **getgrnam**() function returns a pointer to a structure containing the broken-out fields of the record in the group database (e.g., the local group file */etc/group*, NIS, and LDAP) that matches the group name *name*.

The **getgrgid**() function returns a pointer to a structure containing the broken-out fields of the record in the group database that matches the group ID *gid*.

The *group* structure is defined in *\<grp.h\>* as follows:

```
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 more information about the fields of this structure, see [**group**(5)](/group/5.md).

The **getgrnam\_r**() and **getgrgid\_r**() functions obtain the same information as **getgrnam**() and **getgrgid**(), but store the retrieved *group* structure in the space pointed to by *grp*. The string fields pointed to by the members of the *group* structure are stored in the buffer *buf* of size *size*. A pointer to the result (in case of success) or NULL (in case no entry was found or an error occurred) is stored in *\*result*.

The call

```
sysconf(_SC_GETGR_R_SIZE_MAX)
```

returns either -1, without changing *errno*, or an initial suggested size for *buf*. (If this size is too small, the call fails with **ERANGE**, in which case the caller can retry with a larger buffer.)

## RETURN VALUE

The **getgrnam**() and **getgrgid**() functions return a pointer to a *group* structure, or NULL if the matching entry is not found or an error occurs. If an error occurs, *errno* is set to indicate the error. If one wants to check *errno* after the call, it should be set to zero before the call.

The return value may point to a static area, and may be overwritten by subsequent calls to [**getgrent**(3)](/getgrent/3.md), **getgrgid**(), or **getgrnam**(). (Do not pass the returned pointer to [**free**(3)](/free/3.md).)

On success, **getgrnam\_r**() and **getgrgid\_r**() return zero, and set *\*result* to *grp*. If no matching group record was found, these functions return 0 and store NULL in *\*result*. In case of error, an error number is returned, and NULL is stored in *\*result*.

## ERRORS

- **0** or **ENOENT** or **ESRCH** or **EBADF** or **EPERM** or ...

  The given *name* or *gid* was not found.

- **EINTR**

  A signal was caught; see [**signal**(7)](/signal/7.md).

- **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.

- **ENOMEM**

  Insufficient memory to allocate *group* structure.

- **ERANGE**

  Insufficient buffer space supplied.

## FILES

- */etc/group*

  local group database file

## ATTRIBUTES

For an explanation of the terms used in this section, see [**attributes**(7)](/attributes/7.md).

| | | |
| --- | --- | --- |
| **Interface** | **Attribute** | **Value** |
| **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 |

## VERSIONS

The formulation given above under "RETURN VALUE" is from POSIX.1. It does not call "not found" an error, hence does not specify what value *errno* might have in this situation. But that makes it impossible to recognize errors. One might argue that according to POSIX *errno* should be left unchanged if an entry is not found. 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.

## STANDARDS

POSIX.1-2008.

## HISTORY

POSIX.1-2001, SVr4, 4.3BSD.

## SEE ALSO

[**endgrent**(3)](/endgrent/3.md), [**fgetgrent**(3)](/fgetgrent/3.md), [**getgrent**(3)](/getgrent/3.md), [**getpwnam**(3)](/getpwnam/3.md), [**setgrent**(3)](/setgrent/3.md), [**group**(5)](/group/5.md)