lib/libc/gen/getpwent.3

   1 .\"     $NetBSD: getpwent.3,v 1.35 2005/05/25 10:05:22 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 .Aq Pa 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.