getgrent(3C)                   DG/UX R4.11MU05                  getgrent(3C)


NAME
       getgrent, getgrentr, getgrgid, getgrgidr, getgrnam, getgrnamr,
       setgrent, endgrent, fgetgrent, fgetgrentr - get group file entry

SYNOPSIS
       #include <grp.h>

       struct group *getgrent(void)

       struct group *getgrentr(struct group *result, char *buffer, int buflen)

       struct group *getgrgid(gidt gid)

       struct group *getgrgidr(gidt gid, struct group *result, char *buffer,
                 int buflen)

       struct group *getgrnam(const char *name)

       struct group *getgrnamr(const char *name, struct group *result,
                 char *buffer, int buflen)

       void setgrent(void)

       void endgrent(void)

       struct group *fgetgrent(FILE *f)

       struct group *fgetgrentr(FILE *f, struct group *result, char *buffer,
                 int buflen)

DESCRIPTION
       getgrent, getgrentr, getgrgid, getgrgidr, getgrnam, and getgrnamr
       each return pointers to an object with the following structure
       containing the broken-out fields of a line in the group file.

              struct    group {
                   char *grname;
                   char *grpasswd;
                   gidt     grgid;
                   char **grmem;
              };

       The members of this structure are:

       grname    The name of the group.
       grpasswd  The encrypted password of the group.
       grgid     The numerical group-ID.
       grmem     Null-terminated vector of pointers to the individual
                  member names.

       getgrent and getgrentr simply read the next line while getgrgid,
       getgrgidr, getgrnam, and getgrnamr 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 may be used to search
       the entire file.

       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.

       fgetgrent and fgetgrentr return a pointer to the next group
       structure in the stream f, which must refer to an open file in the
       same format as the group file /etc/group.

       The functions getgrentr, getgrgidr, getgrnamr, and fgetgrentr
       differ from their non r counterparts by the addition of three
       arguments.  When calling these, the group structure pointed to by
       result will be updated.  In addition, a pointer to a buffer and
       buflen (the length of the buffer) must be passed.  These new
       arguments are used to rid the r functions' dependencies on static
       data.  Storage referenced by the group structure will be allocated
       from the memory provided by buffer.

   Considerations for Threads Programming
                    +------------+-----------------------------+
                    |            |                      async- |
                    |function    | reentrant   cancel   cancel |
                    |            |             point     safe  |
                    +------------+-----------------------------+
                    |endgrent    |     Y         N        N    |
                    |fgetgrent   |     N         -        -    |
                    |fgetgrentr |     Y         N        N    |
                    |getgrent    |     N         -        -    |
                    |getgrentr  |     Y         N        N    |
                    |getgrgid    |     N         -        -    |
                    |getgrgidr  |     Y         Y        N    |
                    |getgrnam    |     N         -        -    |
                    |getgrnamr  |     Y         Y        N    |
                    |setgrent    |     Y         N        N    |
                    +------------+-----------------------------+
       When the getgrentr, getgrgidr, getgrnamr, and fgetgrentr
       functions are used in a threaded application, they share the same
       state information (position in file, etc.) so they can work
       cooperatively.  In other words, if a number of threads are repeatedly
       calling the getgrentr function, each routine call will pick up where
       the other left off so successive calls in all threads may be used to
       search the entire file.

FILES
       /etc/group

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

       If the functions getgrentr, getgrgidr, getgrnamr, and fgetgrentr
       are called with insufficient storage supplied via buffer and buflen
       to contain the data to be referenced by the resulting struct group
       structure, the function will return a NULL and errno will be set to
       ERANGE.

NOTES
       The functions getgrentr, getgrgidr, getgrnamr, and fgetgrentr are
       only available in the shared library libc.so.

       The functions getgrentr and fgetgrentr are only visible when the
       DGUXTHREADSEXTENSIONS macro is defined during compilation (cc
       -DDGUXTHREADSEXTENSIONS).  This is because these functions are not
       part of the 1003.4a Draft.

SEE ALSO
       bcscat(1M), ypserv(1M), reentrant(3), getlogin(3C), getpwent(3C),
       group(4).

BUGS
       In all of the above functions except getgrentr, getgrgidr,
       getgrnamr, and fgetgrentr, the information is contained in a static
       area, so it must be copied if it is to be saved.

STANDARDS
       When using m88kbcs as the Software Development Environment target,
       the functions mentioned above will be implemented on top of the
       bcscat command.  Because of this, some performance degradation may
       be noticed in comparison to using other development environments.


Licensed material--property of copyright holder(s)