GETGRGID(3) Library Functions Manual GETGRGID(3)

getgrgid getgrgid_r — get group database entry for a group ID

#include <grp.h>

struct group *getgrgid(gid_t gid);
int getgrgid_r(gid_t gid, struct group *grp, char *buffer,
       size_t bufsize, struct group **result);

The getgrgid () function shall search the group database for an entry with a matching gid.

The getgrgid () function need not be thread-safe.

The getgrgid_r () function shall update the structure pointed to by 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 gid. Storage referenced by the group structure is allocated from the memory provided with the parameter, which is bufsize bytes in size. 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. A null pointer shall be returned at the location pointed to by result on error or if the requested entry is not found.

Upon successful completion, getgrgid () shall return a pointer to a struct group with the structure defined in <grp.h> with a matching entry if one is found. The getgrgid () function shall return a null pointer if either the requested entry was not found, or an error occurred. On error, errno shall be set to indicate the error.

The return value may point to a static area which is overwritten by a subsequent call to getgrent(3), getgrgid (), or getgrnam(3).

If successful, the getgrgid_r () function shall return zero; otherwise, an error number shall be returned to indicate the error.

The getgrgid () and getgrgid_r () functions may fail if:

An I/O error has occurred.
A signal was caught during getgrgid ().
All file descriptors available to the process are currently open.
The maximum allowable number of files is currently open in the system.

The getgrgid_r () function may fail if:

Insufficient storage was supplied via buffer and bufsize to contain the data to be referenced by the resulting group structure.

Note that sysconf (_SC_GETGR_R_SIZE_MAX) may return -1 if there is 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 getgrid_r(3).

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 = getgrgid_r(42, &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);

The following example uses getgrgid () to search the group database for a group ID that was previously stored in a structure, then prints out the group name if it is found. If the group is not found, the program prints the numeric value of the group for the entry.

#include <sys/types.h>
#include <grp.h>
#include <stdio.h>
...
struct stat statbuf;
struct group *grp;
...
if ((grp = getgrgid(statbuf.st_gid)) != NULL)
    printf(" %-8.8s", grp->gr_name);
else
    printf(" %-8d", statbuf.st_gid);
...

Applications wishing to check for error situations should set errno to 0 before calling getgrgid (). If errno is set on return, an error occurred.

The getgrgid_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.

Portable applications should take into account that it is usual for an implementation to return -1 from sysconf(3) indicating that there is no maximum for _SC_GETGR_R_SIZE_MAX.

None.

None.

endgrent(3) , getgrnam(3) , sysconf(3)

XBD <grp.h> , <sys/types.h>

First released in Issue 1. Derived from System V Release 2.0.

Normative text previously in the APPLICATION USAGE section is moved to the RETURN VALUE section.

The getgrgid_r () function is included for alignment with the POSIX Threads Extension.

A note indicating that the getgrgid () function need not be reentrant is added to the DESCRIPTION.

The getgrgid_r () function is marked as part of the Thread-Safe Functions option.

The Open Group Corrigendum U028/3 is applied, correcting text in the DESCRIPTION describing matching the gid.

In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety.

In the SYNOPSIS, the optional include of the <sys/types.h> header is removed.

The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:

  • The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was required for conforming implementations of previous POSIX specifications, it was not required for UNIX applications.
  • In the RETURN VALUE section, the requirement to set errno on error is added.
  • The [EIO], [EINTR], [EMFILE], and [ENFILE] optional error conditions are added.

The APPLICATION USAGE section is updated to include a note on the thread-safe function and its avoidance of possibly using a static data area.

IEEE PASC Interpretation 1003.1 #116 is applied, changing the description of the size of the buffer from bufsize characters to bytes.

Austin Group Interpretation 1003.1-2001 #156 is applied.

SD5-XBD-ERN-4 is applied, changing the definition of the [EMFILE] error.

SD5-XSH-ERN-166 is applied.

The getgrgid_r () function is moved from the Thread-Safe Functions option to the Base.

A minor addition is made to the EXAMPLES section, reminding the application developer to free memory allocated as if by malloc(3).

January 1, 2008 posix.fail