# getgrent(3)

    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 implemented 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 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)