endgrent(3C)




NAME

     getgrnam,  getgrnam_r,   getgrent,   getgrent_r,   getgrgid,
     getgrgid_r,  setgrent,  endgrent,  fgetgrent,  fgetgrent_r -
     group database entry functions


SYNOPSIS

     #include <grp.h>

     struct group *getgrnam(const char *name);

     struct group  *getgrnam_r(const  char  *name,  struct  group
     *grp, char *buffer, int bufsize);

     struct group *getgrent(void);

     struct group *getgrent_r(struct group  *grp,  char  *buffer,
     int bufsize);

     struct group *getgrgid(gid_t gid);

     struct group *getgrgid_r(gid_t gid, struct group *grp,  char
     *buffer, int bufsize);

     void setgrent(void);

     void endgrent(void);

     struct group *fgetgrent(FILE *f);

     struct group *fgetgrent_r(FILE *f, struct group  *grp,  char
     *buffer, int bufsize);

  POSIX
     cc [ flag... ] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]

     int getgrnam_r(const char *name,  struct  group  *grp,  char
     *buffer, size_t bufsize, struct group **result);

     int getgrgid_r(gid_t gid, struct group *grp,  char  *buffer,
     size_t bufsize, struct group **result);


DESCRIPTION

     These functions are used to obtain entries  describing  user
     groups.  Entries  can come from any of the sources for group
     specified    in    the    /etc/nsswitch.conf    file    (see
     nsswitch.conf(4)).

     The getgrnam() function searches the group database  for  an
     entry  with the group name specified by the character string
     parameter name.

     The getgrgid() function searches the group database  for  an
     entry with the (numeric) group id specified by gid.

     The setgrent(), getgrent(),  and  endgrent()  functions  are
     used to enumerate group entries from the database.

     The setgrent() function effectively rewinds the group  data-
     base  to  allow  repeated  searches. It sets (or resets) the
     enumeration to the beginning of the set  of  group  entries.
     This function should be called before the first call to get-
     grent().

     The getgrent() function returns a  pointer  to  a  structure
     containing  the  broken-out  fields of an entry in the group
     database.  When first called, getgrent() returns  a  pointer
     to  a group structure containing the next group structure in
     the group database. Successive calls may be used  to  search
     the entire database.

     The endgrent() function may be called  to  close  the  group
     database  and  deallocate  resources when processing is com-
     plete. It is permissible, though  possibly  less  efficient,
     for  the  process to call more group functions after calling
     endgrent().

     The fgetgrent() function, unlike the other functions  above,
     does  not  use  nsswitch.conf.  It reads and parses the next
     line from the stream f, which is assumed to have the  format
     of the group file (see group(4)).

  Reentrant Interfaces
     The  getgrnam(),  getgrgid(),  getgrent(),  and  fgetgrent()
     functions  use  static  storage that is reused in each call,
     making them unsafe for multithreaded applications.

     The   parallel   functions    getgrnam_r(),    getgrgid_r(),
     getgrent_r(), and fgetgrent_r() provide reentrant interfaces
     for these operations.

     Each reentrant interface performs the same operation as  its
     non-reentrant counterpart, named by removing the  _r suffix.
     The reentrant interfaces, however, use buffers  supplied  by
     the  caller to store returned results, and  are safe for use
     in both single-threaded and multithreaded applications.

     Each reentrant interface takes the  same  arguments  as  its
     non-reentrant  counterpart,  as  well as the following addi-
     tional parameters.  The grp argument must be a pointer to  a
     struct group structure allocated by the caller.  On success-
     ful completion, the function returns the group entry in this
     structure.  Storage  referenced  by  the  group structure is
     allocated from the memory provided with the buffer argument,
     which  is  bufsize  characters  in  size.   The maximum size
     needed  for   this  buffer  can  be  determined   with   the
     _SC_GETGR_R_SIZE_MAX  sysconf(3C)  parameter. The POSIX ver-
     sions place a pointer to the modified grp structure  in  the
     result  parameter,  instead  of  returning a pointer to this
     structure.

     For enumeration in multithreaded applications, the  position
     within  the enumeration is a process-wide property shared by
     all threads. setgrent()  may  be  used  in  a  multithreaded
     application  but  resets  the  enumeration  position for all
     threads.   If   multiple   threads   interleave   calls   to
     getgrent_r(), the threads will enumerate disjoint subsets of
     the group database. Like their  non-reentrant  counterparts,
     getgrnam_r() and getgrgid_r() leave the enumeration position
     in an indeterminate state.


