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