]> git.saurik.com Git - apple/libinfo.git/blob - lookup.subproj/getgrent.3
Libinfo-459.tar.gz
[apple/libinfo.git] / lookup.subproj / 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 .\" 4. 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: src/lib/libc/gen/getgrent.3,v 1.28 2007/01/09 00:27:53 imp Exp $
30 .\"
31 .\" @APPLE_LICENSE_HEADER_START@
32 .\"
33 .\" Portions Copyright (c) 2003-2013 Apple Inc. All Rights Reserved.
34 .\"
35 .\" This file contains Original Code and/or Modifications of Original Code
36 .\" as defined in and that are subject to the Apple Public Source License
37 .\" Version 2.0 (the 'License'). You may not use this file except in
38 .\" compliance with the License. Please obtain a copy of the License at
39 .\" http://www.opensource.apple.com/apsl/ and read it before using this
40 .\" file.
41 .\"
42 .\" The Original Code and all software distributed under the License are
43 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
44 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
45 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
46 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
47 .\" Please see the License for the specific language governing rights and
48 .\" limitations under the License.
49 .\"
50 .\" @APPLE_LICENSE_HEADER_END@
51 .\"
52 .Dd October 26, 2011
53 .Dt GETGRENT 3
54 .Os
55 .Sh NAME
56 .Nm getgrent ,
57 .\".Nm getgrent_r ,
58 .Nm getgrnam ,
59 .Nm getgrnam_r ,
60 .Nm getgrgid ,
61 .Nm getgrgid_r ,
62 .Nm getgruuid ,
63 .Nm getgruuid_r ,
64 .Nm setgroupent ,
65 .Nm setgrent ,
66 .Nm endgrent
67 .Nd group database operations
68 .Sh LIBRARY
69 Standard system libraries.
70 .Sh SYNOPSIS
71 .In grp.h
72 .In uuid/uuid.h
73 .Ft struct group *
74 .Fn getgrent void
75 .\".Ft int
76 .\".Fn getgrent_r "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
77 .Ft struct group *
78 .Fn getgrnam "const char *name"
79 .Ft int
80 .Fn getgrnam_r "const char *name" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
81 .Ft struct group *
82 .Fn getgrgid "gid_t gid"
83 .Ft int
84 .Fn getgrgid_r "gid_t gid" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
85 .Ft int
86 .Fn getgruuid "uuid_t uuid"
87 .Ft int
88 .Fn getgruuid_r "uuid_t uuid" "struct group *grp" "char *buffer" "size_t bufsize" "struct group **result"
89 .Ft int
90 .Fn setgroupent "int stayopen"
91 .Ft void
92 .Fn setgrent void
93 .Ft void
94 .Fn endgrent void
95 .Sh DESCRIPTION
96 .\"These functions operate on the group database file
97 These functions obtain information from
98 .Xr opendirectoryd 8 ,
99 including records in
100 .Pa /etc/group
101 which is described
102 in
103 .Xr group 5 .
104 Each line of the database is defined by the structure
105 .Vt group
106 found in the include
107 file
108 .In grp.h :
109 .Bd -literal -offset indent
110 struct group {
111 char *gr_name; /* group name */
112 char *gr_passwd; /* group password */
113 gid_t gr_gid; /* group id */
114 char **gr_mem; /* group members */
115 };
116 .Ed
117 .Pp
118 The functions
119 .Fn getgrnam ,
120 .Fn getgrgid ,
121 and
122 .Fn getgruuid
123 search the group database for the given group name pointed to by
124 .Fa name ,
125 the group id given by
126 .Fa gid ,
127 or the UUID given by
128 .Fa uuid
129 respectively, returning the first one encountered.
130 Identical group
131 names, group gids, or uuids may result in undefined behavior.
132 .Pp
133 Note that the groups file
134 .Pa /etc/group
135 does not contain group UUIDs.
136 The UUID for a group may be found using
137 .Fn mbr_gid_to_uuid .
138 .Pp
139 On OS X, these routines are thread-safe and return a pointer to a
140 thread-specific data structure. The contents of this data
141 structure are automatically released by subsequent calls to
142 any of these routines on the same thread, or when the thread exits.
143 These routines are therefore unsuitable for use in libraries or frameworks,
144 from where they may overwrite the per-thread data that the calling
145 application expects to find as a result of its own calls to these
146 routines. Library and framework code should use the alternative reentrant
147 variants detailed below.
148 .Pp
149 The
150 .Fn getgrent
151 function
152 searches all available directory services on it's first invocation.
153 It caches the returned entries in a list
154 and returns group entries one at a time.
155 .Pp
156 .Em NOTE
157 that
158 .Fn getgrent
159 may cause a very lengthy search for group records by
160 .Nm opendirectoryd
161 and may result in a large number of group records being cached
162 by the calling process.
163 Use of this function is not advised.
164 .Pp
165 The functions
166 .Fn getgrnam_r ,
167 .Fn getgrgid_r ,
168 and
169 .Fn getgruuid_r
170 are alternative versions of
171 .Fn getgrnam ,
172 .Fn getgrgid ,
173 and
174 .Fn getgruuid
175 respectively.
176 The caller must provide storage for the results of the search in
177 the
178 .Fa grp ,
179 .Fa buffer ,
180 .Fa bufsize ,
181 and
182 .Fa result
183 arguments.
184 When these functions are successful, the
185 .Fa grp
186 argument will be filled-in, and a pointer to that argument will be
187 stored in
188 .Fa result .
189 If an entry is not found or an error occurs,
190 .Fa result
191 will be set to
192 .Dv NULL .
193 .Pp
194 These functions will open the group file for reading, if necessary.
195 .Pp
196 The
197 .Fn setgroupent
198 function causes
199 .Fn getgrent
200 to ``rewind'' to the beginning of the list of entries cached by a previous
201 .Fn getgrent
202 call.
203 The cache is not cleared.
204 The
205 .Fa stayopen
206 parameter value is unused on OS X.
207 .Pp
208 The
209 .Fn setgrent
210 and
211 .Fn endgrent
212 functions clear the cached results from a previous
213 .Fn getgrent
214 call.
215 .Sh RETURN VALUES
216 The functions
217 .Fn getgrent ,
218 .Fn getgrnam ,
219 and
220 .Fn getgrgid ,
221 return a pointer to a group structure on success or
222 .Dv NULL
223 if the entry is not found or if an error occurs.
224 If an error does occur,
225 .Va errno
226 will be set.
227 Note that programs must explicitly set
228 .Va errno
229 to zero before calling any of these functions if they need to
230 distinguish between a non-existent entry and an error.
231 The functions
232 .Fn getgrnam_r ,
233 .Fn getgrgid_r ,
234 and
235 .Fn getgruuid_r
236 return 0 if no error occurred, or an error number to indicate failure.
237 It is not an error if a matching entry is not found.
238 (Thus, if
239 .Fa result
240 is set to
241 .Dv NULL
242 and the return value is 0, no matching entry exists.)
243 .Pp
244 .Fn setgroupent
245 returns the value 1 if successful, otherwise the value
246 0 is returned.
247 The functions
248 .Fn setgrent ,
249 .Fn endgrent ,
250 and
251 .Fn setgrfile
252 have no return value.
253 .Sh FILES
254 .Bl -tag -width /etc/group -compact
255 .It Pa /etc/group
256 group database file
257 .El
258 .Sh COMPATIBILITY
259 The historic function
260 .Fn setgrfile ,
261 which allowed the specification of alternate group databases, has
262 been deprecated and is no longer available.
263 .Sh SEE ALSO
264 .Xr getpwent 3 ,
265 .Xr group 5 ,
266 .Xr mbr_gid_to_uuid 3,
267 .Xr opendirectory 8 ,
268 .Xr yp 8
269 .Sh STANDARDS
270 The
271 .Fn getgrent ,
272 .Fn getgrnam ,
273 .Fn getgrnam_r ,
274 .Fn getgrgid ,
275 .Fn getgrgid_r
276 and
277 .Fn endgrent
278 functions conform to
279 .St -p1003.1-96 .
280 The
281 .Fn setgrent
282 function differs from that standard in that its return type is
283 .Vt int
284 rather than
285 .Vt void .
286 .Sh HISTORY
287 The functions
288 .Fn endgrent ,
289 .Fn getgrent ,
290 .Fn getgrnam ,
291 .Fn getgrgid ,
292 and
293 .Fn setgrent
294 appeared in
295 .At v7 .
296 The functions
297 .Fn setgrfile
298 and
299 .Fn setgroupent
300 appeared in
301 .Bx 4.3 Reno .
302 The functions
303 .\".Fn getgrent_r ,
304 .\".Fn getgrnam_r ,
305 .Fn getgrnam_r
306 and
307 .Fn getgrgid_r
308 appeared in
309 .Fx 5.1 .
310 The functions
311 .Fn getgruuid
312 and
313 .Fn getgruuid_r
314 appeared in Mac OS X 10.8.
315 .Sh BUGS
316 The functions
317 .Fn getgrent ,
318 .Fn getgrnam ,
319 .Fn getgrgid ,
320 .Fn getgruuid ,
321 .Fn setgroupent
322 and
323 .Fn setgrent
324 leave their results in an internal thread-specific memory and return
325 a pointer to that object.
326 Subsequent calls to
327 the same function
328 will modify the same object.