NAME    [Toc]    [Back]

     getgrent,  getgrnam,   getgrnam_r,   getgrgid,   getgrgid_r,
setgroupent,
     setgrent, endgrent - group database operations

SYNOPSIS    [Toc]    [Back]

     #include <sys/types.h>
     #include <grp.h>

     struct group *
     getgrent(void);

     struct group *
     getgrnam(const char *name);

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

     struct group *
     getgrgid(gid_t gid);

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

     int
     setgroupent(int stayopen);

     void
     setgrent(void);

     void
     endgrent(void);

DESCRIPTION    [Toc]    [Back]

     These   functions   operate   on  the  group  database  file
/etc/group which is
     described in group(5).  Each line of the database is defined
by the
     structure struct group found in the include file <grp.h>:

           struct group {
                   char    *gr_name;       /* group name */
                   char    *gr_passwd;     /* group password */
                   gid_t   gr_gid;         /* group id */
                   char    **gr_mem;       /* group members */
           };

     The  functions  getgrnam()  and  getgrgid() search the group
database for the
     given group name pointed to by name or the group ID  pointed
to by gid,
     respectively,  returning the first one encountered.  Identical group names
     or group GIDs may result in undefined behavior.

     getgrent() sequentially reads the group database and is  intended for programs
 that wish to step through the complete list of groups.

     All three routines will open the group file for reading,  if
necessary.

     setgroupent() opens the file, or rewinds it if it is already
open.  If
     stayopen is non-zero, file descriptors are left  open,  significantly
     speeding  subsequent  function calls.  This functionality is
unnecessary
     for getgrent() as it doesn't close its file  descriptors  by
default.  It
     should  also  be noted that it is dangerous for long-running
programs to
     use this functionality as the group file may be updated.

     setgrent() is equivalent to setgroupent() with  an  argument
of zero.

     The endgrent() function closes any open files.

     The  getgrgid_r() and getgrnam_r() functions both update the
group structure
 pointed to by grp and store a pointer to that structure
at the location
  pointed to by result.  The structure is filled with an
entry from
     the group database with a matching  gid  or  name.   Storage
referenced by
     the  group  structure will be allocated from the memory provided with the
     buffer parameter, which is bufsiz characters in size.

RETURN VALUES    [Toc]    [Back]

     The functions getgrent(), getgrnam(), and getgrgid()  return
a pointer to
     the  group entry if successful; if end-of-file is reached or
an error occurs
 a null pointer is returned.  The setgroupent() function
returns the
     value  1  if  successful,  otherwise  0.  The endgrent() and
setgrent() functions
 have no return value.  The functions getgrgid_r()  and
getgrnam_r()
     store  a  null  pointer at the location pointed to by result
and return the
     error number if an error occurs, or the requested  entry  is
not found.

FILES    [Toc]    [Back]

     /etc/group  group database file

SEE ALSO    [Toc]    [Back]

     getpwent(3), group(5)

HISTORY    [Toc]    [Back]

     The    functions    endgrent(),    getgrent(),   getgrnam(),
getgrgid(), and
     setgrent() appeared in Version 7 AT&T UNIX.   The  functions
setgrfile()
     and setgroupent() appeared in 4.3BSD-Reno.

     The historic function setgrfile(3), which allowed the specification of
     alternate group databases, has been  deprecated  and  is  no
longer available.

BUGS    [Toc]    [Back]

     The    functions    getgrent(),    getgrnam(),   getgrgid(),
setgroupent(), and
     setgrent() leave their results in an internal static  object
and return a
     pointer  to that object.  Subsequent calls to the same function will modify
 the same object.

     The functions  getgrent(),  endgrent(),  setgroupent(),  and
setgrent() are
     fairly  useless  in  a  networked  environment and should be
avoided, if possible.


OpenBSD     3.6                          April      19,      1994