| blob | 944cf9138300c4c91b5c808f238fb8659cb2a465 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
45 .\" Portions Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
46 .\"
47 .TH GETGRNAM 3C "Feb 25, 2017"
48 .SH NAME
49 getgrnam, getgrnam_r, getgrent, getgrent_r, getgrgid, getgrgid_r, setgrent,
50 endgrent, fgetgrent, fgetgrent_r \- group database entry functions
51 .SH SYNOPSIS
52 .LP
53 .nf
54 #include <grp.h>
56 \fBstruct group *\fR\fBgetgrnam\fR(\fBconst char *\fR\fIname\fR);
57 .fi
59 .LP
60 .nf
61 \fBstruct group *\fR\fBgetgrnam_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct group *\fR\fIgrp\fR,
62 \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbufsize\fR);
63 .fi
65 .LP
66 .nf
67 \fBstruct group *\fR\fBgetgrent\fR(\fBvoid\fR);
68 .fi
70 .LP
71 .nf
72 \fBstruct group *\fR\fBgetgrent_r\fR(\fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbufsize\fR);
73 .fi
75 .LP
76 .nf
77 \fBstruct group *\fR\fBgetgrgid\fR(\fBgid_t\fR \fIgid\fR);
78 .fi
80 .LP
81 .nf
82 \fBstruct group *\fR\fBgetgrgid_r\fR(\fBgid_t\fR \fIgid\fR, \fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR,
83 \fBint\fR \fIbufsize\fR);
84 .fi
86 .LP
87 .nf
88 \fBvoid\fR \fBsetgrent\fR(\fBvoid\fR);
89 .fi
91 .LP
92 .nf
93 \fBvoid\fR \fBendgrent\fR(\fBvoid\fR);
94 .fi
96 .LP
97 .nf
98 \fBstruct group *\fR\fBfgetgrent\fR(\fBFILE *\fR\fIf\fR);
99 .fi
101 .LP
102 .nf
103 \fBstruct group *\fR\fBfgetgrent_r\fR(\fBFILE *\fR\fIf\fR, \fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR,
104 \fBint\fR \fIbufsize\fR);
105 .fi
107 .SS "Standard conforming"
108 .LP
109 .nf
110 cc [ \fIflag\fR... ] \fIfile\fR... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary\fR... ]
112 \fBint\fR \fBgetgrnam_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR,
113 \fBsize_t\fR \fIbufsize\fR, \fBstruct group **\fR\fIresult\fR);
114 .fi
116 .LP
117 .nf
118 \fBint\fR \fBgetgrgid_r\fR(\fBgid_t\fR \fIgid\fR, \fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR,
119 \fBsize_t\fR \fIbufsize\fR, \fBstruct group **\fR\fIresult\fR);
120 .fi
122 .SH DESCRIPTION
123 .LP
124 These functions are used to obtain entries describing user groups. Entries can
125 come from any of the sources for \fBgroup\fR specified in the
126 \fB/etc/nsswitch.conf\fR file (see \fBnsswitch.conf\fR(4)).
127 .sp
128 .LP
129 The \fBgetgrnam()\fR function searches the group database for an entry with the
130 group name specified by the character string parameter \fIname\fR.
131 .sp
132 .LP
133 The \fBgetgrgid()\fR function searches the group database for an entry with the
134 (numeric) group id specified by \fIgid\fR.
135 .sp
136 .LP
137 The \fBsetgrent()\fR, \fBgetgrent()\fR, and \fBendgrent()\fR functions are used
138 to enumerate group entries from the database.
139 .sp
140 .LP
141 The \fBsetgrent()\fR function effectively rewinds the group database to allow
142 repeated searches. It sets (or resets) the enumeration to the beginning of the
143 set of group entries. This function should be called before the first call to
144 \fBgetgrent()\fR.
145 .sp
146 .LP
147 The \fBgetgrent()\fR function returns a pointer to a structure containing the
148 broken-out fields of an entry in the group database. When first called,
149 \fBgetgrent()\fR returns a pointer to a \fBgroup\fR structure containing the
150 next group structure in the group database. Successive calls can be used to
151 search the entire database.
152 .sp
153 .LP
154 The \fBendgrent()\fR function can be called to close the group database and
155 deallocate resources when processing is complete. It is permissible, though
156 possibly less efficient, for the process to call more group functions after
157 calling \fBendgrent()\fR.
158 .sp
159 .LP
160 The \fBfgetgrent()\fR function, unlike the other functions above, does not use
161 \fBnsswitch.conf\fR. It reads and parses the next line from the stream \fIf\fR,
162 which is assumed to have the format of the \fBgroup\fR file (see
163 \fBgroup\fR(4)).
164 .SS "Reentrant Interfaces"
165 .LP
166 The \fBgetgrnam()\fR, \fBgetgrgid()\fR, \fBgetgrent()\fR, and
167 \fBfgetgrent()\fR functions use thread-specific storage that is reused in each
168 call to one of these functions by the same thread, making them safe to use but
169 not recommended for multithreaded applications.
170 .sp
171 .LP
172 The parallel functions \fBgetgrnam_r()\fR, \fBgetgrgid_r()\fR,
173 \fBgetgrent_r()\fR, and \fBfgetgrent_r()\fR provide reentrant interfaces for
174 these operations.
175 .sp
176 .LP
177 Each reentrant interface performs the same operation as its non-reentrant
178 counterpart, named by removing the \fB_r\fR suffix. The reentrant interfaces,
179 however, use buffers supplied by the caller to store returned results instead
180 of using thread-specific data that can be overwritten by each call. They are
181 safe for use in both single-threaded and multithreaded applications.
182 .sp
183 .LP
184 Each reentrant interface takes the same arguments as its non-reentrant
185 counterpart, as well as the following additional parameters. The \fIgrp\fR
186 argument must be a pointer to a \fBstruct group\fR structure allocated by the
187 caller. On successful completion, the function returns the group entry in this
188 structure. Storage referenced by the group structure is allocated from the
189 memory provided with the \fIbuffer\fR argument that is \fIbufsize\fR characters
190 in size. The maximum size needed for this buffer can be determined with the
191 \fB_SC_GETGR_R_SIZE_MAX\fR \fBsysconf\fR(3C) parameter. The standard-conforming
192 versions place a pointer to the modified \fIgrp\fR structure in the
193 \fIresult\fR parameter, instead of returning a pointer to this structure. A
194 null pointer is returned at the location pointed to by \fIresult\fR on error or
195 if the requested entry is not found.
196 .sp
197 .LP
198 For enumeration in multithreaded applications, the position within the
199 enumeration is a process-wide property shared by all threads. The
200 \fBsetgrent()\fR function can be used in a multithreaded application but resets
201 the enumeration position for all threads. If multiple threads interleave calls
202 to \fBgetgrent_r()\fR, the threads will enumerate disjoint subsets of the group
203 database. Like their non-reentrant counterparts, \fBgetgrnam_r()\fR and
204 \fBgetgrgid_r()\fR leave the enumeration position in an indeterminate state.
205 .SS "group Structure"
206 .LP
207 Group entries are represented by the \fBstruct group\fR structure defined in
208 <\fBgrp.h\fR>:
209 .sp
210 .in +2
211 .nf
212 struct group {
213 char *gr_name; /* the name of the group */
214 char *gr_passwd; /* the encrypted group password */
215 gid_t gr_gid; /* the numerical group ID */
216 char **gr_mem; /* vector of pointers to member
217 names */
218 };
219 .fi
220 .in -2
222 .SH RETURN VALUES
223 .LP
224 The \fBgetgrnam()\fR, \fBgetgrnam_r()\fR, \fBgetgrgid()\fR, and
225 \fBgetgrgid_r()\fR functions each return a pointer to a \fBstruct group\fR if
226 they successfully locate the requested entry. They return a null pointer if
227 either the requested entry was not found or an error occurred. On error,
228 \fBerrno\fR is set to indicate the error. The standard-conforming functions
229 \fBgetgrnam_r()\fR and \fBgetgrgid_r()\fR return \fB0\fR upon success or an
230 error number in case of failure.
231 .sp
232 .LP
233 The \fBgetgrent()\fR, \fBgetgrent_r()\fR, \fBfgetgrent()\fR, and
234 \fBfgetgrent_r()\fR functions each return a pointer to a \fBstruct group\fR if
235 they successfully enumerate an entry; otherwise they return a null pointer on
236 end-of-file or error. On error, \fBerrno\fR is set to indicate the error.
237 .sp
238 .LP
239 The \fBgetgrnam()\fR, \fBgetgrgid()\fR, \fBgetgrent()\fR, and \fBfgetgrent()\fR
240 functions use thread-specific data storage, so returned data must be copied
241 before a subsequent call to any of these functions if the data are to be saved.
242 .sp
243 .LP
244 When the pointer returned by the reentrant functions \fBgetgrnam_r()\fR,
245 \fBgetgrgid_r()\fR, \fBgetgrent_r()\fR, and \fBfgetgrent_r()\fR is non-null, it
246 is always equal to the \fIgrp\fR pointer that was supplied by the caller.
247 .sp
248 .LP
249 Applications wishing to check for error situations should set \fBerrno\fR to 0
250 before calling \fBgetgrnam()\fR, \fBgetgrnam_r()\fR, \fBgetgrent()\fR,
251 \fBgetgrent_r()\fR\fBgetgrgid()\fR, \fBgetgrgid_r()\fR, \fBfgetgrent()\fR, and
252 \fBfgetgrent_r()\fR. If these functions return a null pointer and \fBerrno\fR
253 is non-zero, an error occurred.
254 .SH ERRORS
255 .LP
256 The \fBgetgrent_r()\fR, \fBfgetgrent()\fR, and \fBfgetgrent_r()\fR functions
257 will fail if:
258 .sp
259 .ne 2
260 .na
261 \fB\fBEIO\fR\fR
262 .ad
263 .RS 10n
264 An I/O error has occurred.
265 .RE
267 .sp
268 .ne 2
269 .na
270 \fB\fBERANGE\fR\fR
271 .ad
272 .RS 10n
273 Insufficient storage was supplied by \fIbuffer\fR and \fIbufsize\fR to contain
274 the data to be referenced by the resulting \fBgroup\fR structure.
275 .RE
277 .sp
278 .LP
279 The \fBgetgrent_r()\fR function will fail if:
280 .sp
281 .ne 2
282 .na
283 \fB\fBEMFILE\fR\fR
284 .ad
285 .RS 10n
286 There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling
287 process.
288 .RE
290 .sp
291 .ne 2
292 .na
293 \fB\fBENFILE\fR\fR
294 .ad
295 .RS 10n
296 The maximum allowable number of files is currently open in the system.
297 .RE
299 .sp
300 .LP
301 The \fBgetgrnam()\fR, \fBgetgrnam_r()\fR, \fBgetgrgid()\fR, \fBgetgrgid_r()\fR,
302 and \fBgetgrent()\fR functions may fail if:
303 .sp
304 .ne 2
305 .na
306 \fB\fBEINTR\fR\fR
307 .ad
308 .RS 10n
309 A signal was caught during the operation.
310 .RE
312 .sp
313 .ne 2
314 .na
315 \fB\fBEIO\fR\fR
316 .ad
317 .RS 10n
318 An I/O error has occurred.
319 .RE
321 .sp
322 .ne 2
323 .na
324 \fB\fBEMFILE\fR\fR
325 .ad
326 .RS 10n
327 There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling
328 process.
329 .RE
331 .sp
332 .ne 2
333 .na
334 \fB\fBENFILE\fR\fR
335 .ad
336 .RS 10n
337 The maximum allowable number of files is currently open in the system.
338 .RE
340 .sp
341 .LP
342 The \fBgetgrnam_r()\fR and \fBgetgrgid_r()\fR functions may fail if:
343 .sp
344 .ne 2
345 .na
346 \fB\fBERANGE\fR\fR
347 .ad
348 .RS 10n
349 Insufficient storage was supplied by \fIbuffer\fR and \fIbufsize\fR to contain
350 the data to be referenced by the resulting \fBgroup\fR structure.
351 .RE
353 .SH ATTRIBUTES
354 .LP
355 See \fBattributes\fR(5) for descriptions of the following attributes:
356 .sp
358 .sp
359 .TS
360 box;
361 c | c
362 l | l .
363 ATTRIBUTE TYPE ATTRIBUTE VALUE
364 _
365 Interface Stability See below.
366 _
367 MT-Level See \fBReentrant Interfaces\fR in \fBDESCRIPTION\fR.
368 .TE
370 .sp
371 .LP
372 The \fBendgrent()\fR, \fBgetgrent()\fR, \fBgetgrgid()\fR, \fBgetgrgid_r()\fR,
373 \fBgetgrnam()\fR, \fBgetgrnam_r()\fR, and \fBsetgrent()\fR functions are
374 Standard.
375 .SH SEE ALSO
376 .LP
377 \fBIntro\fR(3), \fBgetpwnam\fR(3C), \fBgroup\fR(4), \fBnsswitch.conf\fR(4),
378 \fBpasswd\fR(4), \fBattributes\fR(5), \fBstandards\fR(5)
379 .SH NOTES
380 .LP
381 When compiling multithreaded programs, see \fBIntro\fR(3).
382 .sp
383 .LP
384 Use of the enumeration interfaces \fBgetgrent()\fR and \fBgetgrent_r()\fR is
385 discouraged; enumeration is supported for the group file and \fBNIS\fR
386 but in general is not efficient and might not be supported for all
387 database sources. The semantics of enumeration are discussed further in
388 \fBnsswitch.conf\fR(4).
389 .sp
390 .LP
391 Previous releases allowed the use of ``+'' and ``-'' entries in
392 \fB/etc/group\fR to selectively include and exclude entries from \fBNIS.\fR The
393 primary usage of these entries is superseded by the name service switch, so the
394 ``+/-'' form might not be supported in future releases.
395 .sp
396 .LP
397 If required, the ``+/-'' functionality can still be obtained for \fBNIS\fR by
398 specifying \fBcompat\fR as the source for \fBgroup\fR.
399 .sp
400 .LP
401 If the ``+/-'' functionality is required in conjunction with \fBLDAP,\fR
402 specify both \fBcompat\fR as the source for \fBgroup\fR and \fBldap\fR as
403 the source for the pseudo-database \fBgroup_compat\fR. See \fBgroup\fR(4), and
404 \fBnsswitch.conf\fR(4) for details.
405 .sp
406 .LP
407 Solaris 2.4 and earlier releases provided definitions of the \fBgetgrnam_r()\fR
408 and \fBgetgrgid_r()\fR functions as specified in POSIX.1c Draft 6. The final
409 POSIX.1c standard changed the interface for these functions. Support for the
410 Draft 6 interface is provided for compatibility only and might not be supported
411 in future releases. New applications and libraries should use the
412 standard-conforming interface.
413 .sp
414 .LP
415 For POSIX.1c-conforming applications, the \fB_POSIX_PTHREAD_SEMANTICS\fR and
416 \fB_REENTRANT\fR flags are automatically turned on by defining the
417 \fB_POSIX_C_SOURCE\fR flag with a value \(>=199506L.