]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da MK |
24 | .\" |
25 | .\" References consulted: | |
26 | .\" Linux libc source code | |
27 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
28 | .\" 386BSD man pages | |
29 | .\" Modified Sat Jul 24 19:29:54 1993 by Rik Faith (faith@cs.unc.edu) | |
4b8c67d9 | 30 | .TH GETGRENT 3 2017-09-15 "" "Linux Programmer's Manual" |
fea681da MK |
31 | .SH NAME |
32 | getgrent, setgrent, endgrent \- get group file entry | |
33 | .SH SYNOPSIS | |
34 | .nf | |
35 | .B #include <sys/types.h> | |
36 | .B #include <grp.h> | |
68e4db0a | 37 | .PP |
fea681da | 38 | .B struct group *getgrent(void); |
68e4db0a | 39 | .PP |
fea681da | 40 | .B void setgrent(void); |
68e4db0a | 41 | .PP |
fea681da MK |
42 | .B void endgrent(void); |
43 | .fi | |
26bab9df | 44 | .PP |
cc4615cc MK |
45 | .in -4n |
46 | Feature Test Macro Requirements for glibc (see | |
47 | .BR feature_test_macros (7)): | |
48 | .in | |
26bab9df | 49 | .PP |
12c80914 | 50 | .PD 0 |
cc4615cc | 51 | .ad l |
6fe45009 | 52 | .BR setgrent (): |
12c80914 | 53 | .RS 4 |
9db90c7c MK |
54 | _XOPEN_SOURCE\ >=\ 500 |
55 | .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED | |
56 | || /* Glibc since 2.19: */ _DEFAULT_SOURCE | |
57 | || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE | |
12c80914 | 58 | .RE |
26bab9df | 59 | .PP |
12c80914 | 60 | .BR getgrent (), |
cc4615cc | 61 | .BR endgrent (): |
dcbccea1 | 62 | .RS 4 |
bccf0b07 MK |
63 | Since glibc 2.22: |
64 | _XOPEN_SOURCE\ >=\ 500 || | |
65 | .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED | |
66 | _DEFAULT_SOURCE | |
67 | .br | |
230ed833 | 68 | Glibc 2.21 and earlier |
bccf0b07 MK |
69 | _XOPEN_SOURCE\ >=\ 500 |
70 | .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED | |
71 | || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L | |
72 | || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE | |
dcbccea1 | 73 | .RE |
12c80914 | 74 | .PD |
cc4615cc | 75 | .ad b |
fea681da | 76 | .SH DESCRIPTION |
60a90ecd MK |
77 | The |
78 | .BR getgrent () | |
f2738b39 MK |
79 | function returns a pointer to a structure containing |
80 | the broken-out fields of a record in the group database | |
c13182ef | 81 | (e.g., the local group file |
f2738b39 MK |
82 | .IR /etc/group , |
83 | NIS, and LDAP). | |
aae8e0ac MK |
84 | The first time |
85 | .BR getgrent () | |
86 | is called, | |
fea681da MK |
87 | it returns the first entry; thereafter, it returns successive entries. |
88 | .PP | |
60a90ecd MK |
89 | The |
90 | .BR setgrent () | |
91 | function rewinds to the beginning | |
f2738b39 | 92 | of the group database, to allow repeated scans. |
fea681da | 93 | .PP |
60a90ecd MK |
94 | The |
95 | .BR endgrent () | |
96 | function is used to close the group database | |
f2738b39 | 97 | after all processing has been performed. |
fea681da MK |
98 | .PP |
99 | The \fIgroup\fP structure is defined in \fI<grp.h>\fP as follows: | |
26bab9df | 100 | .PP |
3f89ebc0 | 101 | .in +4n |
b8302363 | 102 | .EX |
fea681da | 103 | struct group { |
5e333b1b MK |
104 | char *gr_name; /* group name */ |
105 | char *gr_passwd; /* group password */ | |
106 | gid_t gr_gid; /* group ID */ | |
b7800b44 MK |
107 | char **gr_mem; /* NULL-terminated array of pointers |
108 | to names of group members */ | |
fea681da | 109 | }; |
b8302363 | 110 | .EE |
3f89ebc0 | 111 | .in |
b39f3e05 MK |
112 | .PP |
113 | For more information about the fields of this structure, see | |
114 | .BR group (5). | |
47297adb | 115 | .SH RETURN VALUE |
60a90ecd MK |
116 | The |
117 | .BR getgrent () | |
118 | function returns a pointer to a | |
c13182ef MK |
119 | .I group |
120 | structure, | |
fea681da | 121 | or NULL if there are no more entries or an error occurs. |
dd3568a1 | 122 | .PP |
fea681da MK |
123 | Upon error, |
124 | .I errno | |
f2738b39 MK |
125 | may be set. |
126 | If one wants to check | |
127 | .I errno | |
128 | after the call, it should be set to zero before the call. | |
26bab9df | 129 | .PP |
03e40141 MK |
130 | The return value may point to a static area, and may be overwritten |
131 | by subsequent calls to | |
132 | .BR getgrent (), | |
133 | .BR getgrgid (3), | |
134 | or | |
135 | .BR getgrnam (3). | |
48e4cfa0 MK |
136 | (Do not pass the returned pointer to |
137 | .BR free (3).) | |
fea681da MK |
138 | .SH ERRORS |
139 | .TP | |
7109ed81 CD |
140 | .B EAGAIN |
141 | The service was temporarily unavailable; try again later. | |
142 | For NSS backends in glibc this indicates a temporary error talking to the backend. | |
143 | The error may correct itself, retrying later is suggested. | |
144 | .TP | |
fea681da | 145 | .B EINTR |
bb14af39 MK |
146 | A signal was caught; see |
147 | .BR signal (7). | |
fea681da MK |
148 | .TP |
149 | .B EIO | |
150 | I/O error. | |
151 | .TP | |
152 | .B EMFILE | |
26c32fab | 153 | The per-process limit on the number of open file descriptors has been reached. |
fea681da MK |
154 | .TP |
155 | .B ENFILE | |
e258766b | 156 | The system-wide limit on the total number of open files has been reached. |
fea681da | 157 | .TP |
7109ed81 CD |
158 | .\" not in POSIX |
159 | .B ENOENT | |
160 | A necessary input file cannot be found. | |
161 | For NSS backends in glibc this indicates the backend is not correctly configured. | |
162 | .TP | |
fea681da | 163 | .B ENOMEM |
f2738b39 | 164 | .\" not in POSIX |
433dc4d5 MK |
165 | Insufficient memory to allocate |
166 | .I group | |
167 | structure. | |
f2738b39 MK |
168 | .TP |
169 | .B ERANGE | |
170 | Insufficient buffer space supplied. | |
fea681da MK |
171 | .SH FILES |
172 | .TP | |
173 | .I /etc/group | |
f2738b39 | 174 | local group database file |
7231e4c3 | 175 | .SH ATTRIBUTES |
777e02d6 MK |
176 | For an explanation of the terms used in this section, see |
177 | .BR attributes (7). | |
178 | .TS | |
179 | allbox; | |
1eed5a4d | 180 | lbw11 lb lb |
777e02d6 MK |
181 | l l l. |
182 | Interface Attribute Value | |
183 | T{ | |
7f4cd55d | 184 | .BR getgrent () |
1eed5a4d MK |
185 | T} Thread safety T{ |
186 | MT-Unsafe race:grent | |
187 | .br | |
188 | race:grentbuf locale | |
189 | T} | |
777e02d6 MK |
190 | T{ |
191 | .BR setgrent (), | |
7f4cd55d | 192 | .BR endgrent () |
97ba81bc | 193 | T} Thread safety MT-Unsafe race:grent locale |
777e02d6 | 194 | .TE |
26bab9df | 195 | .PP |
af89b750 MS |
196 | In the above table, |
197 | .I grent | |
198 | in | |
199 | .I race:grent | |
200 | signifies that if any of the functions | |
201 | .BR setgrent (), | |
202 | .BR getgrent (), | |
203 | or | |
204 | .BR endgrent () | |
2db8b492 MK |
205 | are used in parallel in different threads of a program, |
206 | then data races could occur. | |
47297adb | 207 | .SH CONFORMING TO |
0b86ac46 | 208 | POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. |
47297adb | 209 | .SH SEE ALSO |
fea681da MK |
210 | .BR fgetgrent (3), |
211 | .BR getgrent_r (3), | |
212 | .BR getgrgid (3), | |
c9c3b6f3 | 213 | .BR getgrnam (3), |
22cddee1 | 214 | .BR getgrouplist (3), |
b39f3e05 MK |
215 | .BR putgrent (3), |
216 | .BR group (5) |