fgetgrent_r(3C)
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);
POSIX
cc [ flag... ] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]
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 in the /etc/nsswitch.conf file (see
nsswitch.conf(4)).
The getgrnam() function searches the group database for an
entry with the group name specified by the character string
parameter name.
The getgrgid() function searches the group database for an
entry with the (numeric) group id specified by gid.
The setgrent(), getgrent(), and endgrent() functions are
used to enumerate group entries from the database.
The setgrent() function effectively rewinds the group data-
base 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 get-
grent().
The getgrent() function 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 may be used to search
the entire database.
The endgrent() function may be called to close the group
database and deallocate resources when processing is com-
plete. It is permissible, though possibly less efficient,
for the process to call more group functions after calling
endgrent().
The fgetgrent() function, unlike the other functions above,
does not use nsswitch.conf. It reads and parses the next
line from the stream f, which is assumed to have the format
of the group file (see group(4)).
Reentrant Interfaces
The getgrnam(), getgrgid(), getgrent(), and fgetgrent()
functions use static storage that is reused in each call,
making them unsafe 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, and 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 addi-
tional parameters. The grp argument must be a pointer to a
struct group structure allocated by the caller. On success-
ful 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,
which 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 POSIX ver-
sions place a pointer to the modified grp structure in the
result parameter, instead of returning a pointer to this
structure.
For enumeration in multithreaded applications, the position
within the enumeration is a process-wide property shared by
all threads. setgrent() may 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.
RETURN VALUES
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 */
};
The getgrnam(), getgrnam_r(), getgrgid(), and getgrgid_r()
functions each return a pointer to a struct group if they
successfully locate the requested entry; otherwise they
return NULL. The POSIX functions getgrnam_r() and
getgrgid_r() return 0 upon success or the error number in
case of failure.
The getgrent(), getgrent_r(), fgetgrent(), and
fgetgrent_r() functions each return a pointer to a struct
group if they successfully enumerate an entry; otherwise
they return NULL, indicating the end of the enumeration.
The getgrnam(), getgrgid(), getgrent(), and fgetgrent()
functions use static storage, so returned data must be
copied before a subsequent call to any of these functions if
the data is 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.
ERRORS
The getgrnam(), getgrgid(), getgrent(), fgetgrent(), and
fgetgrent_r() functions 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.
ERANGE
The group file contains a line that exceeds 512 bytes.
The getgrnam_r(), getgrgid_r(), and getgrent_r() functions
may fail if:
ERANGE
Insufficient storage was supplied by buffer and buf-
size to contain the data to be referenced by the
resulting group structure.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| ____________________________|_____________________________|_
| MT-Level | See "Reentrant Interfaces"|
| | in DESCRIPTION. |
|_____________________________|_____________________________|
SEE ALSO
Intro(3), getpwnam(3C), group(4), nsswitch.conf(4),
passwd(4), attributes(5), standards(5)
NOTES
When compiling multithreaded programs, see Intro(3), Notes
On Multithreaded Applications.
Programs that use the interfaces described in this manual
page cannot be linked statically since the implementations
of these functions employ dynamic loading and linking of
shared objects at run time.
Use of the enumeration interfaces getgrent() and
getgrent_r() is discouraged; enumeration is supported for
the group file, NIS, and NIS+, but in general is not effi-
cient and may not be supported for all database sources.
The semantics of enumeration are discussed further in
nsswitch.conf(4).
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 may 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
NIS+, specify both compat as the source for group and
nisplus as the source for the pseudo-database group_compat.
See group(4), and nsswitch.conf(4) for details.
Solaris 2.4 and earlier releases provided definitions of the
getgrnam_r() and getgrgid_r() functions 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 may not be
supported in future releases. New applications and libraries
should use the POSIX standard interface.
For POSIX.1c-compliant applications, the
_POSIX_PTHREAD_SEMANTICS and _REENTRANT flags are automati-
cally turned on by defining the _POSIX_C_SOURCE flag with a
value >= 199506L.
Man(1) output converted with
man2html