1.\" $NetBSD: getpwent.3,v 1.35 2005/05/25 10:05:22 wiz 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 May 24, 2005 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.Aq Pa 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 occurs. 214The 215.Fn setpassent 216function returns 0 on failure and 1 on success. 217The 218.Fn endpwent 219and 220.Fn setpwent 221functions 222have no return value. 223The functions 224.Fn getpwnam_r , 225.Fn getpwuid_r , 226and 227.Fn getpwent_r 228return 229.Dv 0 230on success or entry not found, and non-zero on failure. 231.Sh FILES 232.Bl -tag -width /etc/master.passwd -compact 233.It Pa /etc/pwd.db 234The insecure password database file 235.It Pa /etc/spwd.db 236The secure password database file 237.It Pa /etc/master.passwd 238The current password file 239.It Pa /etc/passwd 240A Version 7 format password file 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 passwd.conf 5 , 248.Xr pwd_mkdb 8 , 249.Xr vipw 8 250.Sh STANDARDS 251The 252.Fn getpwnam 253and 254.Fn getpwuid , 255functions conform to 256.St -p1003.1-90 . 257The 258.Fn getpwnam_r 259and 260.Fn getpwuid_r 261functions conform to 262.St -p1003.1c-95 . 263The 264.Fn endpwent , 265.Fn getpwent , 266and 267.Fn setpwent 268functions conform to 269.St -xpg4.2 270and 271.St -p1003.1-2004 272(XSI extension). 273.Sh HISTORY 274The 275.Nm getpwent , 276.Nm getpwnam , 277.Nm getpwuid , 278.Nm setpwent , 279and 280.Nm endpwent 281functions appeared in 282.At v7 . 283The 284.Nm setpassent 285function appeared in 286.Bx 4.3 Reno . 287The functions 288.Fn getpwnam_r 289and 290.Fn getpwuid_r 291appeared in 292.Nx 3.0 . 293.Sh BUGS 294The functions 295.Fn getpwent , 296.Fn getpwnam , 297and 298.Fn getpwuid , 299leave their results in an internal static object and return 300a pointer to that object. 301Subsequent calls to any of these functions will modify the same object. 302.Pp 303The functions 304.Fn getpwent , 305.Fn endpwent , 306.Fn setpassent , 307and 308.Fn setpwent 309are fairly useless in a networked environment and should be 310avoided, if possible. 311.Fn getpwent 312makes no attempt to suppress duplicate information if multiple 313sources are specified in 314.Xr nsswitch.conf 5 . 315.Sh COMPATIBILITY 316The historic function 317.Fn setpwfile 318which allowed the specification of alternative password databases, 319has been deprecated and is no longer available. 320