1.\" $NetBSD: getpwent.3,v 1.37 2010/03/22 19:30:53 joerg 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 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 occured. 214If an error occured, 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 ERRORS 240The following error codes may be set in 241.Va errno 242for 243.Nm getpwent , 244.Nm getpwent_r , 245.Nm getpwnam , 246.Nm getpwnam_r , 247.Nm getpwuid , 248.Nm getpwuid_r , 249and 250.Nm setpassent : 251.Bl -tag -width Er 252.It Bq Er EIO 253An I/O error has occurred. 254.It Bq Er EINTR 255A signal was caught during the database search. 256.It Bq Er EMFILE 257The limit on open files for this process has been reached. 258.It Bq Er ENFILE 259The system limit on open files has been reached. 260.El 261.Pp 262The following error code may be set in 263.Va errno 264for 265.Nm getpwent_r , 266.Nm getpwnam_r , 267and 268.Nm getpwuid_r : 269.Bl -tag -width Er 270.It Bq Er ERANGE 271The resulting 272.Ft struct passwd 273does not fit in the space defined by 274.Dv buffer 275and 276.Dv buflen 277.El 278.Pp 279Other 280.Dv errno 281values may be set depending on the specific database backends. 282.Sh FILES 283.Bl -tag -width /etc/master.passwd -compact 284.It Pa /etc/pwd.db 285The insecure password database file 286.It Pa /etc/spwd.db 287The secure password database file 288.It Pa /etc/master.passwd 289The current password file 290.It Pa /etc/passwd 291A Version 7 format password file 292.El 293.Sh SEE ALSO 294.Xr getlogin 2 , 295.Xr getgrent 3 , 296.Xr nsswitch.conf 5 , 297.Xr passwd 5 , 298.Xr passwd.conf 5 , 299.Xr pwd_mkdb 8 , 300.Xr vipw 8 301.Sh STANDARDS 302The 303.Fn getpwnam 304and 305.Fn getpwuid , 306functions conform to 307.St -p1003.1-90 . 308The 309.Fn getpwnam_r 310and 311.Fn getpwuid_r 312functions conform to 313.St -p1003.1c-95 . 314The 315.Fn endpwent , 316.Fn getpwent , 317and 318.Fn setpwent 319functions conform to 320.St -xpg4.2 321and 322.St -p1003.1-2004 323(XSI extension). 324.Sh HISTORY 325The 326.Nm getpwent , 327.Nm getpwnam , 328.Nm getpwuid , 329.Nm setpwent , 330and 331.Nm endpwent 332functions appeared in 333.At v7 . 334The 335.Nm setpassent 336function appeared in 337.Bx 4.3 Reno . 338The functions 339.Fn getpwnam_r 340and 341.Fn getpwuid_r 342appeared in 343.Nx 3.0 . 344.Sh BUGS 345The functions 346.Fn getpwent , 347.Fn getpwnam , 348and 349.Fn getpwuid , 350leave their results in an internal static object and return 351a pointer to that object. 352Subsequent calls to any of these functions will modify the same object. 353.Pp 354The functions 355.Fn getpwent , 356.Fn endpwent , 357.Fn setpassent , 358and 359.Fn setpwent 360are fairly useless in a networked environment and should be 361avoided, if possible. 362.Fn getpwent 363makes no attempt to suppress duplicate information if multiple 364sources are specified in 365.Xr nsswitch.conf 5 . 366.Sh COMPATIBILITY 367The historic function 368.Fn setpwfile 369which allowed the specification of alternative password databases, 370has been deprecated and is no longer available. 371