NAME

getgrgid, getgrgid_r - get group database entry for a group ID

SYNOPSIS

#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);


DESCRIPTION

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 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 gid. Storage referenced by the group structure is allocated from the memory provided with the buffer 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.

RETURN VALUE

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(), getgrgid(), or getgrnam().

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

ERRORS

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

[EIO]

An I/O error has occurred.

[EINTR]

A signal was caught during getgrgid().

[EMFILE]

All file descriptors available to the process are currently open.

[ENFILE]

The maximum allowable number of files is currently open in the system.

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

EXAMPLES

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().

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);

Finding an Entry in the Group Database

The following example uses getgrgid() to search the group database for a group ID that was previously stored in a stat 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);
...

APPLICATION USAGE

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() indicating that there is no maximum for _SC_GETGR_R_SIZE_MAX.

RATIONALE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

endgrent , getgrnam , sysconf

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

CHANGE HISTORY

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

Issue 5

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.

Issue 6

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.

Issue 7

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().