# getgrgid

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## 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.
    
           Applications wishing to check for error situations should set
           _errno_ to 0 before calling _getgrgid_().  If _getgrgid_() returns a
           null pointer and _errno_ is set to non-zero, an error occurred.
    
           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. If the requested entry was not found, _errno_ shall not be
           changed. On error, _errno_ shall be set to indicate the error.
    
           The application shall not modify the structure to which the return
           value points, nor any storage areas pointed to by pointers within
           the structure. The returned pointer, and pointers within the
           structure, might be invalidated or the structure or the storage
           areas might be overwritten by a subsequent call to _getgrent_(),
           _getgrgid_(), or _getgrnam_().  The returned pointer, and pointers
           within the structure, might also be invalidated if the calling
           thread is terminated.
    
           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



           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.
    


* * *