NAME

getgrent(), getgrgid(), getgrnam(), setgrent(), endgrent(), fgetgrent() − get group file entry

SYNOPSIS

#include <grp.h>

struct group *getgrent(void);

struct group *getgrgid(gid_t gid);

struct group *getgrnam(const char *name);

void setgrent(void);

void endgrent(void);

struct group *fgetgrent(FILE *stream);

DESCRIPTION

getgrent(), getgrgid(), and getgrnam() locate an entry in the /etc/group file, and return a pointer to an object of type struct group. 

The group structure is defined in <grp.h> and includes the following members:

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;    /* null-terminated array of pointers
                      to member names */

getgrent() When first called, getgrent() returns a pointer to the first group structure in the file; thereafter, it returns a pointer to the next group structure in the file.  In this way, successive calls can be used to search the entire file.  getgrent() opens the /etc/group file prior to doing its work and leaves the file open afterward;

setgrent() Has the effect of rewinding this file to allow repeated searches;

endgrent() Can be called to close the file when processing is complete. 

getgrgid() Searches from the beginning of the file until a numeric 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. 

fgetgrent() Returns a pointer to the next group structure in the standard I/O stream stream, which should be open for reading, and its contents should match the format of /etc/group. 

NETWORKING FEATURES

NFS

If an entry beginning with a plus sign (+) or a minus sign (−) is found, these routines try to use the Network Information Service network database for data. See group(4) for proper syntax and operation.

RETURN VALUE

getgrent(), getgrgid(), getgrnam(), and fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading.  Otherwise, the return value points to an internal static area containing a valid group structure. 

WARNINGS

The above routines use <stdio.h> and the Network Information Service library.  This causes them to increase the size of programs that do not otherwise use standard I/O and Network Information Service more than might ordinarily be expected. 

The value returned by these functions points to a single static area that is overwritten by each call to any of the functions.  It must be copied if it is to be saved. 

DEPENDENCIES

NFS:

FILES

/etc/yp/domainname/group.byname
/etc/yp/domainname/group.bygid

SEE ALSO:

ypcat(1). 

FILES

/etc/group

SEE ALSO

getgroups(2), getpwent(3C), stdio(3S), group(4). 

STANDARDS CONFORMANCE

getgrent(): SVID2, XPG2
endgrent(): SVID2, XPG2

fgetgrent(): SVID2, XPG2
getgrgid(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

getgrnam(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
setgrent(): SVID2, XPG2

Hewlett-Packard Company  —  HP-UX Release 9.10: April 1995