GETGRENT(3C)GETGRENT(3C)NAME
getgrent, getgrent_r, getgrgid, getgrgid_r, getgrnam, getgrnam_r,
setgrent, endgrent, fgetgrent, fgetgrent_r, getgrmember - get group file
entry
SYNOPSIS
#include <grp.h>
struct group *getgrent(void);
struct group *getgrent_r(struct group *grent, char *buffer, int bufsize);
struct group *getgrgid(gid_t gid);
int getgrgid_r(gid_t gid, struct group *grent, char *buffer, int bufsize, struct group **grp);
struct group *getgrnam(const char *name);
int getgrnam_r(const char *name, struct group *grent, char *buffer, int bufsize, struct group **grp);
void setgrent(void);
void endgrent(void);
struct group *fgetgrent(FILE *f);
struct group *fgetgrent_r(FILE *f, struct group *grent, char *buffer, int bufsize);
int getgrmember(const char *name, gid_t gid_array[], int maxgids, int vgids);
DESCRIPTION
getgrent, getgrgid and getgrnam and their reentrant counterparts each
return pointers to an object with the following structure containing the
broken-out fields of a line in the /etc/group file or some other back-end
group database. Each line contains a ``group'' structure, defined in the
<grp.h> header file.
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 */
};
getgrent when first called returns a pointer to the first group structure
in the file; thereafter, it returns a pointer to the next group structure
in the file; so, successive calls may be used to search the entire file.
getgrgid searches from the beginning of the file until a numerical group
id matching gid is found and returns a pointer to the particular
structure in which it was found. getgrnam searches from the beginning of
the file until a group name matching name is found and returns a pointer
to the particular structure in which it was found. If an end-of-file or
Page 1
GETGRENT(3C)GETGRENT(3C)
an error is encountered on reading, these functions return a NULL
pointer.
The getgrnam_r and getgrgid_r calls are reentrant versions of the
getgrnam and getgrgid calls. The extra arguments grent and buffer are
used for internal storage, bufsize is size of buffer, and grp is the
struct group used to return the requested information. A good size of
buffer is BUFSIZ bytes.
A call to setgrent has the effect of rewinding the group file to allow
repeated searches. endgrent may be called to close the group file when
processing is complete.
fgetgrent returns a pointer to the next group structure in the stream f,
which matches the format of /etc/group.
NOTES
In IRIX 4.0, there were two versions of the getpwent primitives: the
standard version in libc and the NIS version in libsun. This release
contains only routines to parse files, an external file supply mechanism
nsd(1) supplies data from NIS and other protocols as files. To force
these routines to not use nsd supplied data set the external
_getpwent_no_yp variable to 1. This is useful for programs that must not
generate any network traffic, and for programs that update the /etc/group
file.
getgrmember is used to get the ids of the groups of which the given user
is a member. name is the name of the user. The group ids are returned
in the array gid_array which contains maxgids elements. The first vgid
elements of gid_array are not used by getgrmember and can be used by the
caller to initialize default group ids. getgrmember is usually called by
initgroups. getgrmember returns the number of valid gids in the gid array
or -1 if an error is encountered.
The Mips ABI specifies nothing but local files so applications which wish
to use anything else must compile with libc prior to libnsl in the
library list.
When nsd is running changes in the group file may not be seen by
getgrent() until the nsd enumeration cache file has timed out.
DIAGNOSTICS
All routines that return a struct group * will return a NULL pointer in
the case of EOF or failure. The reentrant functions return the errno(3C)
for the call, and thus 0 implies success. The getgrmember call returns
the number of gids found, and -1 on failure.
FILES
/etc/group /var/ns/cache/group.byname.m /var/ns/cache/group.bygid.m
/var/ns/cache/group.bymember.m
Page 2
GETGRENT(3C)GETGRENT(3C)SEE ALSOnsd(1M), getgroups(2), errno(3C), getlogin(3C), getpwent(3C), group(4).
WARNING
The above routines use the stdio library, which causes them to increase
the size of programs, not otherwise using standard I/O, more than might
be expected. They also map an external cache file which can cause the
application to be larger than expected.
Page 3
