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 .Dd October 26, 2011
  32 .Dt GETPWENT 3
  33 .Os
  34 .Sh NAME
  35 .Nm getpwent ,
  36 .\".Nm getpwent_r ,
  37 .Nm getpwnam ,
  38 .Nm getpwnam_r ,
  39 .Nm getpwuid ,
  40 .Nm getpwuid_r ,
  41 .Nm getpwuuid ,
  42 .Nm getpwuuid_r ,
  43 .Nm setpassent ,
  44 .Nm setpwent ,
  45 .Nm endpwent
  46 .Nd password database operations
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In sys/types.h
  51 .In pwd.h
  52 .In uuid/uuid.h
  53 .Ft struct passwd *
  54 .Fn getpwent void
  55 .\".Ft int
  56 .\".Fn getpwent_r "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result"
  57 .Ft struct passwd *
  58 .Fn getpwnam "const char *login"
  59 .Ft int
  60 .Fn getpwnam_r "const char *name" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result"
  61 .Ft struct passwd *
  62 .Fn getpwuid "uid_t uid"
  63 .Ft int
  64 .Fn getpwuid_r "uid_t uid" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result"
  65 .Ft int
  66 .Fn getpwuuid "uuid_t uuid"
  67 .Ft int
  68 .Fn getpwuuid_r "uuid_t uuid" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result"
  69 .Ft int
  70 .Fn setpassent "int stayopen"
  71 .Ft void
  72 .Fn setpwent void
  73 .Ft void
  74 .Fn endpwent void
  75 .Sh DESCRIPTION
  76 These functions
  77 .\"operate on the password database file
  78 obtain information from
  79 .Xr opendirectoryd 8 ,
  80 including records in
  81 .Pa /etc/master.passwd
  82 which is described
  83 in
  84 .Xr master.passwd 5 .
  85 Each entry in the database is defined by the structure
  86 .Vt passwd
  87 found in the include
  88 file
  89 .In pwd.h :
  90 .Bd -literal -offset indent
  91 struct passwd {
  92         char    *pw_name;       /* user name */
  93         char    *pw_passwd;     /* encrypted password */
  94         uid_t   pw_uid;         /* user uid */
  95         gid_t   pw_gid;         /* user gid */
  96         time_t  pw_change;      /* password change time */
  97         char    *pw_class;      /* user access class */
  98         char    *pw_gecos;      /* Honeywell login info */
  99         char    *pw_dir;        /* home directory */
 100         char    *pw_shell;      /* default shell */
 101         time_t  pw_expire;      /* account expiration */
 102         int     pw_fields;      /* internal: fields filled in */
 103 };
 104 .Ed
 105 .Pp
 106 The functions
 107 .Fn getpwnam ,
 108 .Fn getpwuid ,
 109 and
 110 .Fn getpwuuid
 111 search the password database for the given login name, user uid, or user uuid
 112 respectively, always returning the first one encountered.
 113 .Pp
 114 Note that the password file
 115 .Pa /etc/master.passwd
 116 does not contain user UUIDs.
 117 The UUID for a user may be found using
 118 .Fn mbr_uid_to_uuid .
 119 .Pp
 120 On Mac OS X, these routines are thread-safe and return a pointer to a
 121 thread-specific data structure.  The contents of this data
 122 structure are automatically released by subsequent calls to
 123 any of these routines on the same thread, or when the thread exits.
 124 These routines are therefore unsuitable for use in libraries or frameworks,
 125 from where they may overwrite the per-thread data that the calling
 126 application expects to find as a result of its own calls to these
 127 routines. Library and framework code should use the alternative reentrant
 128 variants detailed below.
 129 .Pp
 130 The
 131 .Fn getpwent
 132 function
 133 sequentially reads the password database and is intended for programs
 134 that wish to process the complete list of users.
 135 .Pp
 136 The functions
 137 .Fn getpwnam_r ,
 138 .Fn getpwuid_r ,
 139 and
 140 .Fn getpwuuid_r
 141 are alternative versions of
 142 .Fn getpwnam ,
 143 .Fn getpwuid ,
 144 and
 145 .Fn getpwuuid
 146 respectively.
 147 They store the results of their search in the caller-provided
 148 .Fa pwd
 149 structure, which additionally contains pointers to strings that are
 150 stored in the caller-provided
 151 .Fa buffer
 152 of size
 153 .Fa bufsize .
 154 (The maximum required
 155 .Fa bufsize
 156 can be obtained by passing the _SC_GETPW_R_SIZE_MAX constant to the
 157 .Xr sysconf 3
 158 call. See example code below.) When these functions are successful, the
 159 .Fa pwd
 160 argument will be filled in, and a pointer to that argument will be
 161 stored in the caller-provided
 162 .Fa result .
 163 If an entry is not found or an error occurs,
 164 .Fa result
 165 will be set to
 166 .Dv NULL .
 167 .Pp
 168 The
 169 .Fn setpassent
 170 function
 171 accomplishes two purposes.
 172 First, it causes
 173 .Fn getpwent
 174 to ``rewind'' to the beginning of the database.
 175 Additionally, if
 176 .Fa stayopen
 177 is non-zero, file descriptors are left open, significantly speeding
 178 up subsequent accesses for all of the routines.
 179 (This latter functionality is unnecessary for
 180 .Fn getpwent
 181 as it does not close its file descriptors by default.)
 182 .Pp
 183 It is dangerous for long-running programs to keep the file descriptors
 184 open as the database will become out of date if it is updated while the
 185 program is running.
 186 .Pp
 187 The
 188 .Fn setpwent
 189 function
 190 is identical to
 191 .Fn setpassent
 192 with an argument of zero.
 193 .Pp
 194 The
 195 .Fn endpwent
 196 function
 197 closes any open files.
 198 .Pp
 199 .\"These routines have been written to ``shadow'' the password file, e.g.\&
 200 .\"allow only certain programs to have access to the encrypted password.
 201 .\"If the process which calls them has an effective uid of 0, the encrypted
 202 .\"password will be returned, otherwise, the password field of the returned
 203 .\"structure will point to the string
 204 These routines have been written to
 205 .Ql shadow
 206 the password of user records created on Mac OS X 10.3 or later,
 207 by returning a structure whose password field points to the string
 208 .Ql ******** .
 209 Legacy crypt passwords are still returned for user records created on
 210 earlier versions of Mac OS X whose
 211 .Xr opendirectoryd 8
 212 .Dt AuthenticationAuthority
 213 attribute contains the value
 214 .Ql ;basic; .
 215 .Sh RETURN VALUES
 216 The functions
 217 .Fn getpwent ,
 218 .Fn getpwnam ,
 219 .Fn getpwuid ,
 220 and
 221 .Fn getpwuuid
 222 return a valid pointer to a passwd structure on success
 223 or
 224 .Dv NULL
 225 if the entry is not found or if an error occurs.
 226 If an error does occur,
 227 .Va errno
 228 will be set.
 229 Note that programs must explicitly set
 230 .Va errno
 231 to zero before calling any of these functions if they need to
 232 distinguish between a non-existent entry and an error.
 233 The functions
 234 .Fn getpwnam_r ,
 235 .Fn getpwuid_r ,
 236 and
 237 .Fn getpwuuid_r
 238 return 0 if no error occurred, or an error number to indicate failure.
 239 It is not an error if a matching entry is not found.
 240 (Thus, if
 241 .Fa result
 242 is
 243 .Dv NULL
 244 and the return value is 0, no matching entry exists.)
 245 .Pp
 246 The
 247 .Fn setpassent
 248 function returns 0 on failure and 1 on success.
 249 The
 250 .Fn endpwent
 251 and
 252 .Fn setpwent
 253 functions
 254 have no return value.
 255 .Sh EXAMPLES
 256 To print the current user's home directory without depending on per-thread storage:
 257 .Bd -literal -offset indent
 258 #include <sys/types.h>
 259 #include <unistd.h>
 260 #include <stdlib.h>
 261 #include <stdio.h>
 262 #include <pwd.h>
 263
 264 int bufsize;
 265
 266 if ((bufsize = sysconf(_SC_GETPW_R_SIZE_MAX)) == -1)
 267     abort();
 268
 269 char buffer[bufsize];
 270 struct passwd pwd, *result = NULL;
 271 if (getpwuid_r(getuid(), &pwd, buffer, bufsize, &result) != 0 || !result)
 272     abort();
 273
 274 printf("%s\\n", pwd.pw_dir);
 275 .Ed
 276 .Sh FILES
 277 .Bl -tag -width /etc/master.passwd -compact
 278 .\".It Pa /etc/pwd.db
 279 .\"The insecure password database file
 280 .\".It Pa /etc/spwd.db
 281 The secure password database file
 282 .It Pa /etc/master.passwd
 283 The current password file
 284 .It Pa /etc/passwd
 285 A Version 7 format password file
 286 .El
 287 .\".Sh COMPATIBILITY
 288 .\"The historic function
 289 .\".Xr setpwfile 3 ,
 290 .\"which allowed the specification of alternate password databases,
 291 .\"has been deprecated and is no longer available.
 292 .Sh ERRORS
 293 These routines may fail for any of the errors specified in
 294 .Xr open 2 ,
 295 .Xr dbopen 3 ,
 296 .Xr socket 2 ,
 297 and
 298 .Xr connect 2 ,
 299 in addition to the following:
 300 .Bl -tag -width Er
 301 .It Bq Er ERANGE
 302 The buffer specified by the
 303 .Fa buffer
 304 and
 305 .Fa bufsize
 306 arguments was insufficiently sized to store the result.
 307 The caller should retry with a larger buffer.
 308 .El
 309 .Sh SEE ALSO
 310 .Xr getlogin 2 ,
 311 .Xr getgrent 3 ,
 312 .\".Xr nsswitch.conf 5 ,
 313 .Xr passwd 5 ,
 314 .\".Xr pwd_mkdb 8 ,
 315 .\".Xr vipw 8 ,
 316 .Xr mbr_uid_to_uuid 3,
 317 .Xr opendirectoryd 8 ,
 318 .Xr yp 8
 319 .Sh STANDARDS
 320 The
 321 .Fn getpwent ,
 322 .Fn getpwnam ,
 323 .Fn getpwnam_r ,
 324 .Fn getpwuid ,
 325 .Fn getpwuid_r ,
 326 .Fn setpwent ,
 327 and
 328 .Fn endpwent
 329 functions conform to
 330 .St -p1003.1-96 .
 331 .Sh HISTORY
 332 The
 333 .Fn getpwent ,
 334 .Fn getpwnam ,
 335 .Fn getpwuid ,
 336 .Fn setpwent ,
 337 and
 338 .Fn endpwent
 339 functions appeared in
 340 .At v7 .
 341 The
 342 .Fn setpassent
 343 function appeared in
 344 .Bx 4.3 Reno .
 345 The
 346 .\".Fn getpwent_r ,
 347 .\".Fn getpwnam_r ,
 348 .Fn getpwnam_r
 349 and
 350 .Fn getpwuid_r
 351 functions appeared in
 352 .Fx 5.1 .
 353 The functions
 354 .Fn getpwuuid
 355 and
 356 .Fn getpwuuid_r
 357 appeared in Mac OS X 10.8.
 358 .Sh BUGS
 359 The functions
 360 .Fn getpwent ,
 361 .Fn getpwnam ,
 362 .Fn getpwuid ,
 363 and
 364 .Fn getpwuuid ,
 365 .\"leave their results in an internal static object and return
 366 leave their results in an internal thread-specific memory and return
 367 a pointer to that object.
 368 Subsequent calls to
 369 the same function
 370 will modify the same object.
 371 .\".Pp
 372 .\"The functions
 373 .\".Fn getpwent ,
 374 .\".Fn getpwent_r ,
 375 .\".Fn endpwent ,
 376 .\".Fn setpassent ,
 377 .\"and
 378 .\".Fn setpwent
 379 .\"are fairly useless in a networked environment and should be
 380 .\"avoided, if possible.
 381 .\"The
 382 .\".Fn getpwent
 383 .\"and
 384 .\".Fn getpwent_r
 385 .\"functions
 386 .\"make no attempt to suppress duplicate information if multiple
 387 .\"sources are specified in
 388 .\".Xr nsswitch.conf 5 .