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