
GETGRENT(3)                UNIX Programmer's Manual                GETGRENT(3)

NNAAMMEE
     ggeettggrreenntt, ggeettggrrnnaamm, ggeettggrrggiidd, sseettggrroouuppeenntt, sseettggrreenntt, eennddggrreenntt - group
     database operations

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ggrrpp..hh>>

     _s_t_r_u_c_t _g_r_o_u_p _*
     ggeettggrreenntt(_v_o_i_d)

     _s_t_r_u_c_t _g_r_o_u_p _*
     ggeettggrrnnaammee(_c_o_n_s_t _c_h_a_r _*_n_a_m_e)

     _s_t_r_u_c_t _g_r_o_u_p _*
     ggeettggrrggiidd(_g_i_d___t _g_i_d)

     _s_t_r_u_c_t _g_r_o_u_p _*
     sseettggrroouuppeenntt(_i_n_t _s_t_a_y_o_p_e_n)

     _i_n_t
     sseettggrreenntt(_v_o_i_d)

     _v_o_i_d
     eennddggrreenntt(_v_o_i_d)

DDEESSCCRRIIPPTTIIOONN
     These functions operate on the group database file _/_e_t_c_/_g_r_o_u_p which is
     described in group(5).  Each line of the database is defined by the
     structure _g_r_o_u_p found in the include file <_g_r_p_._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 ggeettggrrnnaamm() and ggeettggrrggiidd() search the group database for the
     given group name pointed to by _n_a_m_e or the group id pointed to by _g_i_d,
     respectively, returning the first one encountered.  Identical group names
     or group gids may result in undefined behavior.

     The ggeettggrreenntt() function sequentially reads the group database and is in-
     tended for programs that wish to step through the complete list of
     groups.

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

     The sseettggrroouuppeenntt() function opens the file, or rewinds it if it is already
     open.  If _s_t_a_y_o_p_e_n is non-zero, file descriptors are left open, signifi-
     cantly speeding functions subsequent calls.  This functionality is unnec-
     essary for ggeettggrreenntt() as it doesn't close its file descriptors by de-
     fault.  It should also be noted that it is dangerous for long-running
     programs to use this functionality as the group file may be updated.

     The sseettggrreenntt() function is identical to sseettggrroouuppeenntt() with an argument of
     zero.

     The eennddggrreenntt() function closes any open files.

RREETTUURRNN VVAALLUUEESS
     The functions ggeettggrreenntt(), ggeettggrrnnaamm(), and ggeettggrrggiidd(), return a pointer to
     the group entry if successful; if end-of-file is reached or an error oc-
     curs a null pointer is returned.  The functions sseettggrroouuppeenntt() and
     sseettggrreenntt() return the value 1 if successful, otherwise the value 0 is re-
     turned.  The functions eennddggrreenntt() and sseettggrrffiillee() have no return value.

FFIILLEESS
     /etc/group  group database file

SSEEEE AALLSSOO
     ggeettppwweenntt(_3), ggrroouupp(_5)

HHIISSTTOORRYY
     The functions eennddggrreenntt(), ggeettggrreenntt(), ggeettggrrnnaamm(), ggeettggrrggiidd(), and
     sseettggrreenntt() appeared in Version 7 AT&T UNIX.  The functions sseettggrrffiillee()
     and sseettggrroouuppeenntt() appeared in 4.3BSD-Reno.

CCOOMMPPAATTIIBBIILLIITTYY
     The historic function sseettggrrffiillee(), which allowed the specification of al-
     ternate password databases, has been deprecated and is no longer avail-
     able.

BBUUGGSS
     The functions ggeettggrreenntt(), ggeettggrrnnaamm(), ggeettggrrggiidd(), sseettggrroouuppeenntt() and
     sseettggrreenntt() 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 ggeettggrreenntt(), eennddggrreenntt(), sseettggrroouuppeenntt(), and sseettggrreenntt() are
     fairly useless in a networked environment and should be avoided, if pos-
     sible.

BSD Experimental                April 20, 1991                               2



































