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


     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


SEE ALSO
     nsd(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