Debian Codegraph @

upstream/debian-unstable/man3/getgrent_r.3

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