lib/libc/gen/getpwent.3

   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 .