| blob | db97f378a943b1424f9e1d7e71dd76f55d8912d1 |
1 .\" $NetBSD: getpwent.3,v 1.37 2010/03/22 19:30:53 joerg 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 ERRORS
240 The following error codes may be set in
241 .Va errno
242 for
243 .Nm getpwent ,
244 .Nm getpwent_r ,
245 .Nm getpwnam ,
246 .Nm getpwnam_r ,
247 .Nm getpwuid ,
248 .Nm getpwuid_r ,
249 and
250 .Nm setpassent :
251 .Bl -tag -width Er
252 .It Bq Er EIO
253 An I/O error has occurred.
254 .It Bq Er EINTR
255 A signal was caught during the database search.
256 .It Bq Er EMFILE
257 The limit on open files for this process has been reached.
258 .It Bq Er ENFILE
259 The system limit on open files has been reached.
260 .El
261 .Pp
262 The following error code may be set in
263 .Va errno
264 for
265 .Nm getpwent_r ,
266 .Nm getpwnam_r ,
267 and
268 .Nm getpwuid_r :
269 .Bl -tag -width Er
270 .It Bq Er ERANGE
271 The resulting
272 .Ft struct passwd
273 does not fit in the space defined by
274 .Dv buffer
275 and
276 .Dv buflen
277 .El
278 .Pp
279 Other
280 .Dv errno
281 values may be set depending on the specific database backends.
282 .Sh FILES
283 .Bl -tag -width /etc/master.passwd -compact
284 .It Pa /etc/pwd.db
285 The insecure password database file
286 .It Pa /etc/spwd.db
287 The secure password database file
288 .It Pa /etc/master.passwd
289 The current password file
290 .It Pa /etc/passwd
291 A Version 7 format password file
292 .El
293 .Sh SEE ALSO
294 .Xr getlogin 2 ,
295 .Xr getgrent 3 ,
296 .Xr nsswitch.conf 5 ,
297 .Xr passwd 5 ,
298 .Xr passwd.conf 5 ,
299 .Xr pwd_mkdb 8 ,
300 .Xr vipw 8
301 .Sh STANDARDS
302 The
303 .Fn getpwnam
304 and
305 .Fn getpwuid ,
306 functions conform to
307 .St -p1003.1-90 .
308 The
309 .Fn getpwnam_r
310 and
311 .Fn getpwuid_r
312 functions conform to
313 .St -p1003.1c-95 .
314 The
315 .Fn endpwent ,
316 .Fn getpwent ,
317 and
318 .Fn setpwent
319 functions conform to
320 .St -xpg4.2
321 and
322 .St -p1003.1-2004
323 (XSI extension).
324 .Sh HISTORY
325 The
326 .Nm getpwent ,
327 .Nm getpwnam ,
328 .Nm getpwuid ,
329 .Nm setpwent ,
330 and
331 .Nm endpwent
332 functions appeared in
333 .At v7 .
334 The
335 .Nm setpassent
336 function appeared in
337 .Bx 4.3 Reno .
338 The functions
339 .Fn getpwnam_r
340 and
341 .Fn getpwuid_r
342 appeared in
343 .Nx 3.0 .
344 .Sh BUGS
345 The functions
346 .Fn getpwent ,
347 .Fn getpwnam ,
348 and
349 .Fn getpwuid ,
350 leave their results in an internal static object and return
351 a pointer to that object.
352 Subsequent calls to any of these functions will modify the same object.
353 .Pp
354 The functions
355 .Fn getpwent ,
356 .Fn endpwent ,
357 .Fn setpassent ,
358 and
359 .Fn setpwent
360 are fairly useless in a networked environment and should be
361 avoided, if possible.
362 .Fn getpwent
363 makes no attempt to suppress duplicate information if multiple
364 sources are specified in
365 .Xr nsswitch.conf 5 .
366 .Sh COMPATIBILITY
367 The historic function
368 .Fn setpwfile
369 which allowed the specification of alternative password databases,
370 has been deprecated and is no longer available.