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 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     From: @(#)getpwent.3    8.2 (Berkeley) 12/11/93
  33 .\" $FreeBSD: src/lib/libc/gen/getpwent.3,v 1.18 2001/10/01 16:08:51 ru Exp $
  34 .\"
  35 .Dd September 20, 1994
  36 .Dt GETPWENT 3
  37 .Os
  38 .Sh NAME
  39 .Nm endpwent ,
  40 .Nm getpwent ,
  41 .Nm getpwnam ,
  42 .Nm getpwnam_r ,
  43 .Nm getpwuid ,
  44 .Nm getpwuid_r ,
  45 .Nm setpassent ,
  46 .Nm setpwent
  47 .Nd password database operations
  48 .Sh LIBRARY
  49 .Lb libc
  50 .Sh SYNOPSIS
  51 .In pwd.h
  52 .Ft void
  53 .Fo endpwent
  54 .Fa void
  55 .Fc
  56 .Ft struct passwd *
  57 .Fo getpwent
  58 .Fa void
  59 .Fc
  60 .Ft struct passwd *
  61 .Fo getpwnam
  62 .Fa "const char *login"
  63 .Fc
  64 .Ft int
  65 .Fo getpwnam_r
  66 .Fa "const char *login"
  67 .Fa "struct passwd *pwd"
  68 .Fa "char *buffer"
  69 .Fa "size_t bufsize"
  70 .Fa "struct passwd **result"
  71 .Fc
  72 .Ft struct passwd *
  73 .Fo getpwuid
  74 .Fa "uid_t uid"
  75 .Fc
  76 .Ft int
  77 .Fo getuid_r
  78 .Fa "uid_t uid"
  79 .Fa "struct passwd *pwd"
  80 .Fa "char *buffer"
  81 .Fa "size_t bufsize"
  82 .Fa "struct passwd **result"
  83 .Fc
  84 .Ft int
  85 .Fo setpassent
  86 .Fa "int stayopen"
  87 .Fc
  88 .Ft void
  89 .Fo setpwent
  90 .Fa void
  91 .Fc
  92 .Sh DESCRIPTION
  93 These functions
  94 operate on the password database file,
  95 which is described
  96 in
  97 .Xr passwd 5 .
  98 Each entry in the database is defined by the structure
  99 .Ar passwd ,
 100 found in the include file
 101 .Aq Pa pwd.h :
 102 .Bd -literal -offset indent
 103 struct passwd {
 104         char    *pw_name;       /* user name */
 105         char    *pw_passwd;     /* encrypted password */
 106         uid_t   pw_uid;         /* user uid */
 107         gid_t   pw_gid;         /* user gid */
 108         time_t  pw_change;      /* password change time */
 109         char    *pw_class;      /* user access class */
 110         char    *pw_gecos;      /* Honeywell login info */
 111         char    *pw_dir;        /* home directory */
 112         char    *pw_shell;      /* default shell */
 113         time_t  pw_expire;      /* account expiration */
 114         int     pw_fields;      /* internal: fields filled in */
 115 };
 116 .Ed
 117 .Pp
 118 The functions
 119 .Fn getpwnam
 120 and
 121 .Fn getpwuid
 122 search the password database for the given login name or user uid,
 123 respectively, always returning the first one encountered.
 124 .Pp
 125 All of these routines are thread-safe.
 126 The
 127 .Fn getpwent ,
 128 .Fn getpwnam ,
 129 and
 130 .Fn getpwuid
 131 routines return a pointer to a result managed by the system library in a
 132 thread-specific data structure.
 133 Every thread has space for a pointer to a struct passwd and allocates its own storage for the result.
 134 Neither previously returned values in memory nor a previously returned pointer value should be used
 135 by a thread after calling any one of these three routines.
 136 Memory allocated by a thread is automatically released on subsequent calls by the same thread to any of these
 137 three routines, and when the thread exits.
 138 .Pp
 139 The functions
 140 .Fn getpwnam_r
 141 and
 142 .Fn getpwuid_r
 143 take additional arguments which supply storage space for the returned result.
 144 The
 145 .Fa pwd
 146 parameter is a pointer to a struct passwd, which must be allocated by the caller.
 147 The
 148 .Fa buffer
 149 parameter is a pointer to a block of memory with a size specified by
 150 .Pa bufsize .
 151 This buffer is used to hold the values which are pointed to by values filled in
 152 the
 153 .Fa pwd
 154 structure.
 155 Zero is returned on success.
 156 If insufficient memory is supplied, these routines return ERANGE.
 157 .Pp
 158 The
 159 .Fn getpwent
 160 function
 161 sequentially reads the password database and is intended for programs
 162 that wish to process the complete list of users.
 163 .Pp
 164 The
 165 .Fn setpassent
 166 function
 167 accomplishes two purposes.
 168 First, it causes
 169 .Fn getpwent
 170 to ``rewind'' to the beginning of the database.
 171 Additionally, if
 172 .Fa stayopen
 173 is non-zero, file descriptors are left open, significantly speeding
 174 up subsequent accesses for all of the routines.
 175 (This latter functionality is unnecessary for
 176 .Fn getpwent ,
 177 as it doesn't close its file descriptors by default.)
 178 .Pp
 179 It is dangerous for long-running programs to keep the file descriptors
 180 open, as the database will become out of date if it is updated while the
 181 program is running.
 182 .Pp
 183 The
 184 .Fn setpwent
 185 function
 186 is identical to
 187 .Fn setpassent
 188 with an argument of zero,
 189 save that it does not return a status value.
 190 .Pp
 191 The
 192 .Fn endpwent
 193 function
 194 closes any open files.
 195 .Pp
 196 As of Mac OS X 10.3, there are now different per-user behaviours of
 197 this function, based on the AuthenticationAuthority value
 198 stored for the queried user in DirectoryServices.
 199 .Pp
 200 If the queried user is still a legacy crypt password user or now
 201 has an AuthenticationAuthority value containing ``;basic;'',
 202 these routines will behave in their standard BSD fashion.
 203 These functions will ``shadow'' the password file, e.g.\&
 204 allow only certain programs to have access to the encrypted password.
 205 If the process which calls them has an effective uid of 0, the encrypted
 206 password will be returned, otherwise, the password field of the returned
 207 structure will point to the string
 208 .Ql * .
 209 .Pp
 210 By default in Mac OS X 10.3 and later all users will have an
 211 AuthenticationAuthority with the value ``;ShadowHash;''.
 212 These users will have a visible password value of ``********''.
 213 These functions
 214 will have no access to the encrypted password whatsoever.
 215 Setting or changing
 216 an user password must be done entirely through the DirectoryService APIs
 217 for this default user.
 218 .Pp
 219 There also exists an ``Apple Password Server'' user whose password
 220 value is also ``********'' and with an AuthenticationAuthority that
 221 contains the value ";ApplePasswordServer;" among other data.
 222 There is no getpwnam access to the password for this user either
 223 and again set/change password can be done through the DirectoryService API.
 224 .Pp
 225 Finally in support of local user caching there is a local cached user
 226 whose password is also ``********'' and has an AuthenticationAuthority
 227 value containing ``;LocalCachedUser;'' among other data.
 228 These functions also provide no access to the password for this user
 229 and set/change password functionality is through the DirectoryService API.
 230 .Pp
 231 .Sh RETURN VALUES
 232 The functions
 233 .Fn getpwent ,
 234 .Fn getpwnam ,
 235 and
 236 .Fn getpwuid
 237 return a valid pointer to a passwd structure on success
 238 and a null pointer if end-of-file is reached or an error occurs.
 239 The
 240 .Fn setpassent
 241 function returns 0 on failure and 1 on success.
 242 The
 243 .Fn endpwent
 244 and
 245 .Fn setpwent
 246 functions have no return value.
 247 .Sh FILES
 248 .Bl -tag -width /etc/master.passwd -compact
 249 .It Pa /etc/pwd.db
 250 The insecure password database file
 251 .It Pa /etc/spwd.db
 252 The secure password database file
 253 .It Pa /etc/master.passwd
 254 The current password file
 255 .It Pa /etc/passwd
 256 A Version 7 format password file
 257 .El
 258 .Sh LEGACY SYNOPSIS
 259 .Fd #include <sys/types.h>
 260 .Fd #include <pwd.h>
 261 .Pp
 262 The include file
 263 .In sys/types.h
 264 is necessary for the
 265 .Fa getpwent ,
 266 .Fa getpwnam ,
 267 and
 268 .Fa getpwuid
 269 functions.
 270 .Pp
 271 .Ft int
 272 .br
 273 .Fo setpwent
 274 .Fa void
 275 .Fc ;
 276 .Pp
 277 The
 278 .Fn setpwent
 279 function returns 0 on failure and 1 on success.
 280 .Sh SEE ALSO
 281 .Xr getlogin 2 ,
 282 .Xr getgrent 3 ,
 283 .Xr yp 8 ,
 284 .Xr passwd 5 ,
 285 .Xr pwd_mkdb 8 ,
 286 .Xr vipw 8
 287 .Sh HISTORY
 288 The
 289 .Fn getpwent ,
 290 .Fn getpwnam ,
 291 .Fn getpwuid ,
 292 .Fn setpwent ,
 293 and
 294 .Fn endpwent
 295 functions appeared in
 296 .At v7 .
 297 The
 298 .Fn setpassent
 299 function appeared in
 300 .Bx 4.3 Reno .
 301 .Sh COMPATIBILITY
 302 The historic function
 303 .Xr setpwfile 3 ,
 304 which allowed the specification of alternate password databases,
 305 has been deprecated and is no longer available.
 306 .Sh BUGS
 307 The functions
 308 .Fn getpwent ,
 309 .Fn getpwnam ,
 310 and
 311 .Fn getpwuid
 312 leave their results in internal thread-specific memory and return
 313 a pointer to that object.
 314 Subsequent calls to any of these three routines by the same thread will
 315 release the object and return a new pointer value.