GETGRNAM(3C) Standard C Library Functions GETGRNAM(3C)
getgrnam, getgrnam_r, getgrent, getgrent_r, getgrgid, getgrgid_r,
setgrent, endgrent, fgetgrent, fgetgrent_r - group database entry
functions
#include <grp.h>
struct group *
getgrnam(const char *name);
struct group *
getgrnam_r(const char *name, struct group *grp, char *buffer,
int bufsize);
struct group *
getgrent(void);
struct group *
getgrent_r(struct group *grp, char *buffer, int bufsize);
struct group *
getgrgid(gid_t gid);
struct group *
getgrgid_r(gid_t gid, struct group *grp, char *buffer, int bufsize);
void
setgrent(void);
void
endgrent(void);
struct group *
fgetgrent(FILE *f);
struct group *
fgetgrent_r(FILE *f, struct group *grp, char *buffer, int bufsize);
#define _POSIX_PTHREAD_SEMANTICS
int
getgrnam_r(const char *name, struct group *grp, char *buffer,
size_t bufsize, struct group **result);
int
getgrgid_r(gid_t gid, struct group *grp, char *buffer, size_t bufsize,
struct group **result);
These functions are used to obtain entries describing user groups.
Entries can come from any of the sources for group specified via
nsswitch.conf(5).
getgrnam() searches the group database for an entry with the group name
specified by the character string parameter name.
getgrgid() searches the group database for an entry with the numeric
group id specified by gid.
setgrent(), getgrent(), and endgrent() are used to enumerate group
entries from the database.
setgrent() effectively rewinds the group database to allow repeated
searches. It sets or resets the enumeration to the beginning of the
set of group entries. This function should be called before the first
call to getgrent().
getgrent() returns a pointer to a structure containing the broken-out
fields of an entry in the group database. When first called,
getgrent() returns a pointer to a group structure containing the next
group structure in the group database. Successive calls can be used to
search the entire database.
endgrent() can be called to close the group database and deallocate
resources when processing is complete. It is permissible, though
possibly less efficient, for the process to call more group functions
after calling endgrent().
fgetgrent(), unlike the other functions above, does not use
nsswitch.conf(5). It reads and parses the next line from the stream f,
which is assumed to have the format of the group(5) file.
getgrnam(), getgrgid(), getgrent(), and fgetgrent() use thread-specific
storage that is reused in each call to one of these functions by the
same thread, making them safe to use but not recommended for
multithreaded applications.
The parallel functions getgrnam_r(), getgrgid_r(), getgrent_r(), and
fgetgrent_r() provide reentrant interfaces for these operations.
Each reentrant interface performs the same operation as its non-
reentrant counterpart, named by removing the `_r' suffix. The
reentrant interfaces, however, use buffers supplied by the caller to
store returned results instead of using thread-specific data that can
be overwritten by each call. They are safe for use in both single-
threaded and multithreaded applications.
Each reentrant interface takes the same arguments as its non-reentrant
counterpart, as well as the following additional parameters. The grp
argument must be a pointer to a struct group structure allocated by the
caller. On successful completion, the function returns the group entry
in this structure. Storage referenced by the group structure is
allocated from the memory provided with the buffer argument that is
bufsize characters in size. The maximum size needed for this buffer
can be determined with the _SC_GETGR_R_SIZE_MAX sysconf(3C) parameter.
The standard-conforming versions place a pointer to the modified grp
structure in the result parameter, instead of returning a pointer to
this structure. A null pointer is returned at the location pointed to
by result on error or if the requested entry is not found.
For enumeration in multithreaded applications, the position within the
enumeration is a process-wide property shared by all threads.
setgrent() can be used in a multithreaded application but resets the
enumeration position for all threads. If multiple threads interleave
calls to getgrent_r(), the threads will enumerate disjoint subsets of
the group database. Like their non-reentrant counterparts,
getgrnam_r() and getgrgid_r() leave the enumeration position in an
indeterminate state.
group Structure
Group entries are represented by the struct group structure defined in
<grp.h>
struct group {
char *gr_name; /* the name of the group */
char *gr_passwd; /* the encrypted group password */
gid_t gr_gid; /* the numerical group ID */
char **gr_mem; /* vector of pointers to member names */
};
getgrnam(), getgrnam_r(), getgrgid(), and getgrgid_r() each return a
pointer to a struct group if they successfully locate the requested
entry. They return a null pointer if either the requested entry was
not found or an error occurred. On error, errno is set to indicate the
error.
The standard-conforming functions getgrnam_r() and getgrgid_r() return
0 on success (including when the requested entry is not found) or an
error number in case of failure. To distinguish between a successful
lookup and a not-found condition, the caller must check the pointer
stored at the location pointed to by result: it will be non-NULL if the
entry was found and NULL if it was not.
getgrent(), getgrent_r(), fgetgrent(), and fgetgrent_r() each return a
pointer to a struct group if they successfully enumerate an entry;
otherwise they return a null pointer on end-of-file or error. On
error, errno is set to indicate the error.
getgrnam(), getgrgid(), getgrent(), and fgetgrent() use thread-specific
data storage, so returned data must be copied before a subsequent call
to any of these functions if the data are to be saved.
When the pointer returned by the reentrant functions getgrnam_r(),
getgrgid_r(), getgrent_r(), and fgetgrent_r() is non-NULL, it is always
equal to the grp pointer that was supplied by the caller.
Applications wishing to check for error situations should set errno to
0 before calling getgrnam(), getgrnam_r(), getgrent(), getgrent_r(),
getgrgid(), getgrgid_r(), fgetgrent(), and fgetgrent_r(). If these
functions return a NULL pointer and errno is non-zero, an error
occurred.
getgrent_r(), fgetgrent(), and fgetgrent_r() will fail if:
EIO An I/O error has occurred.
ERANGE Insufficient storage was supplied by buffer and
bufsize to contain the data to be referenced by the
resulting group structure.
getgrent_r() will fail if:
EMFILE There are {OPEN_MAX} file descriptors currently open
in the calling process.
ENFILE The maximum allowable number of files is currently
open in the system.
getgrnam(), getgrnam_r(), getgrgid(), getgrgid_r(), and getgrent() may
fail if:
EINTR A signal was caught during the operation.
EIO An I/O error has occurred.
EMFILE There are {OPEN_MAX} file descriptors currently open
in the calling process.
ENFILE The maximum allowable number of files is currently
open in the system.
getgrnam_r() and getgrgid_r() may fail if:
ERANGE Insufficient storage was supplied by buffer and bufsize to
contain the data to be referenced by the resulting group
structure.
getgrnam, getgrnam_r, getgrent, getgrent_r, getgrgid, getgrgid_r,
setgrent, endgrent, fgetgrent and fgetgrent_r are Committed. See also
NOTES below.
MT-LEVEL
See Reentrant Interfaces in DESCRIPTION.
Intro(3), getpwnam(3C), group(5), nsswitch.conf(5), passwd(5),
attributes(7), standards(7)
When compiling multithreaded programs, see Intro(3).
Use of the enumeration interfaces getgrent() and getgrent_r() is
discouraged; enumeration is supported for the group file and NIS but in
general is not efficient and might not be supported for all database
sources. The semantics of enumeration are discussed further in
nsswitch.conf(5).
Previous releases allowed the use of `+' and `-' entries in /etc/group
to selectively include and exclude entries from NIS. The primary usage
of these entries is superseded by the name service switch, so the `+/-'
form might not be supported in future releases.
If required, the `+/-' functionality can still be obtained for NIS by
specifying compat as the source for group.
If the `+/-' functionality is required in conjunction with LDAP,
specify both compat as the source for group and ldap as the source for
the pseudo-database group_compat. See group(5), and nsswitch.conf(5)
for details.
Solaris 2.4 and earlier releases provided definitions of getgrnam_r()
and getgrgid_r() as specified in POSIX.1c Draft 6. The final POSIX.1c
standard changed the interface for these functions. Support for the
Draft 6 interface is provided for compatibility only and might not be
supported in future releases. New applications and libraries should
use the standard-conforming interface.
For POSIX.1c-conforming applications, the _POSIX_PTHREAD_SEMANTICS and
_REENTRANT flags are automatically turned on by defining the
_POSIX_C_SOURCE flag with a value >= 199506L.
illumos April 16, 2026 illumos
NAME
getgrnam, getgrnam_r, getgrent, getgrent_r, getgrgid, getgrgid_r,
setgrent, endgrent, fgetgrent, fgetgrent_r - group database entry
functions
SYNOPSIS
#include <grp.h>
struct group *
getgrnam(const char *name);
struct group *
getgrnam_r(const char *name, struct group *grp, char *buffer,
int bufsize);
struct group *
getgrent(void);
struct group *
getgrent_r(struct group *grp, char *buffer, int bufsize);
struct group *
getgrgid(gid_t gid);
struct group *
getgrgid_r(gid_t gid, struct group *grp, char *buffer, int bufsize);
void
setgrent(void);
void
endgrent(void);
struct group *
fgetgrent(FILE *f);
struct group *
fgetgrent_r(FILE *f, struct group *grp, char *buffer, int bufsize);
Standard conforming
#define _POSIX_PTHREAD_SEMANTICS
int
getgrnam_r(const char *name, struct group *grp, char *buffer,
size_t bufsize, struct group **result);
int
getgrgid_r(gid_t gid, struct group *grp, char *buffer, size_t bufsize,
struct group **result);
DESCRIPTION
These functions are used to obtain entries describing user groups.
Entries can come from any of the sources for group specified via
nsswitch.conf(5).
getgrnam() searches the group database for an entry with the group name
specified by the character string parameter name.
getgrgid() searches the group database for an entry with the numeric
group id specified by gid.
setgrent(), getgrent(), and endgrent() are used to enumerate group
entries from the database.
setgrent() effectively rewinds the group database to allow repeated
searches. It sets or resets the enumeration to the beginning of the
set of group entries. This function should be called before the first
call to getgrent().
getgrent() returns a pointer to a structure containing the broken-out
fields of an entry in the group database. When first called,
getgrent() returns a pointer to a group structure containing the next
group structure in the group database. Successive calls can be used to
search the entire database.
endgrent() can be called to close the group database and deallocate
resources when processing is complete. It is permissible, though
possibly less efficient, for the process to call more group functions
after calling endgrent().
fgetgrent(), unlike the other functions above, does not use
nsswitch.conf(5). It reads and parses the next line from the stream f,
which is assumed to have the format of the group(5) file.
Reentrant Interfaces
getgrnam(), getgrgid(), getgrent(), and fgetgrent() use thread-specific
storage that is reused in each call to one of these functions by the
same thread, making them safe to use but not recommended for
multithreaded applications.
The parallel functions getgrnam_r(), getgrgid_r(), getgrent_r(), and
fgetgrent_r() provide reentrant interfaces for these operations.
Each reentrant interface performs the same operation as its non-
reentrant counterpart, named by removing the `_r' suffix. The
reentrant interfaces, however, use buffers supplied by the caller to
store returned results instead of using thread-specific data that can
be overwritten by each call. They are safe for use in both single-
threaded and multithreaded applications.
Each reentrant interface takes the same arguments as its non-reentrant
counterpart, as well as the following additional parameters. The grp
argument must be a pointer to a struct group structure allocated by the
caller. On successful completion, the function returns the group entry
in this structure. Storage referenced by the group structure is
allocated from the memory provided with the buffer argument that is
bufsize characters in size. The maximum size needed for this buffer
can be determined with the _SC_GETGR_R_SIZE_MAX sysconf(3C) parameter.
The standard-conforming versions place a pointer to the modified grp
structure in the result parameter, instead of returning a pointer to
this structure. A null pointer is returned at the location pointed to
by result on error or if the requested entry is not found.
For enumeration in multithreaded applications, the position within the
enumeration is a process-wide property shared by all threads.
setgrent() can be used in a multithreaded application but resets the
enumeration position for all threads. If multiple threads interleave
calls to getgrent_r(), the threads will enumerate disjoint subsets of
the group database. Like their non-reentrant counterparts,
getgrnam_r() and getgrgid_r() leave the enumeration position in an
indeterminate state.
group Structure
Group entries are represented by the struct group structure defined in
<grp.h>
struct group {
char *gr_name; /* the name of the group */
char *gr_passwd; /* the encrypted group password */
gid_t gr_gid; /* the numerical group ID */
char **gr_mem; /* vector of pointers to member names */
};
RETURN VALUES
getgrnam(), getgrnam_r(), getgrgid(), and getgrgid_r() each return a
pointer to a struct group if they successfully locate the requested
entry. They return a null pointer if either the requested entry was
not found or an error occurred. On error, errno is set to indicate the
error.
The standard-conforming functions getgrnam_r() and getgrgid_r() return
0 on success (including when the requested entry is not found) or an
error number in case of failure. To distinguish between a successful
lookup and a not-found condition, the caller must check the pointer
stored at the location pointed to by result: it will be non-NULL if the
entry was found and NULL if it was not.
getgrent(), getgrent_r(), fgetgrent(), and fgetgrent_r() each return a
pointer to a struct group if they successfully enumerate an entry;
otherwise they return a null pointer on end-of-file or error. On
error, errno is set to indicate the error.
getgrnam(), getgrgid(), getgrent(), and fgetgrent() use thread-specific
data storage, so returned data must be copied before a subsequent call
to any of these functions if the data are to be saved.
When the pointer returned by the reentrant functions getgrnam_r(),
getgrgid_r(), getgrent_r(), and fgetgrent_r() is non-NULL, it is always
equal to the grp pointer that was supplied by the caller.
Applications wishing to check for error situations should set errno to
0 before calling getgrnam(), getgrnam_r(), getgrent(), getgrent_r(),
getgrgid(), getgrgid_r(), fgetgrent(), and fgetgrent_r(). If these
functions return a NULL pointer and errno is non-zero, an error
occurred.
ERRORS
getgrent_r(), fgetgrent(), and fgetgrent_r() will fail if:
EIO An I/O error has occurred.
ERANGE Insufficient storage was supplied by buffer and
bufsize to contain the data to be referenced by the
resulting group structure.
getgrent_r() will fail if:
EMFILE There are {OPEN_MAX} file descriptors currently open
in the calling process.
ENFILE The maximum allowable number of files is currently
open in the system.
getgrnam(), getgrnam_r(), getgrgid(), getgrgid_r(), and getgrent() may
fail if:
EINTR A signal was caught during the operation.
EIO An I/O error has occurred.
EMFILE There are {OPEN_MAX} file descriptors currently open
in the calling process.
ENFILE The maximum allowable number of files is currently
open in the system.
getgrnam_r() and getgrgid_r() may fail if:
ERANGE Insufficient storage was supplied by buffer and bufsize to
contain the data to be referenced by the resulting group
structure.
INTERFACE STABILITY
getgrnam, getgrnam_r, getgrent, getgrent_r, getgrgid, getgrgid_r,
setgrent, endgrent, fgetgrent and fgetgrent_r are Committed. See also
NOTES below.
MT-LEVEL
See Reentrant Interfaces in DESCRIPTION.
SEE ALSO
Intro(3), getpwnam(3C), group(5), nsswitch.conf(5), passwd(5),
attributes(7), standards(7)
NOTES
When compiling multithreaded programs, see Intro(3).
Use of the enumeration interfaces getgrent() and getgrent_r() is
discouraged; enumeration is supported for the group file and NIS but in
general is not efficient and might not be supported for all database
sources. The semantics of enumeration are discussed further in
nsswitch.conf(5).
Previous releases allowed the use of `+' and `-' entries in /etc/group
to selectively include and exclude entries from NIS. The primary usage
of these entries is superseded by the name service switch, so the `+/-'
form might not be supported in future releases.
If required, the `+/-' functionality can still be obtained for NIS by
specifying compat as the source for group.
If the `+/-' functionality is required in conjunction with LDAP,
specify both compat as the source for group and ldap as the source for
the pseudo-database group_compat. See group(5), and nsswitch.conf(5)
for details.
Solaris 2.4 and earlier releases provided definitions of getgrnam_r()
and getgrgid_r() as specified in POSIX.1c Draft 6. The final POSIX.1c
standard changed the interface for these functions. Support for the
Draft 6 interface is provided for compatibility only and might not be
supported in future releases. New applications and libraries should
use the standard-conforming interface.
For POSIX.1c-conforming applications, the _POSIX_PTHREAD_SEMANTICS and
_REENTRANT flags are automatically turned on by defining the
_POSIX_C_SOURCE flag with a value >= 199506L.
illumos April 16, 2026 illumos