getgrent(3C)                                            getgrent(3C)


       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 *f);

       DESCRIPTION
             getgrent, getgrgid, and getgrnam each returns a pointer to a
             structure containing the broken-out fields of a line in the
             /etc/group file.  Each line contains a ``group'' structure,
             defined in the grp.h header file with 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;    /* vector of pointers to member names */

             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; 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.

             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.




                           Copyright 1994 Novell, Inc.               Page 1

      getgrent(3C)                                            getgrent(3C)


            When used by a multithreaded program, each distinct thread
            will have its own group structure and, except for fgetgrent,
            its own underlaying file descriptor.

         Files
            /etc/group
            /var/yp/domainame/group.byname
            /var/yp/domainame/group.bygid

         Errors
            getgrent, getgrgid, getgrnam, and fgetgrent return a null
            pointer on EOF or error.  If the functions are unable to
            allocate sufficient space for the entry, errno is set to
            ENOMEM.

      REFERENCES
            getlogin(3C), getpwent(3C), group(4)

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

            Group structures will be obtained from NIS, when the dynamic
            versions of these routines (other than fgetgrent) are used and
            NIS is installed and running.  See group(4) for the formats of
            NIS entries.

      LEVEL
            Level 2.



















                          Copyright 1994 Novell, Inc.               Page 2