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