GETGRENT(3)                    Library Routines                    GETGRENT(3)

NAME

       getgrent,  getgrnam,  getgrgid, setgroupent, setgrent, endgrent - group
       database operations

SYNOPSIS

       #include <sys/types.h>
       #include <grp.h>

       struct group * getgrent (void);
       struct group * getgrnam (const char *name);
       struct group * getgrgid (gid_t gid);
       int setgroupent (int stayopen);
       int setgrent (void);
       void endgrent (void);

DESCRIPTION

       These functions operate on the group database file /etc/group which  is
       described  in  group(5).   Each  line of the database is defined by the
       structure group found in the include file <grp.h>:

       struct group {
            char *gr_name; /* group name */
            char *gr_passwd;    /* group password */
            gid_t     gr_gid;        /* group id */
            char **gr_mem; /* group members */
       };

       Applications should never read /etc/group directly, as the  implementa‐
       tion of the group database is subject to change.

       The  functions  getgrnam and getgrgid search the group database for the
       given group name pointed to by name or the group id gid,  respectively,
       returning  the  first  one encountered.  Identical group names or group
       gids may result in undefined behavior.

       The getgrent function sequentially reads the group database and is  in‐
       tended  for  programs  that  wish  to step through the complete list of
       groups.

       All three routines will open the group file for reading, if necessary.

       The setgroupent function opens the file, or rewinds it if it is already
       open.  If stayopen is non-zero, file descriptors are left open, signif‐
       icantly speeding functions subsequent calls.  This functionality is un‐
       necessary  for getgrent as it doesn't close its file descriptors by de‐
       fault.  It should also be noted that it is dangerous  for  long-running
       programs to use this functionality as the group file may be updated.

       The  setgrent  function is identical to setgroupent with an argument of
       zero.

       The endgrent function closes any open files.

YP/NIS INTERACTION

       When the yp(4) group database is enabled,  the  getgrnam  and  getgrgid
       functions  use  the YP maps group.byname and group.bygid, respectively,
       if the requested group is not found in the local /etc/group file.   The
       getgrent  function will step through the YP map group.byname if the en‐
       tire map is enabled as described in group(5).

RETURN VALUES

       The functions getgrent, getgrnam, and getgrgid, return a pointer to the
       group entry if successful; if end-of-file is reached or an error occurs
       a null pointer is returned.  The functions setgroupent and setgrent re‐
       turn the value 1 if successful, otherwise the value 0 is returned.  The
       functions endgrent and setgrfile have no return value.

FILES

       /etc/group
              group database file

SEE ALSO

       getpwent3, group5, yp4

HISTORY

       The functions endgrent, getgrent, getgrnam, getgrgid, and setgrent  ap‐
       peared in Version 7 AT&T UNIX.  The functions setgrfile and setgroupent
       appeared in 4.3BSD (Reno).

COMPATIBILITY

       The historic function setgrfile, which allowed the specification of al‐
       ternate password databases, has been deprecated and is no longer avail‐
       able.

BUGS

       The functions getgrent, getgrnam, getgrgid,  setgroupent  and  setgrent
       leave  their  results in an internal static object and return a pointer
       to that object. Subsequent calls to the same function will  modify  the
       same object.

       GNO does not currently make use of the yp(4) database.



GNO                             27 January 1997                    GETGRENT(3)