GETGRENT(3)                          BSD                           GETGRENT(3)



NAME
     getgrent, getgrgid, getgrgid_r, getgrnam, getgrnam_r, setgrent, endgrent,
     setgrfile - get group file entry

SYNOPSIS
     #include <grp.h>

     struct group *getgrent()

     struct group *getgrgid(gid)
     int gid;

     struct group *getgrgid_r (results, gid, buffer,len)
     gid_t gid;
     struct group *results;
     char *buffer;
     int len;

     struct group *getgrnam(name)
     char *name;

     struct group *getgrnam_r (results,name,buffer,len)
     const char *name;
     struct group *results;
     char *buffer;
     int len;

     setgrent()

     endgrent()

     setgrfile(name)
     char *name;

DESCRIPTION
     getgrent, getgrgid and getgrnam return pointers to an object with the
     following structure, which contains the broken-out fields of a line in
     the group file.

          /*   grp.h     4.1  83/05/03  */

          struct    group { /* see getgrent(3) */
               char *gr_name;
               char *gr_passwd;
               int  gr_gid;
               char **gr_mem;
          };

          #ifndef __STDC__
          struct group *getgrent(), *getgrgid(), *getgrnam();
          #else
          struct group *getgrent(void);
          struct group *getgrgid(int gid);
          struct group *getgrnam(char *name);
          void setgrent(void);
          void endgrent(void);
          #endif

     The members of this structure are

     gr_name    The name of the group.

     gr_passwd  The encrypted password of the group.
     gr_gid     The numerical group-ID.
     gr_mem     Null terminated vector of pointers to the individual member
                names.

     getgrent simply reads the next line while getgrgid and getgrnam search
     until a matching gid or name is found (or until EOF is encountered).
     Each routine picks up where the others leave off, so successive calls can
     be used to search the entire file.

     A call to setgrent has the effect of rewinding the group file to allow
     repeated searches.  endgrent can be called to close the group file when
     processing is complete.

NOTES
     All information is contained in a static area, so it must be copied if it
     is to be saved.

     Under Domain/OS BSD, /etc/group is a read-only object of the type
     "group," maintained by the registry server.  See rgyd(8).  The presence
     of the registry server affects the implementation of these interfaces in
     the following way.

     If there was no call to setgrfile, these interfaces call the registry
     server.  If this call fails, they search the local registry.

     If there was a call to setgrfile, these interfaces search name.  They
     access name by way of its type manager.  If name is of type "group" (as
     in the case of /etc/group), its manager will cause the interface to call
     the registry server.  If, in this case, the call to the registry server
     fails, the local registry will not be searched.  name remains in effect
     until the next call to setgrfile or the process fails.

     The getgrgid_r and getgrnam_r functions are the reentrant versions of
     getgrgid and getgrnam, respectively.  Upon successful completion, the
     result is stored in the buffer pointed to by the result parameter.

FILES
     /etc/group

SEE ALSO
     getlogin(3), getpwent(3), group(5), rgyd(8)
     Domain/OS System Administration Reference.

DIAGNOSTICS
     A null pointer (0) is returned on EOF or error.