<<< Previous | Home | Next >>>

The Open Group Base Specifications Issue 7
IEEE Std 1003.1-2008
Copyright © 2001-2008 The IEEE and The Open Group

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

The following sections are informative.

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

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2008 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]

<<< Previous | Home | Next >>>