1.\" $NetBSD: getpwent.3,v 1.40 2018/02/07 11:16:05 pgoyette 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 February 7, 2018 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 86These functions 87operate on the password database 88which is described 89in 90.Xr passwd 5 . 91Each entry in the database is defined by the structure 92.Ar passwd 93found in the include 94file 95.In pwd.h : 96.Bd -literal -offset indent 97struct 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 111The functions 112.Fn getpwnam 113and 114.Fn getpwuid 115search the password database for the given user name pointed to by 116.Ar name 117or user id pointed to by 118.Ar uid 119respectively, always returning the first one encountered. 120Identical user names or user ids may result in undefined behavior. 121.Pp 122The 123.Fn getpwent 124function 125sequentially reads the password database and is intended for programs 126that wish to process the complete list of users. 127.Pp 128The functions 129.Fn getpwnam_r , 130.Fn getpwuid_r , 131and 132.Fn getpwent_r 133act like their non re-entrant counterparts, updating the contents of 134.Ar pw 135and storing a pointer to that in 136.Ar result , 137and returning 138.Dv 0 . 139Storage used by 140.Ar pw 141is allocated from 142.Ar buffer , 143which is 144.Ar buflen 145bytes in size. 146If the requested entry cannot be found, 147.Ar result 148will point to 149.Dv NULL 150and 151.Dv 0 152will be returned. 153If an error occurs, 154a non-zero error number will be returned and 155.Ar result 156will point to 157.Dv NULL . 158Calling 159.Fn getpwent_r 160from multiple threads will result in each thread reading a disjoint portion 161of the password database. 162.Pp 163The 164.Fn setpassent 165function 166accomplishes two purposes. 167First, it causes 168.Fn getpwent 169to 170.Dq rewind 171to the beginning of the database. 172Additionally, if 173.Fa stayopen 174is non-zero, file descriptors are left open, significantly speeding 175up subsequent accesses for all of the functions. 176(This latter functionality is unnecessary for 177.Fn getpwent 178as it doesn't close its file descriptors by default.) 179.Pp 180It is dangerous for long-running programs to keep the file descriptors 181open as the database will become out of date if it is updated while the 182program is running. 183.Pp 184The 185.Fn setpwent 186function 187is equivalent to 188.Fn setpassent 189with an argument of zero. 190.Pp 191The 192.Fn endpwent 193function 194closes any open files. 195.Pp 196These functions have been written to 197.Dq shadow 198the password file, e.g. allow only certain programs to have access 199to the encrypted password. 200If the process which calls them has an effective uid of 0, the encrypted 201password will be returned, otherwise, the password field of the returned 202structure will point to the string 203.Ql * . 204.Sh RETURN VALUES 205The functions 206.Fn getpwent , 207.Fn getpwnam , 208and 209.Fn getpwuid , 210return a valid pointer to a passwd structure on success 211and a 212.Dv NULL 213pointer if the entry was not found or an error occurred. 214If an error occurred, the global variable 215.Dv errno 216is set to indicate the nature of the failure. 217The 218.Fn setpassent 219function returns 0 on failure, setting the global variable 220.Dv errno 221to indicate the nature of the failure, and 1 on success. 222The 223.Fn endpwent 224and 225.Fn setpwent 226functions 227have no return value. 228The functions 229.Fn getpwnam_r , 230.Fn getpwuid_r , 231and 232.Fn getpwent_r 233return 234.Dv 0 235on success or entry not found, and non-zero on failure, setting the global 236variable 237.Dv errno 238to indicate the nature of the failure. 239.Sh FILES 240.Bl -tag -width /etc/master.passwd -compact 241.It Pa /etc/pwd.db 242The insecure password database file 243.It Pa /etc/spwd.db 244The secure password database file 245.It Pa /etc/master.passwd 246The current password file 247.It Pa /etc/passwd 248A Version 7 format password file 249.El 250.Sh COMPATIBILITY 251The historic function 252.Fn setpwfile 253which allowed the specification of alternative password databases, 254has been deprecated and is no longer available. 255.Sh ERRORS 256The following error codes may be set in 257.Va errno 258for 259.Nm getpwent , 260.Nm getpwent_r , 261.Nm getpwnam , 262.Nm getpwnam_r , 263.Nm getpwuid , 264.Nm getpwuid_r , 265and 266.Nm setpassent : 267.Bl -tag -width Er 268.It Bq Er EINTR 269A signal was caught during the database search. 270.It Bq Er EIO 271An I/O error has occurred. 272.It Bq Er EMFILE 273The limit on open files for this process has been reached. 274.It Bq Er ENFILE 275The system limit on open files has been reached. 276.El 277.Pp 278The following error code may be set in 279.Va errno 280for 281.Nm getpwent_r , 282.Nm getpwnam_r , 283and 284.Nm getpwuid_r : 285.Bl -tag -width Er 286.It Bq Er ERANGE 287The resulting 288.Ft struct passwd 289does not fit in the space defined by 290.Dv buffer 291and 292.Dv buflen . 293.El 294.Pp 295Other 296.Dv errno 297values 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 307The 308.Fn getpwnam 309and 310.Fn getpwuid , 311functions conform to 312.St -p1003.1-90 . 313The 314.Fn getpwnam_r 315and 316.Fn getpwuid_r 317functions conform to 318.St -p1003.1c-95 . 319The 320.Fn endpwent , 321.Fn getpwent , 322and 323.Fn setpwent 324functions conform to 325.St -xpg4.2 326and 327.St -p1003.1-2004 328(XSI extension). 329.Sh HISTORY 330The 331.Nm getpwent , 332.Nm getpwnam , 333.Nm getpwuid , 334.Nm setpwent , 335and 336.Nm endpwent 337functions appeared in 338.At v7 . 339The 340.Nm setpassent 341function appeared in 342.Bx 4.3 Reno . 343The functions 344.Fn getpwnam_r 345and 346.Fn getpwuid_r 347appeared in 348.Nx 3.0 . 349.Sh BUGS 350The functions 351.Fn getpwent , 352.Fn getpwnam , 353and 354.Fn getpwuid , 355leave their results in an internal static object and return 356a pointer to that object. 357Subsequent calls to any of these functions will modify the same object. 358.Pp 359The functions 360.Fn getpwent , 361.Fn endpwent , 362.Fn setpassent , 363and 364.Fn setpwent 365are fairly useless in a networked environment and should be 366avoided, if possible. 367.Fn getpwent 368makes no attempt to suppress duplicate information if multiple 369sources are specified in 370.Xr nsswitch.conf 5 . 371