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
       intended  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
       unnecessary for getgrent as it doesn't close its  file  descriptors  by
       default.  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
       entire 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
       return 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
       appeared in Version 7 AT&T UNIX.   The  functions  setgrfile  and  set-
       groupent appeared in 4.3BSD (Reno).


COMPATIBILITY

       The  historic  function  setgrfile,  which allowed the specification of
       alternate password databases, has been  deprecated  and  is  no  longer
       available.


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)

Man(1) output converted with man2html