]> git.saurik.com Git - apple/libinfo.git/blob - lookup.subproj/getgrent.3
Libinfo-391.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 .Dd April 16, 2003
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 These functions obtain information from
70 .Xr DirectoryService 8 ,
71 including records in
72 .Pa /etc/group
73 which is described
74 in
75 .Xr group 5 .
76 Each line of the database is defined by the structure
77 .Vt group
78 found in the include
79 file
80 .In grp.h :
81 .Bd -literal -offset indent
82 struct group {
83 char *gr_name; /* group name */
84 char *gr_passwd; /* group password */
85 gid_t gr_gid; /* group id */
86 char **gr_mem; /* group members */
87 };
88 .Ed
89 .Pp
90 The functions
91 .Fn getgrnam
92 and
93 .Fn getgrgid
94 search the group database for the given group name pointed to by
95 .Fa name
96 or the group id pointed to by
97 .Fa gid ,
98 respectively, returning the first one encountered.
99 Identical group
100 names or group gids may result in undefined behavior.
101 .Pp
102 On Mac OS X, these routines are thread-safe and return a pointer to a
103 thread-specific data structure. The contents of this data
104 structure are automatically released by subsequent calls to
105 any of these routines on the same thread, or when the thread exits.
106 .Pp
107 The
108 .Fn getgrent
109 function
110 sequentially reads the group database and is intended for programs
111 that wish to step through the complete list of groups.
112 .Pp
113 The functions
114 .\".Fn getgrent_r ,
115 .\".Fn getgrnam_r ,
116 .Fn getgrnam_r
117 and
118 .Fn getgrgid_r
119 are thread-safe versions of
120 .\".Fn getgrent ,
121 .\".Fn getgrnam ,
122 .Fn getgrnam
123 and
124 .Fn getgrgid ,
125 respectively.
126 The caller must provide storage for the results of the search in
127 the
128 .Fa grp ,
129 .Fa buffer ,
130 .Fa bufsize ,
131 and
132 .Fa result
133 arguments.
134 When these functions are successful, the
135 .Fa grp
136 argument will be filled-in, and a pointer to that argument will be
137 stored in
138 .Fa result .
139 If an entry is not found or an error occurs,
140 .Fa result
141 will be set to
142 .Dv NULL .
143 .Pp
144 These functions will open the group file for reading, if necessary.
145 .Pp
146 The
147 .Fn setgroupent
148 function
149 opens the file, or rewinds it if it is already open.
150 If
151 .Fa stayopen
152 is non-zero, file descriptors are left open, significantly speeding
153 functions subsequent calls.
154 This functionality is unnecessary for
155 .Fn getgrent
156 as it does not close its file descriptors by default.
157 It should also
158 be noted that it is dangerous for long-running programs to use this
159 functionality as the group file may be updated.
160 .Pp
161 The
162 .Fn setgrent
163 function
164 is identical to
165 .Fn setgroupent
166 with an argument of zero.
167 .Pp
168 The
169 .Fn endgrent
170 function
171 closes any open files.
172 .Sh RETURN VALUES
173 The functions
174 .Fn getgrent ,
175 .Fn getgrnam ,
176 and
177 .Fn getgrgid ,
178 return a pointer to a group structure on success or
179 .Dv NULL
180 if the entry is not found or if an error occurs.
181 If an error does occur,
182 .Va errno
183 will be set.
184 Note that programs must explicitly set
185 .Va errno
186 to zero before calling any of these functions if they need to
187 distinguish between a non-existent entry and an error.
188 The functions
189 .\".Fn getgrent_r ,
190 .\".Fn getgrnam_r ,
191 .Fn getgrnam_r
192 and
193 .Fn getgrgid_r
194 return 0 if no error occurred, or an error number to indicate failure.
195 It is not an error if a matching entry is not found.
196 (Thus, if
197 .Fa result
198 is set to
199 .Dv NULL
200 and the return value is 0, no matching entry exists.)
201 .Pp
202 .Fn setgroupent
203 returns the value 1 if successful, otherwise the value
204 0 is returned.
205 The functions
206 .Fn setgrent ,
207 .Fn endgrent ,
208 and
209 .Fn setgrfile
210 have no return value.
211 .Sh FILES
212 .Bl -tag -width /etc/group -compact
213 .It Pa /etc/group
214 group database file
215 .El
216 .Sh COMPATIBILITY
217 The historic function
218 .Fn setgrfile ,
219 which allowed the specification of alternate password databases, has
220 been deprecated and is no longer available.
221 .Sh SEE ALSO
222 .Xr getpwent 3 ,
223 .Xr group 5 ,
224 .\".Xr nsswitch.conf 5 ,
225 .Xr DirectoryService 8 ,
226 .Xr yp 8
227 .Sh STANDARDS
228 The
229 .Fn getgrent ,
230 .Fn getgrnam ,
231 .Fn getgrnam_r ,
232 .Fn getgrgid ,
233 .Fn getgrgid_r
234 and
235 .Fn endgrent
236 functions conform to
237 .St -p1003.1-96 .
238 The
239 .Fn setgrent
240 function differs from that standard in that its return type is
241 .Vt int
242 rather than
243 .Vt void .
244 .Sh HISTORY
245 The functions
246 .Fn endgrent ,
247 .Fn getgrent ,
248 .Fn getgrnam ,
249 .Fn getgrgid ,
250 and
251 .Fn setgrent
252 appeared in
253 .At v7 .
254 The functions
255 .Fn setgrfile
256 and
257 .Fn setgroupent
258 appeared in
259 .Bx 4.3 Reno .
260 The functions
261 .\".Fn getgrent_r ,
262 .\".Fn getgrnam_r ,
263 .Fn getgrnam_r
264 and
265 .Fn getgrgid_r
266 appeared in
267 .Fx 5.1 .
268 .Sh BUGS
269 The functions
270 .Fn getgrent ,
271 .Fn getgrnam ,
272 .Fn getgrgid ,
273 .Fn setgroupent
274 and
275 .Fn setgrent
276 leave their results in an internal thread-specific memory and return
277 a pointer to that object.
278 Subsequent calls to
279 the same function
280 will modify the same object.
281 .\".Pp
282 .\"The functions
283 .\".Fn getgrent ,
284 .\".Fn getgrent_r ,
285 .\".Fn endgrent ,
286 .\".Fn setgroupent ,
287 .\"and
288 .\".Fn setgrent
289 .\"are fairly useless in a networked environment and should be
290 .\"avoided, if possible.
291 .\"The
292 .\".Fn getgrent
293 .\"and
294 .\".Fn getgrent_r
295 .\"functions
296 .\"make no attempt to suppress duplicate information if multiple
297 .\"sources are specified in
298 .\".Xr nsswitch.conf 5 .