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