]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da MK |
2 | .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) |
3 | .\" | |
e4a74ca8 | 4 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
fea681da | 5 | .\" |
4c1c5274 | 6 | .TH getgrent_r 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
7 | .SH NAME |
8 | getgrent_r, fgetgrent_r \- get group file entry reentrantly | |
42009080 AC |
9 | .SH LIBRARY |
10 | Standard C library | |
11 | .RI ( libc ", " \-lc ) | |
fea681da MK |
12 | .SH SYNOPSIS |
13 | .nf | |
fea681da | 14 | .B #include <grp.h> |
68e4db0a | 15 | .PP |
61f75e87 | 16 | .BI "int getgrent_r(struct group *restrict " gbuf , |
1eed67e7 | 17 | .BI " char " buf "[restrict ." buflen "], size_t " buflen , |
61f75e87 AC |
18 | .BI " struct group **restrict " gbufp ); |
19 | .BI "int fgetgrent_r(FILE *restrict " stream ", struct group *restrict " gbuf , | |
1eed67e7 | 20 | .BI " char " buf "[restrict ." buflen "], size_t " buflen , |
61f75e87 | 21 | .BI " struct group **restrict " gbufp ); |
cc4615cc | 22 | .fi |
68e4db0a | 23 | .PP |
d39ad78f | 24 | .RS -4 |
cc4615cc MK |
25 | Feature Test Macro Requirements for glibc (see |
26 | .BR feature_test_macros (7)): | |
d39ad78f | 27 | .RE |
68e4db0a | 28 | .PP |
cc4615cc | 29 | .BR getgrent_r (): |
1dd0d7b4 MK |
30 | .nf |
31 | _GNU_SOURCE | |
32 | .fi | |
cc4615cc | 33 | .\" FIXME . The FTM requirements seem inconsistent here. File a glibc bug? |
98c9347c | 34 | .PP |
cc4615cc | 35 | .BR fgetgrent_r (): |
8c5b1011 | 36 | .nf |
51c612fb MK |
37 | Since glibc 2.19: |
38 | _DEFAULT_SOURCE | |
75c018a1 | 39 | glibc 2.19 and earlier: |
51c612fb | 40 | _SVID_SOURCE |
8c5b1011 | 41 | .fi |
fea681da MK |
42 | .SH DESCRIPTION |
43 | The functions | |
63aa9df0 | 44 | .BR getgrent_r () |
fea681da | 45 | and |
63aa9df0 | 46 | .BR fgetgrent_r () |
fea681da MK |
47 | are the reentrant versions of |
48 | .BR getgrent (3) | |
49 | and | |
50 | .BR fgetgrent (3). | |
51 | The former reads the next group entry from the stream initialized by | |
52 | .BR setgrent (3). | |
43905c28 | 53 | The latter reads the next group entry from |
e164e983 | 54 | .IR stream . |
fea681da MK |
55 | .PP |
56 | The \fIgroup\fP structure is defined in | |
57 | .I <grp.h> | |
58 | as follows: | |
51f5698d | 59 | .PP |
bd191423 | 60 | .in +4n |
b8302363 | 61 | .EX |
fea681da | 62 | struct group { |
5e333b1b MK |
63 | char *gr_name; /* group name */ |
64 | char *gr_passwd; /* group password */ | |
65 | gid_t gr_gid; /* group ID */ | |
d064d41a | 66 | char **gr_mem; /* NULL\-terminated array of pointers |
b7800b44 | 67 | to names of group members */ |
fea681da | 68 | }; |
b8302363 | 69 | .EE |
bd191423 | 70 | .in |
b39f3e05 MK |
71 | .PP |
72 | For more information about the fields of this structure, see | |
73 | .BR group (5). | |
74 | .PP | |
54d75d6c | 75 | The nonreentrant functions return a pointer to static storage, |
fea681da | 76 | where this static storage contains further pointers to group |
735334d4 | 77 | name, password, and members. |
fea681da | 78 | The reentrant functions described here return all of that in |
c13182ef MK |
79 | caller-provided buffers. |
80 | First of all there is the buffer | |
fea681da | 81 | .I gbuf |
0c2ec4f1 | 82 | that can hold a \fIstruct group\fP. |
c13182ef | 83 | And next the buffer |
fea681da MK |
84 | .I buf |
85 | of size | |
86 | .I buflen | |
87 | that can hold additional strings. | |
0c2ec4f1 | 88 | The result of these functions, the \fIstruct group\fP read from the stream, |
fea681da | 89 | is stored in the provided buffer |
bd9b2a9c | 90 | .IR *gbuf , |
0c2ec4f1 | 91 | and a pointer to this \fIstruct group\fP is returned in |
bd9b2a9c | 92 | .IR *gbufp . |
47297adb | 93 | .SH RETURN VALUE |
fea681da | 94 | On success, these functions return 0 and |
bd9b2a9c | 95 | .I *gbufp |
0c2ec4f1 | 96 | is a pointer to the \fIstruct group\fP. |
fea681da | 97 | On error, these functions return an error value and |
bd9b2a9c | 98 | .I *gbufp |
fea681da MK |
99 | is NULL. |
100 | .SH ERRORS | |
101 | .TP | |
102 | .B ENOENT | |
103 | No more entries. | |
104 | .TP | |
105 | .B ERANGE | |
c13182ef MK |
106 | Insufficient buffer space supplied. |
107 | Try again with larger buffer. | |
f8c46262 ZL |
108 | .SH ATTRIBUTES |
109 | For an explanation of the terms used in this section, see | |
110 | .BR attributes (7). | |
111 | .TS | |
112 | allbox; | |
b32feea5 | 113 | lb lb lbx |
f8c46262 ZL |
114 | l l l. |
115 | Interface Attribute Value | |
116 | T{ | |
9e54434e BR |
117 | .na |
118 | .nh | |
f8c46262 | 119 | .BR getgrent_r () |
b32feea5 | 120 | T} Thread safety T{ |
9e54434e BR |
121 | .na |
122 | .nh | |
b32feea5 MK |
123 | MT-Unsafe race:grent locale |
124 | T} | |
f8c46262 | 125 | T{ |
9e54434e BR |
126 | .na |
127 | .nh | |
f8c46262 | 128 | .BR fgetgrent_r () |
b32feea5 | 129 | T} Thread safety T{ |
9e54434e BR |
130 | .na |
131 | .nh | |
b32feea5 MK |
132 | MT-Safe |
133 | T} | |
f8c46262 | 134 | .TE |
847e0d88 | 135 | .sp 1 |
f8c46262 ZL |
136 | In the above table, |
137 | .I grent | |
138 | in | |
139 | .I race:grent | |
140 | signifies that if any of the functions | |
e3a78ee9 MK |
141 | .BR setgrent (3), |
142 | .BR getgrent (3), | |
143 | .BR endgrent (3), | |
f8c46262 ZL |
144 | or |
145 | .BR getgrent_r () | |
146 | are used in parallel in different threads of a program, | |
147 | then data races could occur. | |
4131356c | 148 | .SH VERSIONS |
b33e5e80 | 149 | Other systems use the prototype |
51f5698d | 150 | .PP |
088a639b | 151 | .in +4n |
b8302363 | 152 | .EX |
3f282501 MK |
153 | struct group *getgrent_r(struct group *grp, char *buf, |
154 | int buflen); | |
b8302363 | 155 | .EE |
bdd915e2 | 156 | .in |
51f5698d | 157 | .PP |
2b2581ee | 158 | or, better, |
51f5698d | 159 | .PP |
088a639b | 160 | .in +4n |
b8302363 | 161 | .EX |
3f282501 MK |
162 | int getgrent_r(struct group *grp, char *buf, int buflen, |
163 | FILE **gr_fp); | |
b8302363 | 164 | .EE |
bdd915e2 | 165 | .in |
4131356c AC |
166 | .SH STANDARDS |
167 | GNU. | |
168 | .SH HISTORY | |
169 | These functions are done in a style resembling | |
170 | the POSIX version of functions like | |
171 | .BR getpwnam_r (3). | |
2b2581ee MK |
172 | .SH NOTES |
173 | The function | |
174 | .BR getgrent_r () | |
175 | is not really reentrant since it shares the reading position | |
176 | in the stream with all other threads. | |
a14af333 | 177 | .SH EXAMPLES |
b0b6ab4e | 178 | .\" SRC BEGIN (getgrent_r.c) |
bdd915e2 | 179 | .EX |
fea681da MK |
180 | #define _GNU_SOURCE |
181 | #include <grp.h> | |
8eb90116 | 182 | #include <stdint.h> |
ad3868f0 | 183 | #include <stdio.h> |
af9c7ff2 | 184 | #include <stdlib.h> |
fea681da | 185 | #define BUFLEN 4096 |
fe5dba13 | 186 | \& |
c13182ef MK |
187 | int |
188 | main(void) | |
cf0a9ace | 189 | { |
203a500f AC |
190 | struct group grp; |
191 | struct group *grpp; | |
cf0a9ace MK |
192 | char buf[BUFLEN]; |
193 | int i; | |
fe5dba13 | 194 | \& |
cf0a9ace MK |
195 | setgrent(); |
196 | while (1) { | |
cf254328 | 197 | i = getgrent_r(&grp, buf, sizeof(buf), &grpp); |
cf0a9ace MK |
198 | if (i) |
199 | break; | |
8eb90116 | 200 | printf("%s (%jd):", grpp\->gr_name, (intmax_t) grpp\->gr_gid); |
b42296e4 | 201 | for (size_t j = 0; ; j++) { |
88893a77 | 202 | if (grpp\->gr_mem[j] == NULL) |
cf0a9ace | 203 | break; |
88893a77 | 204 | printf(" %s", grpp\->gr_mem[j]); |
cf0a9ace | 205 | } |
31a6818e | 206 | printf("\en"); |
cf0a9ace MK |
207 | } |
208 | endgrent(); | |
5bc8c34c | 209 | exit(EXIT_SUCCESS); |
fea681da | 210 | } |
bdd915e2 | 211 | .EE |
fea681da MK |
212 | .\" perhaps add error checking - should use strerror_r |
213 | .\" #include <errno.h> | |
214 | .\" #include <stdlib.h> | |
215 | .\" if (i) { | |
216 | .\" if (i == ENOENT) | |
217 | .\" break; | |
218 | .\" printf("getgrent_r: %s", strerror(i)); | |
4c44ffe5 | 219 | .\" exit(EXIT_FAILURE); |
fea681da | 220 | .\" } |
b0b6ab4e | 221 | .\" SRC END |
47297adb | 222 | .SH SEE ALSO |
fea681da MK |
223 | .BR fgetgrent (3), |
224 | .BR getgrent (3), | |
225 | .BR getgrgid (3), | |
226 | .BR getgrnam (3), | |
c9c3b6f3 | 227 | .BR putgrent (3), |
cc4615cc | 228 | .BR group (5) |