]>
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 getpwent_r 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
6 | .SH NAME |
7 | getpwent_r, fgetpwent_r \- get passwd 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 <pwd.h> |
68e4db0a | 14 | .PP |
69b7afbe AC |
15 | .BI "int getpwent_r(struct passwd *restrict " pwbuf , |
16 | .BI " char *restrict " buf ", size_t " buflen , | |
17 | .BI " struct passwd **restrict " pwbufp ); | |
18 | .BI "int fgetpwent_r(FILE *restrict " stream \ | |
19 | ", struct passwd *restrict " pwbuf , | |
20 | .BI " char *restrict " buf ", size_t " buflen , | |
21 | .BI " struct passwd **restrict " pwbufp ); | |
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 getpwent_r (), |
9d281e06 | 30 | .nf |
51c612fb MK |
31 | Since glibc 2.19: |
32 | _DEFAULT_SOURCE | |
33 | Glibc 2.19 and earlier: | |
34 | _BSD_SOURCE || _SVID_SOURCE | |
9d281e06 | 35 | .fi |
98c9347c | 36 | .PP |
cc4615cc | 37 | .BR fgetpwent_r (): |
9d281e06 | 38 | .nf |
51c612fb MK |
39 | Since glibc 2.19: |
40 | _DEFAULT_SOURCE | |
41 | Glibc 2.19 and earlier: | |
42 | _SVID_SOURCE | |
9d281e06 | 43 | .fi |
fea681da MK |
44 | .SH DESCRIPTION |
45 | The functions | |
63aa9df0 | 46 | .BR getpwent_r () |
fea681da | 47 | and |
63aa9df0 | 48 | .BR fgetpwent_r () |
fea681da MK |
49 | are the reentrant versions of |
50 | .BR getpwent (3) | |
51 | and | |
52 | .BR fgetpwent (3). | |
53 | The former reads the next passwd entry from the stream initialized by | |
54 | .BR setpwent (3). | |
ef3d4efe | 55 | The latter reads the next passwd entry from |
495604c3 | 56 | .IR stream . |
fea681da MK |
57 | .PP |
58 | The \fIpasswd\fP structure is defined in | |
59 | .I <pwd.h> | |
60 | as follows: | |
51f5698d | 61 | .PP |
bd191423 | 62 | .in +4n |
b8302363 | 63 | .EX |
fea681da | 64 | struct passwd { |
18701562 | 65 | char *pw_name; /* username */ |
cf0a9ace MK |
66 | char *pw_passwd; /* user password */ |
67 | uid_t pw_uid; /* user ID */ | |
68 | gid_t pw_gid; /* group ID */ | |
97724acd | 69 | char *pw_gecos; /* user information */ |
cf0a9ace MK |
70 | char *pw_dir; /* home directory */ |
71 | char *pw_shell; /* shell program */ | |
fea681da | 72 | }; |
b8302363 | 73 | .EE |
bd191423 | 74 | .in |
7f12f117 MK |
75 | .PP |
76 | For more information about the fields of this structure, see | |
77 | .BR passwd (5). | |
847e0d88 | 78 | .PP |
54d75d6c | 79 | The nonreentrant functions return a pointer to static storage, |
fea681da MK |
80 | where this static storage contains further pointers to user |
81 | name, password, gecos field, home directory and shell. | |
82 | The reentrant functions described here return all of that in | |
c13182ef MK |
83 | caller-provided buffers. |
84 | First of all there is the buffer | |
fea681da | 85 | .I pwbuf |
0c2ec4f1 | 86 | that can hold a \fIstruct passwd\fP. |
c13182ef | 87 | And next the buffer |
fea681da MK |
88 | .I buf |
89 | of size | |
90 | .I buflen | |
91 | that can hold additional strings. | |
0c2ec4f1 | 92 | The result of these functions, the \fIstruct passwd\fP read from the stream, |
fea681da | 93 | is stored in the provided buffer |
bd9b2a9c | 94 | .IR *pwbuf , |
0c2ec4f1 | 95 | and a pointer to this \fIstruct passwd\fP is returned in |
bd9b2a9c | 96 | .IR *pwbufp . |
47297adb | 97 | .SH RETURN VALUE |
fea681da | 98 | On success, these functions return 0 and |
bd9b2a9c | 99 | .I *pwbufp |
0c2ec4f1 | 100 | is a pointer to the \fIstruct passwd\fP. |
fea681da | 101 | On error, these functions return an error value and |
bd9b2a9c | 102 | .I *pwbufp |
fea681da MK |
103 | is NULL. |
104 | .SH ERRORS | |
105 | .TP | |
106 | .B ENOENT | |
107 | No more entries. | |
108 | .TP | |
109 | .B ERANGE | |
c13182ef MK |
110 | Insufficient buffer space supplied. |
111 | Try again with larger buffer. | |
98a731cd ZL |
112 | .SH ATTRIBUTES |
113 | For an explanation of the terms used in this section, see | |
114 | .BR attributes (7). | |
c466875e MK |
115 | .ad l |
116 | .nh | |
98a731cd ZL |
117 | .TS |
118 | allbox; | |
b32feea5 | 119 | lb lb lbx |
98a731cd ZL |
120 | l l l. |
121 | Interface Attribute Value | |
122 | T{ | |
123 | .BR getpwent_r () | |
b32feea5 MK |
124 | T} Thread safety T{ |
125 | MT-Unsafe race:pwent locale | |
126 | T} | |
98a731cd ZL |
127 | T{ |
128 | .BR fgetpwent_r () | |
129 | T} Thread safety MT-Safe | |
130 | .TE | |
c466875e MK |
131 | .hy |
132 | .ad | |
847e0d88 | 133 | .sp 1 |
98a731cd ZL |
134 | In the above table, |
135 | .I pwent | |
136 | in | |
137 | .I race:pwent | |
138 | signifies that if any of the functions | |
139 | .BR setpwent (), | |
140 | .BR getpwent (), | |
141 | .BR endpwent (), | |
142 | or | |
143 | .BR getpwent_r () | |
144 | are used in parallel in different threads of a program, | |
145 | then data races could occur. | |
3113c7f3 | 146 | .SH STANDARDS |
2b2581ee MK |
147 | These functions are GNU extensions, done in a style resembling |
148 | the POSIX version of functions like | |
149 | .BR getpwnam_r (3). | |
b5606b27 | 150 | Other systems use the prototype |
51f5698d | 151 | .PP |
088a639b | 152 | .in +4n |
b8302363 | 153 | .EX |
2b2581ee MK |
154 | struct passwd * |
155 | getpwent_r(struct passwd *pwd, char *buf, int buflen); | |
b8302363 | 156 | .EE |
bdd915e2 | 157 | .in |
51f5698d | 158 | .PP |
2b2581ee | 159 | or, better, |
51f5698d | 160 | .PP |
088a639b | 161 | .in +4n |
b8302363 | 162 | .EX |
2b2581ee MK |
163 | int |
164 | getpwent_r(struct passwd *pwd, char *buf, int buflen, | |
165 | FILE **pw_fp); | |
b8302363 | 166 | .EE |
e646a1ba | 167 | .in |
2b2581ee MK |
168 | .SH NOTES |
169 | The function | |
170 | .BR getpwent_r () | |
171 | is not really reentrant since it shares the reading position | |
172 | in the stream with all other threads. | |
a14af333 | 173 | .SH EXAMPLES |
b0b6ab4e | 174 | .\" SRC BEGIN (getpwent_r.c) |
bdd915e2 | 175 | .EX |
fea681da MK |
176 | #define _GNU_SOURCE |
177 | #include <pwd.h> | |
8eb90116 | 178 | #include <stdint.h> |
ad3868f0 | 179 | #include <stdio.h> |
0ac66436 | 180 | #include <stdlib.h> |
ad3868f0 | 181 | |
fea681da MK |
182 | #define BUFLEN 4096 |
183 | ||
c13182ef MK |
184 | int |
185 | main(void) | |
cf0a9ace | 186 | { |
4e4e6e5e AC |
187 | struct passwd pw; |
188 | struct passwd *pwp; | |
cf0a9ace MK |
189 | char buf[BUFLEN]; |
190 | int i; | |
fea681da | 191 | |
cf0a9ace MK |
192 | setpwent(); |
193 | while (1) { | |
1656c170 | 194 | i = getpwent_r(&pw, buf, sizeof(buf), &pwp); |
cf0a9ace MK |
195 | if (i) |
196 | break; | |
8eb90116 AC |
197 | printf("%s (%jd)\etHOME %s\etSHELL %s\en", pwp\->pw_name, |
198 | (intmax_t) pwp\->pw_uid, pwp\->pw_dir, pwp\->pw_shell); | |
cf0a9ace MK |
199 | } |
200 | endpwent(); | |
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("getpwent_r: %s", strerror(i)); | |
4c44ffe5 | 211 | .\" exit(EXIT_SUCCESS); |
fea681da | 212 | .\" } |
b0b6ab4e | 213 | .\" SRC END |
47297adb | 214 | .SH SEE ALSO |
fea681da MK |
215 | .BR fgetpwent (3), |
216 | .BR getpw (3), | |
217 | .BR getpwent (3), | |
218 | .BR getpwnam (3), | |
219 | .BR getpwuid (3), | |
220 | .BR putpwent (3), | |
cc4615cc | 221 | .BR passwd (5) |