]> git.saurik.com Git - apple/libinfo.git/blob - lookup.subproj/getpwent.3
bf8566eeb1efcd597086978e947ce8f068ba0b11
[apple/libinfo.git] / lookup.subproj / getpwent.3
1 .\" Copyright (c) 1988, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 4. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\" From: @(#)getpwent.3 8.2 (Berkeley) 12/11/93
29 .\" $FreeBSD: src/lib/libc/gen/getpwent.3,v 1.30 2007/01/09 00:27:54 imp Exp $
30 .\"
31 .\" @APPLE_LICENSE_HEADER_START@
32 .\"
33 .\" Portions Copyright (c) 2003-2013 Apple Inc. All Rights Reserved.
34 .\"
35 .\" This file contains Original Code and/or Modifications of Original Code
36 .\" as defined in and that are subject to the Apple Public Source License
37 .\" Version 2.0 (the 'License'). You may not use this file except in
38 .\" compliance with the License. Please obtain a copy of the License at
39 .\" http://www.opensource.apple.com/apsl/ and read it before using this
40 .\" file.
41 .\"
42 .\" The Original Code and all software distributed under the License are
43 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
44 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
45 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
46 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
47 .\" Please see the License for the specific language governing rights and
48 .\" limitations under the License.
49 .\"
50 .\" @APPLE_LICENSE_HEADER_END@
51 .\"
52 .Dd October 26, 2011
53 .Dt GETPWENT 3
54 .Os
55 .Sh NAME
56 .Nm getpwent ,
57 .\".Nm getpwent_r ,
58 .Nm getpwnam ,
59 .Nm getpwnam_r ,
60 .Nm getpwuid ,
61 .Nm getpwuid_r ,
62 .Nm getpwuuid ,
63 .Nm getpwuuid_r ,
64 .Nm setpassent ,
65 .Nm setpwent ,
66 .Nm endpwent
67 .Nd password database operations
68 .Sh LIBRARY
69 .Lb libc
70 .Sh SYNOPSIS
71 .In sys/types.h
72 .In pwd.h
73 .In uuid/uuid.h
74 .Ft struct passwd *
75 .Fn getpwent void
76 .\".Ft int
77 .\".Fn getpwent_r "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result"
78 .Ft struct passwd *
79 .Fn getpwnam "const char *login"
80 .Ft int
81 .Fn getpwnam_r "const char *name" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result"
82 .Ft struct passwd *
83 .Fn getpwuid "uid_t uid"
84 .Ft int
85 .Fn getpwuid_r "uid_t uid" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result"
86 .Ft struct passwd *
87 .Fn getpwuuid "uuid_t uuid"
88 .Ft int
89 .Fn getpwuuid_r "uuid_t uuid" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result"
90 .Ft int
91 .Fn setpassent "int stayopen"
92 .Ft void
93 .Fn setpwent void
94 .Ft void
95 .Fn endpwent void
96 .Sh DESCRIPTION
97 These functions
98 .\"operate on the password database file
99 obtain information from
100 .Xr opendirectoryd 8 ,
101 including records in
102 .Pa /etc/master.passwd
103 which is described
104 in
105 .Xr master.passwd 5 .
106 Each entry in the database is defined by the structure
107 .Vt passwd
108 found in the include
109 file
110 .In pwd.h :
111 .Bd -literal -offset indent
112 struct passwd {
113 char *pw_name; /* user name */
114 char *pw_passwd; /* encrypted password */
115 uid_t pw_uid; /* user uid */
116 gid_t pw_gid; /* user gid */
117 time_t pw_change; /* password change time */
118 char *pw_class; /* user access class */
119 char *pw_gecos; /* Honeywell login info */
120 char *pw_dir; /* home directory */
121 char *pw_shell; /* default shell */
122 time_t pw_expire; /* account expiration */
123 int pw_fields; /* internal: fields filled in */
124 };
125 .Ed
126 .Pp
127 The functions
128 .Fn getpwnam ,
129 .Fn getpwuid ,
130 and
131 .Fn getpwuuid
132 search the password database for the given login name, user uid, or user uuid
133 respectively, always returning the first one encountered.
134 .Pp
135 Note that the password file
136 .Pa /etc/master.passwd
137 does not contain user UUIDs.
138 The UUID for a user may be found using
139 .Fn mbr_uid_to_uuid .
140 .Pp
141 On OS X, these routines are thread-safe and return a pointer to a
142 thread-specific data structure. The contents of this data
143 structure are automatically released by subsequent calls to
144 any of these routines on the same thread, or when the thread exits.
145 These routines are therefore unsuitable for use in libraries or frameworks,
146 from where they may overwrite the per-thread data that the calling
147 application expects to find as a result of its own calls to these
148 routines. Library and framework code should use the alternative reentrant
149 variants detailed below.
150 .Pp
151 The
152 .Fn getpwent
153 function
154 searches all available directory services on it's first invocation.
155 It caches the returned entries in a list
156 and returns user account entries one at a time.
157 .Pp
158 .Em NOTE
159 that
160 .Fn getpwent
161 may cause a very lengthy search for user account records by
162 .Nm opendirectoryd
163 and may result in a large number of user account records being cached
164 by the calling process.
165 Use of this function is not advised.
166 .Pp
167 The functions
168 .Fn getpwnam_r ,
169 .Fn getpwuid_r ,
170 and
171 .Fn getpwuuid_r
172 are alternative versions of
173 .Fn getpwnam ,
174 .Fn getpwuid ,
175 and
176 .Fn getpwuuid
177 respectively.
178 They store the results of their search in the caller-provided
179 .Fa pwd
180 structure, which additionally contains pointers to strings that are
181 stored in the caller-provided
182 .Fa buffer
183 of size
184 .Fa bufsize .
185 (The maximum required
186 .Fa bufsize
187 can be obtained by passing the _SC_GETPW_R_SIZE_MAX constant to the
188 .Xr sysconf 3
189 call. See example code below.) When these functions are successful, the
190 .Fa pwd
191 argument will be filled in, and a pointer to that argument will be
192 stored in the caller-provided
193 .Fa result .
194 If an entry is not found or an error occurs,
195 .Fa result
196 will be set to
197 .Dv NULL .
198 .Pp
199 The
200 .Fn setpassent
201 function causes
202 .Fn getpwent
203 to ``rewind'' to the beginning of the list of entries cached by a previous
204 .Fn getpwent
205 call.
206 The cache is not cleared.
207 The
208 .Fa stayopen
209 parameter value is unused on OS X.
210 .Pp
211 The
212 .Fn setpwent
213 and
214 .Fn endpwent
215 functions clear the cached results from a previous
216 .Fn getpwent
217 call.
218 .Pp
219 .\"These routines have been written to ``shadow'' the password file, e.g.\&
220 .\"allow only certain programs to have access to the encrypted password.
221 .\"If the process which calls them has an effective uid of 0, the encrypted
222 .\"password will be returned, otherwise, the password field of the returned
223 .\"structure will point to the string
224 These routines have been written to
225 .Ql shadow
226 the password of user records created on Mac OS X 10.3 or later,
227 by returning a structure whose password field points to the string
228 .Ql ******** .
229 Legacy crypt passwords are still returned for user records created on
230 earlier versions of Mac OS X whose
231 .Xr opendirectoryd 8
232 .Dt AuthenticationAuthority
233 attribute contains the value
234 .Ql ;basic; .
235 .Pp
236 Note that
237 .Xr opendirectoryd 8
238 allows user records from some sources which may not include all the component
239 fields present in a passwd structure.
240 Only the name, uid, and gid of a user record are required.
241 Default values will be supplied as follows:
242 .Bd -literal -offset indent
243 pw_passwd = "*"
244 pw_change = 0
245 pw_class = ""
246 pw_gecos = ""
247 pw_dir = "/var/empty"
248 pw_shell = "/usr/bin/false"
249 pw_expire = 0
250 .Ed
251 .Sh RETURN VALUES
252 The functions
253 .Fn getpwent ,
254 .Fn getpwnam ,
255 .Fn getpwuid ,
256 and
257 .Fn getpwuuid
258 return a valid pointer to a passwd structure on success
259 or
260 .Dv NULL
261 if the entry is not found or if an error occurs.
262 If an error does occur,
263 .Va errno
264 will be set.
265 Note that programs must explicitly set
266 .Va errno
267 to zero before calling any of these functions if they need to
268 distinguish between a non-existent entry and an error.
269 The functions
270 .Fn getpwnam_r ,
271 .Fn getpwuid_r ,
272 and
273 .Fn getpwuuid_r
274 return 0 if no error occurred, or an error number to indicate failure.
275 It is not an error if a matching entry is not found.
276 (Thus, if
277 .Fa result
278 is
279 .Dv NULL
280 and the return value is 0, no matching entry exists.)
281 .Pp
282 The
283 .Fn setpassent
284 function returns 0 on failure and 1 on success.
285 The
286 .Fn endpwent
287 and
288 .Fn setpwent
289 functions
290 have no return value.
291 .Sh EXAMPLES
292 To print the current user's home directory without depending on per-thread storage:
293 .Bd -literal -offset indent
294 #include <sys/types.h>
295 #include <unistd.h>
296 #include <stdlib.h>
297 #include <stdio.h>
298 #include <pwd.h>
299
300 int bufsize;
301
302 if ((bufsize = sysconf(_SC_GETPW_R_SIZE_MAX)) == -1)
303 abort();
304
305 char buffer[bufsize];
306 struct passwd pwd, *result = NULL;
307 if (getpwuid_r(getuid(), &pwd, buffer, bufsize, &result) != 0 || !result)
308 abort();
309
310 printf("%s\\n", pwd.pw_dir);
311 .Ed
312 .Sh FILES
313 .Bl -tag -width /etc/master.passwd -compact
314 .\".It Pa /etc/pwd.db
315 .\"The insecure password database file
316 .\".It Pa /etc/spwd.db
317 The secure password database file
318 .It Pa /etc/master.passwd
319 The current password file
320 .It Pa /etc/passwd
321 A Version 7 format password file
322 .El
323 .\".Sh COMPATIBILITY
324 .\"The historic function
325 .\".Xr setpwfile 3 ,
326 .\"which allowed the specification of alternate password databases,
327 .\"has been deprecated and is no longer available.
328 .Sh ERRORS
329 These routines may fail for any of the errors specified in
330 .Xr open 2 ,
331 .Xr dbopen 3 ,
332 .Xr socket 2 ,
333 and
334 .Xr connect 2 ,
335 in addition to the following:
336 .Bl -tag -width Er
337 .It Bq Er ERANGE
338 The buffer specified by the
339 .Fa buffer
340 and
341 .Fa bufsize
342 arguments was insufficiently sized to store the result.
343 The caller should retry with a larger buffer.
344 .El
345 .Sh SEE ALSO
346 .Xr getlogin 2 ,
347 .Xr getgrent 3 ,
348 .\".Xr nsswitch.conf 5 ,
349 .Xr passwd 5 ,
350 .\".Xr pwd_mkdb 8 ,
351 .\".Xr vipw 8 ,
352 .Xr mbr_uid_to_uuid 3,
353 .Xr opendirectoryd 8 ,
354 .Xr yp 8
355 .Sh STANDARDS
356 The
357 .Fn getpwent ,
358 .Fn getpwnam ,
359 .Fn getpwnam_r ,
360 .Fn getpwuid ,
361 .Fn getpwuid_r ,
362 .Fn setpwent ,
363 and
364 .Fn endpwent
365 functions conform to
366 .St -p1003.1-96 .
367 .Sh HISTORY
368 The
369 .Fn getpwent ,
370 .Fn getpwnam ,
371 .Fn getpwuid ,
372 .Fn setpwent ,
373 and
374 .Fn endpwent
375 functions appeared in
376 .At v7 .
377 The
378 .Fn setpassent
379 function appeared in
380 .Bx 4.3 Reno .
381 The
382 .\".Fn getpwent_r ,
383 .\".Fn getpwnam_r ,
384 .Fn getpwnam_r
385 and
386 .Fn getpwuid_r
387 functions appeared in
388 .Fx 5.1 .
389 The functions
390 .Fn getpwuuid
391 and
392 .Fn getpwuuid_r
393 appeared in Mac OS X 10.8.
394 .Sh BUGS
395 The functions
396 .Fn getpwent ,
397 .Fn getpwnam ,
398 .Fn getpwuid ,
399 and
400 .Fn getpwuuid ,
401 .\"leave their results in an internal static object and return
402 leave their results in an internal thread-specific memory and return
403 a pointer to that object.
404 Subsequent calls to
405 the same function
406 will modify the same object.
407 .\".Pp
408 .\"The functions
409 .\".Fn getpwent ,
410 .\".Fn getpwent_r ,
411 .\".Fn endpwent ,
412 .\".Fn setpassent ,
413 .\"and
414 .\".Fn setpwent
415 .\"are fairly useless in a networked environment and should be
416 .\"avoided, if possible.
417 .\"The
418 .\".Fn getpwent
419 .\"and
420 .\".Fn getpwent_r
421 .\"functions
422 .\"make no attempt to suppress duplicate information if multiple
423 .\"sources are specified in
424 .\".Xr nsswitch.conf 5 .