getgrent(3)getgrent(3)NAME
endgrent, fgetgrent, getgrent, getgrgid, getgrnam, setgrent, end‐
grent_r, fgetgrent_r, getgrent_r, getgrgid_r, getgrnam_r, setgrent_r -
Access group information in the user database
SYNOPSIS
#include <grp.h>
void endgrent(
void ); struct group *fgetgrent(
FILE *f ); struct group *getgrent(
void ); struct group *getgrgid(
gid_t *gid ); struct group *getgrnam(
const char *name ); void setgrent(
void ); void endgrent(
FILE **gr_fp ); void fgetgrent_r(
FILE *f,
stuct group *grp,
char *buffer,
int len ); void getgrent_r(
stuct group *grp,
char *buffer,
int len,
FILE **gr_fp ); int getgrgid_r(
gid_t *gid,
struct group *grp,
char *buffer,
siz_t len,
struct group **result ); int getgrname(
const char *name,
struct group *grp,
char *buffer,
size_t len,
struct group **result ); int setgrent_r(
FILE **gr_fp );
The following obsolete functions do not conform to industry standards
and are supported only for backward compatibility. You should not use
them in new designs. int getgrgid_r(
gid_t gid,
struct group *grp,
char *buffer,
int len ); int getgrnam_r(
const char *name,
struct group *grp,
char *buffer,
int len ); int setgrent(
void );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
endgrent(), getgrent(), getgrgid(), getgrgid_r(), getgrnam(), getgr‐
nam_r(), setgrent(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the name of the group for which the group file entry is to be
retrieved. Specifies the group ID of the group for which the group
file entry is to be retrieved. Provides storage to hold the retrieved
group structure. Specifies the working buffer that is able to hold the
longest group entry in the database (/etc/group). Specifies the length
of buffer. This length should be sufficient for buf to hold the longest
/etc/group line. Upon successful return, points to the retrieved group
structure. Upon unsuccessful return, the result is set to NULL. Speci‐
fies a file that contains the next group structure (initialized by the
user). Specifies a file that contains the next group structure (ini‐
tialized by the user). This file should have the same format as
/etc/group. The minimum buffer size is 1024 bytes as defined for
SIABUFSIZ in /usr/include/sia.h. Specifies the length of buffer. The
minimum buffer size is 1024 bytes as defined for SIABUFSIZ in
/usr/include/sia.h.
DESCRIPTION
The getgrent(), getgrgid(), getgrnam(), setgrent(), endgrent(), and
fgetgrent() functions may be used to access the basic group attributes.
The setgrent() function opens the user database (if not already open)
and rewinds to the first group entry in the database.
The getgrent(), getgrnam(), and getgrgid() functions return information
about the requested group. The getgrent() function returns the next
group in the sequential search. The getgrnam() function returns the
first group in the database with the gr_name field that matches the
name parameter. The getgrgid() function returns the first group in the
database with a gr_gid field that matches the gid parameter. The end‐
grent() function closes the user database.
The group structure, which is returned by the getgrent(), getgrgid(),
and getgrnam() functions, is defined in the grp.h header file, and con‐
tains the following members: The name of the group. The password of
the group. (Note that this field is not used by the system, so its
value is meaningless.) The ID of the group. The members of the group.
The fgetgrent() function gets a group file entry from the file speci‐
fied by the f parameter, rather than assuming that it comes from the
/etc/group file. This file must have the format of the /etc/group
file.
The endgrent_r(), fgetgrent_r(), getgrent_r(), getgrgid_r(), getgr‐
nam_r(), and setgrent_r(), functions are the reentrant versions of end‐
grent(), fgetgrent(), getgrent(), getgrgid(), getgrnam(), and set‐
grent(), respectively.
The endgrent_r(), fgetgrent_r(), getgrent_r(), and setgrent_r(), func‐
tions use the f and gr_fp parameters to keep track of the calls to the
getgrent_r function, so that subsequent calls will return subsequent
entries from the /etc/group file.
Upon successful completion, the fgetgrent_r(), getgrent_r(), get‐
grgid_r(), and getgrnam_r() functions store their results in the buffer
pointed to by the grp parameter, with references to the working buffer.
The pointer to the grp is also stored in result.
NOTES
The data that is returned by the fgetgrent(), getgrent(), getgrgid(),
and getgrnam() functions is stored in a static area and will be over‐
written on subsequent calls to these routines.
The fgetgrent(), getgrent(), getgrnam(), and getgrgid() functions are
not supported for multithreaded applications. Instead, their reentrant
equivalents, fgetgrent_r(), getgrent_r(), getgrnam_r(), and get‐
grgid_r,() should be used with multiple threads.
Note that the caller is expected to initialize *gr_fp to NULL before
using it for the first time.
Note also that entries which are excessively long will be ignored by
both the reentrant and non-reentrant functions.
RETURN VALUES
Upon successful completion, the fgetgrent(), getgrent(), getgrgid(),
and getgrnam() functions return a pointer to a valid group structure
containing a matching entry. Upon failure, these functions return NULL.
The getgrgid_r() and getgrnam_r() functions return a value of 0 (zero)
on success. If the user or group is not found in the password or group
database, these routines return 0 for the status and a NULL in the
returned "result" pointer.
The fgetgrent_r() and getgrent_r() functions, as well as the obsolete
versions of the getgrgid_r and getgrnam_r functions, return a value of
0 (zero) for success and a value of -1 for failure.
The backward-compatible version of the setgrent() function returns a
value of 1 for success and a value of 0 (zero) for failure.
The setgrent_r() function returns a value of 0 (zero) for success and a
value of -1 for failure.
ERRORS
If any of the following conditions occurs, the getgrgid_r() and getgr‐
nam_r() functions set errno to the corresponding value: The amount of
storage specified by buffer and len is too small to contain the data to
be referenced by the resulting struct group structure.
SEE ALSO
Functions: getpwent(3)
Standards: standards(5)getgrent(3)