lib/libc/gen/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 .\" $DragonFly: src/lib/libc/gen/getpwent.3,v 1.5 2006/05/26 19:39:36 swildner Exp $
  31 .\"
  32 .Dd April 16, 2003
  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 sys/types.h
  50 .In pwd.h
  51 .Ft struct passwd *
  52 .Fn getpwent void
  53 .Ft int
  54 .Fn getpwent_r "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result"
  55 .Ft struct passwd *
  56 .Fn getpwnam "const char *login"
  57 .Ft int
  58 .Fn getpwnam_r "const char *name" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result"
  59 .Ft struct passwd *
  60 .Fn getpwuid "uid_t uid"
  61 .Ft int
  62 .Fn getpwuid_r "uid_t uid" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result"
  63 .Ft int
  64 .Fn setpassent "int stayopen"
  65 .Ft void
  66 .Fn setpwent void
  67 .Ft void
  68 .Fn endpwent void
  69 .Sh DESCRIPTION
  70 These functions
  71 operate on the password database file
  72 which is described
  73 in
  74 .Xr passwd 5 .
  75 Each entry in the database is defined by the structure
  76 .Vt passwd
  77 found in the include
  78 file
  79 .In pwd.h :
  80 .Bd -literal -offset indent
  81 struct passwd {
  82         char    *pw_name;       /* user name */
  83         char    *pw_passwd;     /* encrypted password */
  84         uid_t   pw_uid;         /* user uid */
  85         gid_t   pw_gid;         /* user gid */
  86         time_t  pw_change;      /* password change time */
  87         char    *pw_class;      /* user access class */
  88         char    *pw_gecos;      /* Honeywell login info */
  89         char    *pw_dir;        /* home directory */
  90         char    *pw_shell;      /* default shell */
  91         time_t  pw_expire;      /* account expiration */
  92         int     pw_fields;      /* internal: fields filled in */
  93 };
  94 .Ed
  95 .Pp
  96 The functions
  97 .Fn getpwnam
  98 and
  99 .Fn getpwuid
 100 search the password database for the given login name or user uid,
 101 respectively, always returning the first one encountered.
 102 .Pp
 103 The
 104 .Fn getpwent
 105 function
 106 sequentially reads the password database and is intended for programs
 107 that wish to process the complete list of users.
 108 .Pp
 109 The functions
 110 .Fn getpwent_r ,
 111 .Fn getpwnam_r ,
 112 and
 113 .Fn getpwuid_r
 114 are thread-safe versions of
 115 .Fn getpwent ,
 116 .Fn getpwnam ,
 117 and
 118 .Fn getpwuid ,
 119 respectively.
 120 The caller must provide storage for the results of the search in
 121 the
 122 .Fa pwd ,
 123 .Fa buffer ,
 124 .Fa bufsize ,
 125 and
 126 .Fa result
 127 arguments.
 128 When these functions are successful, the
 129 .Fa pwd
 130 argument will be filled-in, and a pointer to that argument will be
 131 stored in
 132 .Fa result .
 133 If an entry is not found or an error occurs,
 134 .Fa result
 135 will be set to
 136 .Dv NULL .
 137 .Pp
 138 The
 139 .Fn setpassent
 140 function
 141 accomplishes two purposes.
 142 First, it causes
 143 .Fn getpwent
 144 to ``rewind'' to the beginning of the database.
 145 Additionally, if
 146 .Fa stayopen
 147 is non-zero, file descriptors are left open, significantly speeding
 148 up subsequent accesses for all of the routines.
 149 (This latter functionality is unnecessary for
 150 .Fn getpwent
 151 as it does not close its file descriptors by default.)
 152 .Pp
 153 It is dangerous for long-running programs to keep the file descriptors
 154 open as the database will become out of date if it is updated while the
 155 program is running.
 156 .Pp
 157 The
 158 .Fn setpwent
 159 function
 160 is identical to
 161 .Fn setpassent
 162 with an argument of zero.
 163 .Pp
 164 The
 165 .Fn endpwent
 166 function
 167 closes any open files.
 168 .Pp
 169 These routines have been written to ``shadow'' the password file, e.g.\&
 170 allow only certain programs to have access to the encrypted password.
 171 If the process which calls them has an effective uid of 0, the encrypted
 172 password will be returned, otherwise, the password field of the returned
 173 structure will point to the string
 174 .Ql * .
 175 .Sh RETURN VALUES
 176 The functions
 177 .Fn getpwent ,
 178 .Fn getpwnam ,
 179 and
 180 .Fn getpwuid
 181 return a valid pointer to a passwd structure on success
 182 or
 183 .Dv NULL
 184 if the entry is not found or if an error occurs.
 185 If an error does occur,
 186 .Va errno
 187 will be set.
 188 Note that programs must explicitly set
 189 .Va errno
 190 to zero before calling any of these functions if they need to
 191 distinguish between a non-existent entry and an error.
 192 The functions
 193 .Fn getpwent_r ,
 194 .Fn getpwnam_r ,
 195 and
 196 .Fn getpwuid_r
 197 return 0 if no error occurred, or an error number to indicate failure.
 198 It is not an error if a matching entry is not found.
 199 (Thus, if
 200 .Fa result
 201 is
 202 .Dv NULL
 203 and the return value is 0, no matching entry exists.)
 204 .Pp
 205 The
 206 .Fn setpassent
 207 function returns 0 on failure and 1 on success.
 208 The
 209 .Fn endpwent
 210 and
 211 .Fn setpwent
 212 functions
 213 have no return value.
 214 .Sh FILES
 215 .Bl -tag -width /etc/master.passwd -compact
 216 .It Pa /etc/pwd.db
 217 The insecure password database file
 218 .It Pa /etc/spwd.db
 219 The secure password database file
 220 .It Pa /etc/master.passwd
 221 The current password file
 222 .It Pa /etc/passwd
 223 A Version 7 format password file
 224 .El
 225 .Sh COMPATIBILITY
 226 The historic function
 227 .Xr setpwfile 3 ,
 228 which allowed the specification of alternate password databases,
 229 has been deprecated and is no longer available.
 230 .Sh ERRORS
 231 These routines may fail for any of the errors specified in
 232 .Xr open 2 ,
 233 .Xr dbopen 3 ,
 234 .Xr socket 2 ,
 235 and
 236 .Xr connect 2 ,
 237 in addition to the following:
 238 .Bl -tag -width Er
 239 .It Bq Er ERANGE
 240 The buffer specified by the
 241 .Fa buffer
 242 and
 243 .Fa bufsize
 244 arguments was insufficiently sized to store the result.
 245 The caller should retry with a larger buffer.
 246 .El
 247 .Sh SEE ALSO
 248 .Xr getlogin 2 ,
 249 .Xr getgrent 3 ,
 250 .Xr nsswitch.conf 5 ,
 251 .Xr passwd 5 ,
 252 .Xr pwd_mkdb 8 ,
 253 .Xr vipw 8 ,
 254 .Xr yp 8
 255 .Sh STANDARDS
 256 The
 257 .Fn getpwent ,
 258 .Fn getpwnam ,
 259 .Fn getpwnam_r ,
 260 .Fn getpwuid ,
 261 .Fn getpwuid_r ,
 262 .Fn setpwent ,
 263 and
 264 .Fn endpwent
 265 functions conform to
 266 .St -p1003.1-96 .
 267 .Sh HISTORY
 268 The
 269 .Fn getpwent ,
 270 .Fn getpwnam ,
 271 .Fn getpwuid ,
 272 .Fn setpwent ,
 273 and
 274 .Fn endpwent
 275 functions appeared in
 276 .At v7 .
 277 The
 278 .Fn setpassent
 279 function appeared in
 280 .Bx 4.3 Reno .
 281 The
 282 .Fn getpwent_r ,
 283 .Fn getpwnam_r ,
 284 and
 285 .Fn getpwuid_r
 286 functions appeared in
 287 .Fx 5.1
 288 and
 289 .Dx 2.1 .
 290 .Sh BUGS
 291 The functions
 292 .Fn getpwent ,
 293 .Fn getpwnam ,
 294 and
 295 .Fn getpwuid ,
 296 leave their results in an internal static object and return
 297 a pointer to that object.
 298 Subsequent calls to
 299 the same function
 300 will modify the same object.
 301 .Pp
 302 The functions
 303 .Fn getpwent ,
 304 .Fn getpwent_r ,
 305 .Fn endpwent ,
 306 .Fn setpassent ,
 307 and
 308 .Fn setpwent
 309 are fairly useless in a networked environment and should be
 310 avoided, if possible.
 311 The
 312 .Fn getpwent
 313 and
 314 .Fn getpwent_r
 315 functions
 316 make no attempt to suppress duplicate information if multiple
 317 sources are specified in
 318 .Xr nsswitch.conf 5 .