NAME

     getgrent, getgrnam, getgrgid, setgrent, endgrent,  setgrfile
     - group file routines


SYNOPSIS

     #include <grp.h>

     struct group *getgrent(void)
     struct group *getgrnam(const char *name)
     struct group *getgrgid(gid_t gid)
     int setgrent(void)
     void endgrent(void)
     void setgrfile(const char *file)


DESCRIPTION

     These functions are used  to  obtain  information  from  the
     group  file.  They return this information in a struct group
     as defined by <grp.h>:

     struct group {
         char  *gr_name;      /* login name */
         char  *gr_passwd;    /* encrypted password */
         gid_t gr_gid;        /* numeric group id */
         char  **gr_mem;      /* null-terminated list of group members */
     };

     Getgrent() reads the group file entry by entry.   Getgrnam()
     scans  the  entire  group  file for the group with the given
     name.  Getgrgid() looks for the first group with  the  given
     gid.   The  setgrent()  and endgrent() functions are used to
     open and later close the group file.  With  setgrfile()  one
     can  specify  the  file  to read other than the normal group
     file.  This only sets the name,  the  next  setgrent()  call
     will  open the file.  Do not touch the file name while it is
     active.  Use setgrfile(NULL) to revert back  to  the  normal
     group file.

     The usual way to scan the  group  file  is  (error  checking
     omitted):

          setgrent();
          while ((gr = getgrent()) != NULL)
               if (appropriate_test(gr)) break;
          endgrent();

     The gr variable contains the entry that is  wanted  if  non-
     NULL.   The  getgrnam()  and getgrgid() functions are imple-
     mented as in this example, with error checking of course.

     Getgrent() calls setgrent() if this has not yet  been  done.
     Setgrent() first calls endgrent() if the group file is still
     open.  (Other implementations may simply rewind the file.)


FILES

     /etc/group     The group file database.


SEE ALSO

     getgroups(2), initgroups(3), getpwent(3), passwd(5).


DIAGNOSTICS

     Setgrent() has the same return value and error codes as  the
     open(2)  call  it uses to open the group file.  The getxxx()
     functions return NULL on end of file, entry  not  found,  or
     error.   You can set errno to zero before the call and check
     it after.


NOTES

     All getxxx() routines return a  pointer  to  static  storage
     that is overwritten in each call.

     Only getgrnam() and getgrgid() are defined  by  POSIX.   The
     _MINIX_SOURCE macro must be defined before including <grp.h>
     to make the other functions visible.  The gr_passwd field is
     also  not defined by POSIX, but is always visible.  Portable
     code cannot reliably detect errors by setting errno to zero.
     Under  MINIX 3 it is better to make a getgrent() scan if you
     need to look up several group-id's or  names,  but  portable
     code  had better use several getgrgid() or getgrnam() calls.
     The getgrent() is usually available on  other  systems,  but
     may  be  very expensive.  See initgroups(3) if you are after
     supplementary group id's.


AUTHOR

     Kees J. Bot (kjb@cs.vu.nl)