GETGRENT(3)						     Library Functions Manual						       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 por-
       table 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)

																       GETGRENT(3)