xref: /386bsd/usr/share/man/cat3/getgrnam.0 (revision a2142627) 
1GETGRENT(3)               386BSD Programmer's Manual               GETGRENT(3)
2
3NNAAMMEE
4     ggeettggrreenntt, ggeettggrrnnaamm, ggeettggrrggiidd, sseettggrroouuppeenntt, sseettggrreenntt, eennddggrreenntt - group
5     database operations
6
7SSYYNNOOPPSSIISS
8     ##iinncclluuddee <<ggrrpp..hh>>
9
10     _s_t_r_u_c_t _g_r_o_u_p *
11     ggeettggrreenntt(_v_o_i_d)
12
13     _s_t_r_u_c_t _g_r_o_u_p *
14     ggeettggrrnnaamm(_c_o_n_s_t _c_h_a_r *_n_a_m_e)
15
16     _s_t_r_u_c_t _g_r_o_u_p *
17     ggeettggrrggiidd(_g_i_d__t _g_i_d)
18
19     _s_t_r_u_c_t _g_r_o_u_p *
20     sseettggrroouuppeenntt(_i_n_t _s_t_a_y_o_p_e_n)
21
22     _i_n_t
23     sseettggrreenntt(_v_o_i_d)
24
25     _v_o_i_d
26     eennddggrreenntt(_v_o_i_d)
27
28DDEESSCCRRIIPPTTIIOONN
29     These functions operate on the group database file /_e_t_c/_g_r_o_u_p which is
30     described in group(5).  Each line of the database is defined by the
31     structure _g_r_o_u_p found in the include file <_g_r_p._h>:
32
33           struct group {
34                   char    *gr_name;       /* group name */
35                   char    *gr_passwd;     /* group password */
36                   gid_t   gr_gid;         /* group id */
37                   char    **gr_mem;       /* group members */
38           };
39
40     The functions ggeettggrrnnaamm() and ggeettggrrggiidd() search the group database for the
41     given group name pointed to by _n_a_m_e or the group id pointed to by _g_i_d,
42     respectively, returning the first one encountered.  Identical group names
43     or group gids may result in undefined behavior.
44
45     The ggeettggrreenntt() function sequentially reads the group database and is
46     intended for programs that wish to step through the complete list of
47     groups.
48
49     All three routines will open the group file for reading, if necesssary.
50
51     The sseettggrroouuppeenntt() function opens the file, or rewinds it if it is already
52     open.  If _s_t_a_y_o_p_e_n is non-zero, file descriptors are left open,
53     significantly speeding functions subsequent calls.  This functionality is
54     unnecessary for ggeettggrreenntt() as it doesn't close its file descriptors by
55     default.  It should also be noted that it is dangerous for long-running
56     programs to use this functionality as the group file may be updated.
57
58     The sseettggrreenntt() function is identical to sseettggrroouuppeenntt() with an argument of
59     zero.
60
61     The eennddggrreenntt() function closes any open files.
62
63RREETTUURRNN VVAALLUUEESS
64     The functions ggeettggrreenntt(), ggeettggrrnnaamm(), and ggeettggrrggiidd(), return a pointer to
65     the group entry if successful; if end-of-file is reached or an error
66     occurs a null pointer is returned.  The functions sseettggrroouuppeenntt() and
67     sseettggrreenntt() return the value 1 if successful, otherwise the value 0 is
68     returned.  The functions eennddggrreenntt() and sseettggrrffiillee() have no return value.
69
70FFIILLEESS
71     /etc/group  group database file
72
73SSEEEE AALLSSOO
74     ggeettppwweenntt(_3), ggrroouupp(_5)
75
76HHIISSTTOORRYY
77     The functions eennddggrreenntt(), ggeettggrreenntt(), ggeettggrrnnaamm(), ggeettggrrggiidd(), and
78     sseettggrreenntt() appeared in Version 7 AT&T UNIX.  The functions sseettggrrffiillee()
79     and sseettggrroouuppeenntt() appeared in 4.3BSD-Reno.
80
81CCOOMMPPAATTIIBBIILLIITTYY
82     The historic function sseettggrrffiillee(), which allowed the specification of
83     alternate password databases, has been deprecated and is no longer
84     available.
85
86BBUUGGSS
87     The functions ggeettggrreenntt(), ggeettggrrnnaamm(), ggeettggrrggiidd(), sseettggrroouuppeenntt() and
88     sseettggrreenntt() leave their results in an internal static object and return a
89     pointer to that object. Subsequent calls to the same function will modify
90     the same object.
91
92     The functions ggeettggrreenntt(), eennddggrreenntt(), sseettggrroouuppeenntt(), and sseettggrreenntt() are
93     fairly useless in a networked environment and should be avoided, if
94     possible.
95
96BSD Experimental                April 20, 1991                               2
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133