]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - lib/libc/gen/getgrent.3
Add a missing Nm macro
[FreeBSD/FreeBSD.git] / lib / libc / gen / getgrent.3
1 .\" Copyright (c) 1989, 1991, 1993
2 .\"     The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\"    may be used to endorse or promote products derived from this software
14 .\"    without specific prior written permission.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\"     From: @(#)getgrent.3    8.2 (Berkeley) 4/19/94
29 .\" $FreeBSD$
30 .\"
31 .Dd July 31, 2016
32 .Dt GETGRENT 3
33 .Os
34 .Sh NAME
35 .Nm getgrent ,
36 .Nm getgrent_r ,
37 .Nm getgrnam ,
38 .Nm getgrnam_r ,
39 .Nm getgrgid ,
40 .Nm getgrgid_r ,
41 .Nm setgroupent ,
42 .Nm setgrent ,
43 .Nm endgrent
44 .Nd group database operations
45 .Sh LIBRARY
46 .Lb libc
47 .Sh SYNOPSIS
48 .In grp.h
49 .Ft struct group *
50 .Fn getgrent void
51 .Ft int
52 .Fn getgrent_r "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
53 .Ft struct group *
54 .Fn getgrnam "const char *name"
55 .Ft int
56 .Fn getgrnam_r "const char *name" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
57 .Ft struct group *
58 .Fn getgrgid "gid_t gid"
59 .Ft int
60 .Fn getgrgid_r "gid_t gid" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
61 .Ft int
62 .Fn setgroupent "int stayopen"
63 .Ft void
64 .Fn setgrent void
65 .Ft void
66 .Fn endgrent void
67 .Sh DESCRIPTION
68 These functions operate on the group database file
69 .Pa /etc/group
70 which is described
71 in
72 .Xr group 5 .
73 Each line of the database is defined by the structure
74 .Vt group
75 found in the include
76 file
77 .In grp.h :
78 .Bd -literal -offset indent
79 struct group {
80         char    *gr_name;       /* group name */
81         char    *gr_passwd;     /* group password */
82         gid_t   gr_gid;         /* group id */
83         char    **gr_mem;       /* group members */
84 };
85 .Ed
86 .Pp
87 The functions
88 .Fn getgrnam
89 and
90 .Fn getgrgid
91 search the group database for the given group name pointed to by
92 .Fa name
93 or the group id pointed to by
94 .Fa gid ,
95 respectively, returning the first one encountered.
96 Identical group
97 names or group gids may result in undefined behavior.
98 .Pp
99 The
100 .Fn getgrent
101 function
102 sequentially reads the group database and is intended for programs
103 that wish to step through the complete list of groups.
104 .Pp
105 The functions
106 .Fn getgrent_r ,
107 .Fn getgrnam_r ,
108 and
109 .Fn getgrgid_r
110 are thread-safe versions of
111 .Fn getgrent ,
112 .Fn getgrnam ,
113 and
114 .Fn getgrgid ,
115 respectively.
116 The caller must provide storage for the results of the search in
117 the
118 .Fa grp ,
119 .Fa buffer ,
120 .Fa bufsize ,
121 and
122 .Fa result
123 arguments.
124 When these functions are successful, the
125 .Fa grp
126 argument will be filled-in, and a pointer to that argument will be
127 stored in
128 .Fa result .
129 If an entry is not found or an error occurs,
130 .Fa result
131 will be set to
132 .Dv NULL .
133 .Pp
134 These functions will open the group file for reading, if necessary.
135 .Pp
136 The
137 .Fn setgroupent
138 function
139 opens the file, or rewinds it if it is already open.
140 If
141 .Fa stayopen
142 is non-zero, file descriptors are left open, significantly speeding
143 functions subsequent calls.
144 This functionality is unnecessary for
145 .Fn getgrent
146 as it does not close its file descriptors by default.
147 It should also
148 be noted that it is dangerous for long-running programs to use this
149 functionality as the group file may be updated.
150 .Pp
151 The
152 .Fn setgrent
153 function
154 is identical to
155 .Fn setgroupent
156 with an argument of zero.
157 .Pp
158 The
159 .Fn endgrent
160 function
161 closes any open files.
162 .Sh RETURN VALUES
163 The functions
164 .Fn getgrent ,
165 .Fn getgrnam ,
166 and
167 .Fn getgrgid ,
168 return a pointer to a group structure on success or
169 .Dv NULL
170 if the entry is not found or if an error occurs.
171 If an error does occur,
172 .Va errno
173 will be set.
174 Note that programs must explicitly set
175 .Va errno
176 to zero before calling any of these functions if they need to
177 distinguish between a non-existent entry and an error.
178 The functions
179 .Fn getgrent_r ,
180 .Fn getgrnam_r ,
181 and
182 .Fn getgrgid_r
183 return 0 if no error occurred, or an error number to indicate failure.
184 It is not an error if a matching entry is not found.
185 (Thus, if
186 .Fa result
187 is set to
188 .Dv NULL
189 and the return value is 0, no matching entry exists.)
190 .Pp
191 The function
192 .Fn setgroupent
193 returns the value 1 if successful, otherwise the value
194 0 is returned.
195 The functions
196 .Fn endgrent ,
197 .Fn setgrent
198 and
199 .Fn setgrfile
200 have no return value.
201 .Sh FILES
202 .Bl -tag -width /etc/group -compact
203 .It Pa /etc/group
204 group database file
205 .El
206 .Sh COMPATIBILITY
207 The historic function
208 .Fn setgrfile ,
209 which allowed the specification of alternate password databases, has
210 been deprecated and is no longer available.
211 .Sh SEE ALSO
212 .Xr getpwent 3 ,
213 .Xr group 5 ,
214 .Xr nsswitch.conf 5 ,
215 .Xr yp 8
216 .Sh STANDARDS
217 The
218 .Fn getgrent ,
219 .Fn getgrnam ,
220 .Fn getgrnam_r ,
221 .Fn getgrgid ,
222 .Fn getgrgid_r
223 and
224 .Fn endgrent
225 functions conform to
226 .St -p1003.1-96 .
227 The
228 .Fn setgrent
229 function differs from that standard in that its return type is
230 .Vt int
231 rather than
232 .Vt void .
233 .Sh HISTORY
234 The functions
235 .Fn endgrent ,
236 .Fn getgrent ,
237 .Fn getgrnam ,
238 .Fn getgrgid ,
239 and
240 .Fn setgrent
241 appeared in
242 .At v7 .
243 The functions
244 .Fn setgrfile
245 and
246 .Fn setgroupent
247 appeared in
248 .Bx 4.3 Reno .
249 The functions
250 .Fn getgrent_r ,
251 .Fn getgrnam_r ,
252 and
253 .Fn getgrgid_r
254 appeared in
255 .Fx 5.1 .
256 .Sh BUGS
257 The functions
258 .Fn getgrent ,
259 .Fn getgrnam ,
260 .Fn getgrgid ,
261 .Fn setgroupent
262 and
263 .Fn setgrent
264 leave their results in an internal static object and return
265 a pointer to that object.
266 Subsequent calls to
267 the same function
268 will modify the same object.
269 .Pp
270 The functions
271 .Fn getgrent ,
272 .Fn getgrent_r ,
273 .Fn endgrent ,
274 .Fn setgroupent ,
275 and
276 .Fn setgrent
277 are fairly useless in a networked environment and should be
278 avoided, if possible.
279 The
280 .Fn getgrent
281 and
282 .Fn getgrent_r
283 functions
284 make no attempt to suppress duplicate information if multiple
285 sources are specified in
286 .Xr nsswitch.conf 5 .