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(gidt gid);

     struct group *getgrnam(const char *name);

     void setgrent(void);

     void endgrent(void);

     struct group *fgetgrent(FILE *f);

DESCRIPTION
     getgrent(), getgrgid(), and getgrnam() each return pointers to an
     object 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:

     struct        group {
           char    *grname;      /* the name of the group */
           char    *grpasswd;    /* the encrypted group password */
           gidt   grgid;        /* the numerical group ID */
           char    **grmem;      /* 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 struc-
     ture in which it was found. If an end-of-file or an error is encoun-
     tered on reading, these functions return a null pointer.

     A call to setgrent() has the effect of resetting the file pointer to
     the start of the group file, thus permitting 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.




Page 1                       Reliant UNIX 5.44                Printed 11/98

getgrent(3C)                                                   getgrent(3C)

RESULT
     getgrent(), getgrgid(), getgrnam(), and fgetgrent() return a null
     pointer on EOF or error.

ERRORS
     The following error code descriptions are function-specific. You will
     find a general description in introprm2(2) or in errno(5).

     The getgrent() function may fail if:

     EINTR     A signal was caught during the operation.

     EIO       An I/O error has occurred.

     EMFILE    OPENMAX file descriptors are currently open in the calling
               process.

     ENFILE    The maximum allowable number of files is currently open in
               the system.

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

     Applications wishing to check for error situations must set errno to
     zero before calling the appropriate function.

FILES
     /etc/group

SEE ALSO
     getlogin(3C), getpwent(3C), group(4), grp(5).






















Page 2                       Reliant UNIX 5.44                Printed 11/98