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)