GETGRENT(3C)                         SysV                         GETGRENT(3C)



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

SYNOPSIS
     #include <grp.h>

     struct group *getgrent (void)

     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,
     const char *name;
     struct group *results;
     char *buffer;
     int len;

     void setgrent (void)

     void endgrent (void)

     struct group *fgetgrent (f)
     FILE *f;

     setgrfile(name)
     char *name;

DESCRIPTION
     getgrent, getgrgid and getgrnam return pointers to an object with the
     following structure, containing the broken-out fields of a line in the
     /etc/group file.  Each line contains a "group" structure, defined in the
     <grp.h> header file.

          struct group {
                 char    *gr_name;
                 char    *gr_passwd;
                 int     gr_gid;
                 char    **gr_mem;
          };

     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.

     When first called, getgrent returns a pointer to the first line in the
     file.  Each call thereafter returns a pointer to a successive line.
     getgrgid and getgrnam search from the beginning of the file until a

     matching gid or name, respectively, is found (or until EOF is
     encountered).

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

     getgrent returns a pointer to the next group structure in the stream f,
     which matches the format of /etc/group.

     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.

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

     The above routines use <stdio.h>, which causes them to increase the size
     of programs, not otherwise using standard I/O, more than might be
     expected.

     Under Domain/OS SysV, /etc/group is a read-only object of the type
     "group," maintained by the registry server.  See rgyd(1M).  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.

DIAGNOSTICS
     A NULL pointer is returned on EOF or error.

FILES
     /etc/group

SEE ALSO
     getlogin(3C), getorgent(3C), getpwent(3C), group(4), rgyd(1M).
     Domain/OS System Administration Reference".