getgrent(S)                    6 January 1993                    getgrent(S)


 Name

    getgrent, getgrgid, getgrnam, setgrent, endgrent, fgetgrent - get group
    file entry

 Syntax


    cc  . . .  -lc


    #include  <grp.h>

    struct group *getgrent ()

    struct group *getgrgid (gid)
    gid_t gid;

    struct group *getgrnam (name)
    char *name;

    void setgrent ()

    void endgrent ()

    struct group *fgetgrent (f)
    FILE *f;


 Description

    The getgrent, getgrgid, and getgrnam routines return pointers to an
    object with the following 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.

       struct  group {
               char       *gr_name;        /* the name of the group */
               char       *gr_passwd;      /* the encrypted group password */
               int        gr_gid;          /* the numerical group ID */
               char       **gr_mem;        /* vector of pointers to member names */
       };

    When the getgrent routine is first called, it returns a pointer to the
    first group structure in the /etc/group file.  Thereafter, it returns a
    pointer to the next group structure in the /etc/group file.  Thus, suc-
    cessive calls to getgrent may be used to search the entire file.

    The getgrgid routine searches from the beginning of the /etc/group file
    until a numerical group ID matching the argument gid is found.  getgrgid
    returns a pointer to the group structure in which the argument gid was
    found.

    Like getgrgid, the getgrnam routine searches from the beginning of the
    /etc/group file until a group whose name matches the argument name is
    found.  getgrnam returns a pointer to the particular group structure in
    which the argument name was found.

    The setgrent routine resets the file pointer to the beginning of the
    group file to allow repeated searches.  The endgrent routine closes the
    group file when processing is complete.

    The fgetgrent routine returns a pointer to the next group structure which
    matches the format of /etc/group in the stream argument f.

 Return value

    Upon successful completion, the routines getgrent, getgrgid, getgrnam,
    and fgetgrent each returns a pointer to a group structure.  If an end-
    of-file or an error is encountered on reading, these routines return a
    NULL pointer.  No errors are defined for the setgrent or endgrent rou-
    tines.

 Diagnostics

    Use feof() to test if a null return value is caused by an end-of-file or
    from a syntax error in the group file.  The feof macro is described in
    the ferror(S) manual page.

 Note

    All information is contained in a static area, so it must be copied if it
    is to be saved.  Otherwise, it may be overwritten on subsequent calls to
    these routines.

 Files

    /etc/group

 See also

    getlogin(S), getpwent(S), group(F)

 Standards conformance

    fgetgrent, getgrent, endgrent, and  setgrent conform with:
    AT&T SVID Issue 2;
    these routines have been withdrawn from XPG3.

    getgrgid and getgrnam conform with:
    AT&T SVID Issue 2;
    X/Open Portability Guide, Issue 3, 1989;
    IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C
    Language] (ISO/IEC 9945-1);
    and NIST FIPS 151-1.