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