Debian Codegraph @

upstream/debian-unstable/man3/getgrent.3

raw
1 '\" t
2 .\" Copyright 1993, David Metcalfe <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH getgrent 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 getgrent, setgrent, endgrent \- get group file entry
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <sys/types.h>
16 .B #include <grp.h>
17 .P
18 .B struct group *getgrent(void);
19 .P
20 .B void setgrent(void);
21 .B void endgrent(void);
22 .fi
23 .P
24 .RS -4
25 Feature Test Macro Requirements for glibc (see
26 .BR feature_test_macros (7)):
27 .RE
28 .P
29 .BR setgrent ():
30 .nf
31 _XOPEN_SOURCE >= 500
32 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
33 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
34 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
35 .fi
36 .P
37 .BR getgrent (),
38 .BR endgrent ():
39 .nf
40 Since glibc 2.22:
41 _XOPEN_SOURCE >= 500 || _DEFAULT_SOURCE
42 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
43 glibc 2.21 and earlier
44 _XOPEN_SOURCE >= 500
45 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
46 || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
47 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
48 .fi
49 .SH DESCRIPTION
50 The
51 .BR getgrent ()
52 function returns a pointer to a structure containing
53 the broken-out fields of a record in the group database
54 (e.g., the local group file
55 .IR /etc/group ,
56 NIS, and LDAP).
57 The first time
58 .BR getgrent ()
59 is called,
60 it returns the first entry;
61 thereafter,
62 it returns successive entries.
63 .P
64 The
65 .BR setgrent ()
66 function rewinds to the beginning
67 of the group database, to allow repeated scans.
68 .P
69 The
70 .BR endgrent ()
71 function is used to close the group database
72 after all processing has been performed.
73 .P
74 The
75 .I group
76 structure is defined in
77 .I <grp.h>
78 as follows:
79 .P
80 .in +4n
81 .EX
82 struct group {
83 char *gr_name; /* group name */
84 char *gr_passwd; /* group password */
85 gid_t gr_gid; /* group ID */
86 char **gr_mem; /* NULL\-terminated array of pointers
87 to names of group members */
88 };
89 .EE
90 .in
91 .P
92 For more information about the fields of this structure, see
93 .BR group (5).
94 .SH RETURN VALUE
95 The
96 .BR getgrent ()
97 function returns a pointer to a
98 .I group
99 structure,
100 or NULL if there are no more entries or an error occurs.
101 .P
102 Upon error,
103 .I errno
104 may be set.
105 If one wants to check
106 .I errno
107 after the call, it should be set to zero before the call.
108 .P
109 The return value may point to a static area, and may be overwritten
110 by subsequent calls to
111 .BR getgrent (),
112 .BR getgrgid (3),
113 or
114 .BR getgrnam (3).
115 (Do not pass the returned pointer to
116 .BR free (3).)
117 .SH ERRORS
118 .TP
119 .B EAGAIN
120 The service was temporarily unavailable;
121 try again later.
122 For NSS backends in glibc
123 this indicates a temporary error talking to the backend.
124 The error may correct itself;
125 retrying later is suggested.
126 .TP
127 .B EINTR
128 A signal was caught;
129 see
130 .BR signal (7).
131 .TP
132 .B EIO
133 I/O error.
134 .TP
135 .B EMFILE
136 The per-process limit on the number of open file descriptors has been reached.
137 .TP
138 .B ENFILE
139 The system-wide limit on the total number of open files has been reached.
140 .TP
141 .\" not in POSIX
142 .B ENOENT
143 A necessary input file cannot be found.
144 For NSS backends in glibc
145 this indicates the backend is not correctly configured.
146 .TP
147 .B ENOMEM
148 .\" not in POSIX
149 Insufficient memory to allocate
150 .I group
151 structure.
152 .TP
153 .B ERANGE
154 Insufficient buffer space supplied.
155 .SH FILES
156 .TP
157 .I /etc/group
158 local group database file
159 .SH ATTRIBUTES
160 For an explanation of the terms used in this section, see
161 .BR attributes (7).
162 .TS
163 allbox;
164 lb lb lbx
165 l l l.
166 Interface Attribute Value
167 T{
168 .na
169 .nh
170 .BR getgrent ()
171 T} Thread safety T{
172 .na
173 .nh
174 MT-Unsafe race:grent
175 race:grentbuf locale
176 T}
177 T{
178 .na
179 .nh
180 .BR setgrent (),
181 .BR endgrent ()
182 T} Thread safety T{
183 .na
184 .nh
185 MT-Unsafe race:grent locale
186 T}
187 .TE
188 .P
189 In the above table,
190 .I grent
191 in
192 .I race:grent
193 signifies that if any of the functions
194 .BR setgrent (),
195 .BR getgrent (),
196 or
197 .BR endgrent ()
198 are used in parallel in different threads of a program,
199 then data races could occur.
200 .SH STANDARDS
201 POSIX.1-2008.
202 .SH HISTORY
203 POSIX.1-2001, SVr4, 4.3BSD.
204 .SH SEE ALSO
205 .BR fgetgrent (3),
206 .BR getgrent_r (3),
207 .BR getgrgid (3),
208 .BR getgrnam (3),
209 .BR getgrouplist (3),
210 .BR putgrent (3),
211 .BR group (5)