RETURN VALUES

     Group entries are represented by the struct group  structure
     defined in <grp.h>:

     struct group {
         char *gr_name;          /* the name of the group */
         char *gr_passwd;        /* the encrypted group password */
         gid_t gr_gid;           /* the numerical group ID */
         char **gr_mem;          /* vector of pointers to member names */
     };

     The  getgrnam(), getgrnam_r(), getgrgid(), and  getgrgid_r()
     functions  each  return  a pointer to a struct group if they
     successfully locate  the  requested  entry;  otherwise  they
     return   NULL.   The   POSIX   functions   getgrnam_r()  and
     getgrgid_r() return 0 upon success or the  error  number  in
     case of failure.

     The     getgrent(),    getgrent_r(),    fgetgrent(),     and
     fgetgrent_r()  functions  each  return a pointer to a struct
     group if they successfully  enumerate  an  entry;  otherwise
     they return NULL, indicating the end of the enumeration.

     The  getgrnam(),  getgrgid(),  getgrent(),  and  fgetgrent()
     functions  use  static  storage,  so  returned  data must be
     copied before a subsequent call to any of these functions if
     the data is to be saved.

     When  the  pointer  returned  by  the  reentrant   functions
     getgrnam_r(),  getgrgid_r(), getgrent_r(), and fgetgrent_r()
     is non-null, it is always equal to the grp pointer that  was
     supplied by the caller.


ERRORS


     The getgrnam(),  getgrgid(),  getgrent(),  fgetgrent(),  and
     fgetgrent_r() functions may fail if:

     EINTR A signal was caught during the operation.

     EIO   An I/O error has occurred.

     EMFILE
           There are OPEN_MAX file descriptors currently open  in
           the calling process.

     ENFILE
           The maximum allowable number  of  files  is  currently
           open in the system.

     ERANGE
           The group file contains a line that exceeds 512 bytes.

     The getgrnam_r(), getgrgid_r(), and  getgrent_r()  functions
     may fail if:

     ERANGE
           Insufficient storage was supplied by buffer  and  buf-
           size  to  contain  the  data  to  be referenced by the
           resulting group structure.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
   |        ATTRIBUTE TYPE       |        ATTRIBUTE VALUE      |
   | ____________________________|_____________________________|_
   |  MT-Level                   |  See "Reentrant  Interfaces"|
   |                             |  in DESCRIPTION.            |
   |_____________________________|_____________________________|


SEE ALSO

     Intro(3),    getpwnam(3C),    group(4),    nsswitch.conf(4),
     passwd(4), attributes(5), standards(5)


NOTES

     When compiling multithreaded programs, see  Intro(3),  Notes
     On Multithreaded Applications.

     Programs that use the interfaces described  in  this  manual
     page  cannot  be linked statically since the implementations
     of these functions employ dynamic  loading  and  linking  of
     shared objects at run time.

     Use   of   the   enumeration   interfaces   getgrent()   and
     getgrent_r()  is  discouraged;  enumeration is supported for
     the group file, NIS, and NIS+, but in general is  not  effi-
     cient  and  may  not  be supported for all database sources.
     The  semantics  of  enumeration  are  discussed  further  in
     nsswitch.conf(4).

     Previous releases allowed the use of ``+'' and ``-'' entries
     in  /etc/group  to  selectively  include and exclude entries
     from NIS. The primary usage of these entries  is  superseded
     by  the  name service switch, so the ``+/-'' form may not be
     supported in future releases.

     If required, the ``+/-'' functionality can still be obtained
     for NIS by specifying compat as the source for group.

     If the ``+/-'' functionality is required in conjunction with
     NIS+,  specify  both  compat  as  the  source  for group and
     nisplus as the source for the pseudo-database  group_compat.
     See group(4), and nsswitch.conf(4) for details.

     Solaris 2.4 and earlier releases provided definitions of the
     getgrnam_r()  and  getgrgid_r()  functions  as  specified in
     POSIX.1c Draft 6. The final POSIX.1c  standard  changed  the
     interface  for  these  functions.  Support  for  the Draft 6
     interface is provided for compatibility only and may not  be
     supported in future releases. New applications and libraries
     should use the POSIX standard interface.

     For       POSIX.1c-compliant        applications,        the
     _POSIX_PTHREAD_SEMANTICS  and _REENTRANT flags are automati-
     cally turned on by defining the _POSIX_C_SOURCE flag with  a
     value >= 199506L.


Man(1) output converted with man2html