| blob | 5d55919cf3da512060fccdcfb575e2e24049c834 |
1 .\" $NetBSD: getpwent.3,v 1.38 2011/04/28 16:35:05 wiz Exp $
2 .\"
3 .\" Copyright (c) 1988, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)getpwent.3 8.2 (Berkeley) 12/11/93
31 .\"
32 .Dd April 30, 2008
33 .Dt GETPWENT 3
34 .Os
35 .Sh NAME
36 .Nm getpwent ,
37 .Nm getpwent_r ,
38 .Nm getpwnam ,
39 .Nm getpwnam_r ,
40 .Nm getpwuid ,
41 .Nm getpwuid_r ,
42 .Nm setpassent ,
43 .Nm setpwent ,
44 .Nm endpwent
45 .Nd password database operations
46 .Sh LIBRARY
47 .Lb libc
48 .Sh SYNOPSIS
49 .In pwd.h
50 .Ft struct passwd *
51 .Fn getpwent void
52 .Ft int
53 .Fo getpwent_r
54 .Fa "struct passwd *pw"
55 .Fa "char *buffer"
56 .Fa "size_t buflen"
57 .Fa "struct passwd **result"
58 .Fc
59 .Ft struct passwd *
60 .Fn getpwnam "const char *name"
61 .Ft int
62 .Fo getpwnam_r
63 .Fa "const char *name"
64 .Fa "struct passwd *pw"
65 .Fa "char *buffer"
66 .Fa "size_t buflen"
67 .Fa "struct passwd **result"
68 .Fc
69 .Ft struct passwd *
70 .Fn getpwuid "uid_t uid"
71 .Ft int
72 .Fo getpwuid_r
73 .Fa "uid_t uid"
74 .Fa "struct passwd *pw"
75 .Fa "char *buffer"
76 .Fa "size_t buflen"
77 .Fa "struct passwd **result"
78 .Fc
79 .Ft int
80 .Fn setpassent "int stayopen"
81 .Ft void
82 .Fn setpwent void
83 .Ft void
84 .Fn endpwent void
85 .Sh DESCRIPTION
86 These functions
87 operate on the password database
88 which is described
89 in
90 .Xr passwd 5 .
91 Each entry in the database is defined by the structure
92 .Ar passwd
93 found in the include
94 file
95 .In pwd.h :
96 .Bd -literal -offset indent
97 struct passwd {
98 char *pw_name; /* user name */
99 char *pw_passwd; /* encrypted password */
100 uid_t pw_uid; /* user uid */
101 gid_t pw_gid; /* user gid */
102 time_t pw_change; /* password change time */
103 char *pw_class; /* user login class */
104 char *pw_gecos; /* general information */
105 char *pw_dir; /* home directory */
106 char *pw_shell; /* default shell */
107 time_t pw_expire; /* account expiration */
108 };
109 .Ed
110 .Pp
111 The functions
112 .Fn getpwnam
113 and
114 .Fn getpwuid
115 search the password database for the given user name pointed to by
116 .Ar name
117 or user id pointed to by
118 .Ar uid
119 respectively, always returning the first one encountered.
120 Identical user names or user ids may result in undefined behavior.
121 .Pp
122 The
123 .Fn getpwent
124 function
125 sequentially reads the password database and is intended for programs
126 that wish to process the complete list of users.
127 .Pp
128 The functions
129 .Fn getpwnam_r ,
130 .Fn getpwuid_r ,
131 and
132 .Fn getpwent_r
133 act like their non re-entrant counterparts, updating the contents of
134 .Ar pw
135 and storing a pointer to that in
136 .Ar result ,
137 and returning
138 .Dv 0 .
139 Storage used by
140 .Ar pw
141 is allocated from
142 .Ar buffer ,
143 which is
144 .Ar buflen
145 bytes in size.
146 If the requested entry cannot be found,
147 .Ar result
148 will point to
149 .Dv NULL
150 and
151 .Dv 0
152 will be returned.
153 If an error occurs,
154 a non-zero error number will be returned and
155 .Ar result
156 will point to
157 .Dv NULL .
158 Calling
159 .Fn getpwent_r
160 from multiple threads will result in each thread reading a disjoint portion
161 of the password database.
162 .Pp
163 The
164 .Fn setpassent
165 function
166 accomplishes two purposes.
167 First, it causes
168 .Fn getpwent
169 to
170 .Dq rewind
171 to the beginning of the database.
172 Additionally, if
173 .Fa stayopen
174 is non-zero, file descriptors are left open, significantly speeding
175 up subsequent accesses for all of the functions.
176 (This latter functionality is unnecessary for
177 .Fn getpwent
178 as it doesn't close its file descriptors by default.)
179 .Pp
180 It is dangerous for long-running programs to keep the file descriptors
181 open as the database will become out of date if it is updated while the
182 program is running.
183 .Pp
184 The
185 .Fn setpwent
186 function
187 is equivalent to
188 .Fn setpassent
189 with an argument of zero.
190 .Pp
191 The
192 .Fn endpwent
193 function
194 closes any open files.
195 .Pp
196 These functions have been written to
197 .Dq shadow
198 the password file, e.g. allow only certain programs to have access
199 to the encrypted password.
200 If the process which calls them has an effective uid of 0, the encrypted
201 password will be returned, otherwise, the password field of the returned
202 structure will point to the string
203 .Ql * .
204 .Sh RETURN VALUES
205 The functions
206 .Fn getpwent ,
207 .Fn getpwnam ,
208 and
209 .Fn getpwuid ,
210 return a valid pointer to a passwd structure on success
211 and a
212 .Dv NULL
213 pointer if the entry was not found or an error occured.
214 If an error occured, the global variable
215 .Dv errno
216 is set to indicate the nature of the failure.
217 The
218 .Fn setpassent
219 function returns 0 on failure, setting the global variable
220 .Dv errno
221 to indicate the nature of the failure, and 1 on success.
222 The
223 .Fn endpwent
224 and
225 .Fn setpwent
226 functions
227 have no return value.
228 The functions
229 .Fn getpwnam_r ,
230 .Fn getpwuid_r ,
231 and
232 .Fn getpwent_r
233 return
234 .Dv 0
235 on success or entry not found, and non-zero on failure, setting the global
236 variable
237 .Dv errno
238 to indicate the nature of the failure.
239 .Sh FILES
240 .Bl -tag -width /etc/master.passwd -compact
241 .It Pa /etc/pwd.db
242 The insecure password database file
243 .It Pa /etc/spwd.db
244 The secure password database file
245 .It Pa /etc/master.passwd
246 The current password file
247 .It Pa /etc/passwd
248 A Version 7 format password file
249 .El
250 .Sh COMPATIBILITY
251 The historic function
252 .Fn setpwfile
253 which allowed the specification of alternative password databases,
254 has been deprecated and is no longer available.
255 .Sh ERRORS
256 The following error codes may be set in
257 .Va errno
258 for
259 .Nm getpwent ,
260 .Nm getpwent_r ,
261 .Nm getpwnam ,
262 .Nm getpwnam_r ,
263 .Nm getpwuid ,
264 .Nm getpwuid_r ,
265 and
266 .Nm setpassent :
267 .Bl -tag -width Er
268 .It Bq Er EINTR
269 A signal was caught during the database search.
270 .It Bq Er EIO
271 An I/O error has occurred.
272 .It Bq Er EMFILE
273 The limit on open files for this process has been reached.
274 .It Bq Er ENFILE
275 The system limit on open files has been reached.
276 .El
277 .Pp
278 The following error code may be set in
279 .Va errno
280 for
281 .Nm getpwent_r ,
282 .Nm getpwnam_r ,
283 and
284 .Nm getpwuid_r :
285 .Bl -tag -width Er
286 .It Bq Er ERANGE
287 The resulting
288 .Ft struct passwd
289 does not fit in the space defined by
290 .Dv buffer
291 and
292 .Dv buflen
293 .El
294 .Pp
295 Other
296 .Dv errno
297 values may be set depending on the specific database backends.
298 .Sh SEE ALSO
299 .Xr getlogin 2 ,
300 .Xr getgrent 3 ,
301 .Xr nsswitch.conf 5 ,
302 .Xr passwd 5 ,
303 .Xr passwd.conf 5 ,
304 .Xr pwd_mkdb 8 ,
305 .Xr vipw 8
306 .Sh STANDARDS
307 The
308 .Fn getpwnam
309 and
310 .Fn getpwuid ,
311 functions conform to
312 .St -p1003.1-90 .
313 The
314 .Fn getpwnam_r
315 and
316 .Fn getpwuid_r
317 functions conform to
318 .St -p1003.1c-95 .
319 The
320 .Fn endpwent ,
321 .Fn getpwent ,
322 and
323 .Fn setpwent
324 functions conform to
325 .St -xpg4.2
326 and
327 .St -p1003.1-2004
328 (XSI extension).
329 .Sh HISTORY
330 The
331 .Nm getpwent ,
332 .Nm getpwnam ,
333 .Nm getpwuid ,
334 .Nm setpwent ,
335 and
336 .Nm endpwent
337 functions appeared in
338 .At v7 .
339 The
340 .Nm setpassent
341 function appeared in
342 .Bx 4.3 Reno .
343 The functions
344 .Fn getpwnam_r
345 and
346 .Fn getpwuid_r
347 appeared in
348 .Nx 3.0 .
349 .Sh BUGS
350 The functions
351 .Fn getpwent ,
352 .Fn getpwnam ,
353 and
354 .Fn getpwuid ,
355 leave their results in an internal static object and return
356 a pointer to that object.
357 Subsequent calls to any of these functions will modify the same object.
358 .Pp
359 The functions
360 .Fn getpwent ,
361 .Fn endpwent ,
362 .Fn setpassent ,
363 and
364 .Fn setpwent
365 are fairly useless in a networked environment and should be
366 avoided, if possible.
367 .Fn getpwent
368 makes no attempt to suppress duplicate information if multiple
369 sources are specified in
370 .Xr nsswitch.conf 5 .