The functions
getgrnam
and
getgrgid
search the group database for the given group name pointed to by
name
or the group id pointed to by
gid,
respectively, returning the first one encountered.
Identical group
names or group gids may result in undefined behavior.

The
getgrent
function
sequentially reads the group database and is intended for programs
that wish to step through the complete list of groups.

The functions
getgrent_r,
getgrnam_r,
and
getgrgid_r
are thread-safe versions of
getgrent,
getgrnam,
and
getgrgid,
respectively.
The caller must provide storage for the results of the search in
the
grp,
buffer,
bufsize,
and
result
arguments.
When these functions are successful, the
grp
argument will be filled-in, and a pointer to that argument will be
stored in
result.
If an entry is not found or an error occurs,
result
will be set to
NULL.

These functions will open the group file for reading, if necessary.

The
setgroupent
function
opens the file, or rewinds it if it is already open.
If
stayopen
is non-zero, file descriptors are left open, significantly speeding
functions subsequent calls.
This functionality is unnecessary for
getgrent
as it does not close its file descriptors by default.
It should also
be noted that it is dangerous for long-running programs to use this
functionality as the group file may be updated.

The
setgrent
function
is identical to
setgroupent
with an argument of zero.

The functions
getgrent,
getgrnam,
and
getgrgid,
return a pointer to a group structure on success or
NULL
if the entry is not found or if an error occurs.
If an error does occur,
errno
will be set.
Note that programs must explicitly set
errno
to zero before calling any of these functions if they need to
distinguish between a non-existent entry and an error.
The functions
getgrent_r,
getgrnam_r,
and
getgrgid_r
return 0 if no error occurred, or an error number to indicate failure.
It is not an error if a matching entry is not found.
(Thus, if
result
is set to
NULL
and the return value is 0, no matching entry exists.)

The functions
setgroupent
and
setgrent
return the value 1 if successful, otherwise the value
0 is returned.
The functions
endgrent
and
setgrfile
have no return value.

The
getgrent,
getgrnam,
getgrnam_r,
getgrgid,
getgrgid_r
and
endgrent
functions conform to
-p1003.1-96.
The
setgrent
function differs from that standard in that its return type is
.Vt int
rather than
.Vt void .

The functions
endgrent,
getgrent,
getgrnam,
getgrgid,
and
setgrent
appeared in
AT&T v7 .
The functions
setgrfile
and
setgroupent
appeared in
BSD 4.3 Reno .
The functions
getgrent_r,
getgrnam_r,
and
getgrgid_r
appeared in
.Fx 5.1 .

The functions
getgrent,
getgrnam,
getgrgid,
setgroupent
and
setgrent
leave their results in an internal static object and return
a pointer to that object.
Subsequent calls to
the same function
will modify the same object.

The functions
getgrent,
getgrent_r,
endgrent,
setgroupent,
and
setgrent
are fairly useless in a networked environment and should be
avoided, if possible.
The
getgrent
and
getgrent_r
functions
make no attempt to suppress duplicate information if multiple
sources are specified in
nsswitch.conf(5).