Name

getgrent, getgrgid, getgrnam, setgrent, endgrent − get group entry

Syntax

#include <grp.h>

struct group *getgrent()

struct group *getgrgid(gid)
gid_t gid;

struct group *getgrnam(name)
char *name;

setgrent()

endgrent()

Description

The getgrent, getgrgid and getgrnam subroutines each return pointers to an object with the following structure containing the broken-out fields of a line in the group database:

 struct  group { /* see getgrent(3) */
        char    *gr_name;
        char    *gr_passwd;
        int     gr_gid;
        char    **gr_mem;
};
 struct group *getgrent(), *getgrgid(), *getgrnam();
 

The members of this structure are:

gr_name The name of the group. 

gr_passwd The encrypted password of the group. 

gr_gid The numerical group-ID. 

gr_mem Null-terminated vector of pointers to the individual member names. 

A call to setgrent has the effect of rewinding the group file to allow repeated searches. The endgrent may be called to close the group database when processing is complete.

The getgrent subroutine simply reads the next line while getgrgid and getgrnam search until a matching gid or name is found (or until EOF is encountered).  The getgrent subroutine keeps a pointer in the database, allowing successive calls to be used to search the entire file.

A call to setgrent must be made before a while loop using getgrent in order to perform initialization and an endgrent must be used after the loop.  Both getgrgid and getgrnam make calls to setgrent and endgrent.

Restrictions

All information is contained in a static area so it must be copied if it is to be saved. 

If YP is running, getgrent does not return the entries in any particular order. See the Guide to the Yellow Pages Service for setup information. 

The group database may also be distributed via the BIND/Hesiod naming service.  See the Guide to the BIND/Hesiod Service for more information. 

Return Value

A null pointer (0) is returned on EOF or error. 

Files

/etc/group

See Also

group(5), svc.conf(5)
Guide to the BIND/Hesiod Service
Guide to the Yellow Pages Service