# getgrnam

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



           getgrnam, getgrnam_r — search group database for a name
    


## SYNOPSIS



           #include <grp.h>
    
           struct group *getgrnam(const char *_name_);
           int getgrnam_r(const char *_name_ , struct group *_grp_ , char *_buffer_ ,
               size_t _bufsize_ , struct group **_result_);
    


## DESCRIPTION



           The _getgrnam_() function shall search the group database for an
           entry with a matching _name_.
    
           The _getgrnam_() function need not be thread-safe.
    
           Applications wishing to check for error situations should set
           _errno_ to 0 before calling _getgrnam_().  If _getgrnam_() returns a
           null pointer and _errno_ is set to non-zero, an error occurred.
    
           The _getgrnam_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 _name_.  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 is returned at the location pointed to by _result_ on
           error or if the requested entry is not found.
    


## RETURN VALUE



           The _getgrnam_() function shall return a pointer to a **struct group**
           with the structure defined in _< grp.h>_ with a matching entry if one
           is found. The _getgrnam_() 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.
    
           The _getgrnam_r_() function shall return zero on success or if the
           requested entry was not found and no error has occurred. If any
           error has occurred, an error number shall be returned to indicate
           the error.
    


## ERRORS



           The _getgrnam_() and _getgrnam_r_() functions may fail if:
    
           **EIO** An I/O error has occurred.
    
           **EINTR** A signal was caught during _getgrnam_().
    
           **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 _getgrnam_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 _getgrnam_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 = getgrnam_r("somegroup", &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);
    


## APPLICATION USAGE



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


* * *