getgrent(3C)                      SDK R4.11                     getgrent(3C)


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

SYNOPSIS
       #include <grp.h>

       struct group *getgrent(void)

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

       struct group *getgrgid(gid_t gid)

       struct group *getgrgid_r(gid_t gid, struct group *result, char *buffer,
                 int buflen)

       struct group *getgrnam(const char *name)

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

       void setgrent(void)

       void endgrent(void)

       struct group *fgetgrent(FILE *f)

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

DESCRIPTION
       getgrent, getgrent_r, getgrgid, getgrgid_r, getgrnam, and getgrnam_r
       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 *gr_name;
                   char *gr_passwd;
                   gid_t     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.

       getgrent and getgrent_r simply read the next line while getgrgid,
       getgrgid_r, getgrnam, and getgrnam_r 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 fgetgrent_r 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 getgrent_r, getgrgid_r, getgrnam_r, and fgetgrent_r
       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         -        -    |
                    |fgetgrent_r |     Y         N        N    |
                    |getgrent    |     N         -        -    |
                    |getgrent_r  |     Y         N        N    |
                    |getgrgid    |     N         -        -    |
                    |getgrgid_r  |     Y         Y        N    |
                    |getgrnam    |     N         -        -    |
                    |getgrnam_r  |     Y         Y        N    |
                    |setgrent    |     Y         N        N    |
                    +------------+-----------------------------+
       When the getgrent_r, getgrgid_r, getgrnam_r, and fgetgrent_r
       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 getgrent_r 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 getgrent_r, getgrgid_r, getgrnam_r, and fgetgrent_r
       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 getgrent_r, getgrgid_r, getgrnam_r, and fgetgrent_r are
       only available in the shared library libc.so.

       The functions getgrent_r and fgetgrent_r are only visible when the
       _DGUX_THREADS_EXTENSIONS macro is defined during compilation (cc
       -D_DGUX_THREADS_EXTENSIONS).  This is because these functions are not
       part of the 1003.4a Draft.

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

BUGS
       In all of the above functions except getgrent_r, getgrgid_r,
       getgrnam_r, and fgetgrent_r, 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
       bcs_cat command.  Because of this, some performance degradation may
       be noticed in comparison to using other development environments.


Licensed material--property of copyright holder(s)