1.\" $OpenBSD: getpwent.3,v 1.33 2022/09/11 06:38:10 jmc 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.Dd $Mdocdate: September 11 2022 $ 31.Dt GETPWENT 3 32.Os 33.Sh NAME 34.Nm getpwent , 35.Nm setpwent , 36.Nm endpwent 37.Nd sequential password database access 38.Sh SYNOPSIS 39.In pwd.h 40.Ft struct passwd * 41.Fn getpwent void 42.Ft void 43.Fn setpwent void 44.Ft void 45.Fn endpwent void 46.Sh DESCRIPTION 47These functions operate on the password database file which is described in 48.Xr passwd 5 . 49Each entry in the database is defined by the structure 50.Vt struct passwd 51found in the include file 52.In pwd.h : 53.Bd -literal -offset indent 54struct passwd { 55 char *pw_name; /* user name */ 56 char *pw_passwd; /* encrypted password */ 57 uid_t pw_uid; /* user uid */ 58 gid_t pw_gid; /* user gid */ 59 time_t pw_change; /* password change time */ 60 char *pw_class; /* user access class */ 61 char *pw_gecos; /* Honeywell login info */ 62 char *pw_dir; /* home directory */ 63 char *pw_shell; /* default shell */ 64 time_t pw_expire; /* account expiration */ 65}; 66.Ed 67.Pp 68The 69.Fn getpwent 70function sequentially reads the password database and is intended for programs 71that wish to process the complete list of users. 72.Pp 73It is dangerous for long-running programs to keep the file descriptors 74open as the database will become out of date if it is updated while the 75program is running. 76However the file descriptors are automatically closed when 77.Xr execve 2 78is called. 79.Pp 80.Fn setpwent 81causes 82.Fn getpwent 83to 84.Dq rewind 85to the beginning of the database. 86.Pp 87The 88.Fn endpwent 89function closes any file descriptors opened by 90.Fn setpwent 91or 92.Fn getpwent . 93.Pp 94These routines have been written to 95.Dq shadow 96the password file, that is, 97allow only certain programs to have access to the encrypted password. 98If the process which calls them has an effective UID of 0 or has the 99.Dq _shadow 100group in its group vector, the encrypted password will be returned, otherwise, 101the password field of the returned structure will point to the string 102.Ql * . 103.Sh YP SUPPORT 104If YP is active, 105.Fn getpwent 106also uses the 107.Pa master.passwd.byname 108YP map (if available) or the 109.Pa passwd.byname 110YP map. 111This is in addition to the passwd file, 112and respects the order of both normal and YP 113entries in the passwd file. 114.Sh RETURN VALUES 115The 116.Fn getpwent 117function returns a valid pointer to a passwd structure on success 118or a null pointer if end-of-file is reached or an error occurs. 119Subsequent calls to 120.Fn getpwent , 121.Fn getpwnam , 122.Fn getpwnam_shadow , 123.Fn getpwuid 124or 125.Fn getpwuid_shadow 126may invalidate the returned pointer or overwrite the contents 127of the passwd structure it points to. 128.Pp 129The 130.Fn endpwent 131and 132.Fn setpwent 133functions have no return value. 134.Sh FILES 135.Bl -tag -width /etc/master.passwd -compact 136.It Pa /etc/pwd.db 137insecure password database file 138.It Pa /etc/spwd.db 139secure password database file 140.It Pa /etc/master.passwd 141current password file 142.It Pa /etc/passwd 143legacy password file 144.El 145.Sh ERRORS 146The 147.Fn getpwent 148function may fail for any of the errors specified for 149.Xr dbopen 3 150and its 151.Fn get 152routine. 153.Pp 154If YP is active, it may also fail due to errors caused by the YP subsystem. 155.Sh SEE ALSO 156.Xr getlogin 2 , 157.Xr getgrent 3 , 158.Xr getgrouplist 3 , 159.Xr getpwnam 3 , 160.Xr pw_dup 3 , 161.Xr passwd 5 , 162.Xr Makefile.yp 8 , 163.Xr pwd_mkdb 8 , 164.Xr vipw 8 , 165.Xr yp 8 166.Sh STANDARDS 167These functions are compliant with the X/Open System Interfaces option of the 168.St -p1003.1-2008 169specification. 170.Sh HISTORY 171The 172.Fn getpwent , 173.Fn setpwent , 174and 175.Fn endpwent 176functions appeared in 177.At v7 . 178.Pp 179The historic function 180.Fn setpwfile , 181which allowed the specification of alternate password databases, 182has been deprecated and is no longer available. 183.Sh BUGS 184The routines 185.Fn getpwent , 186.Fn endpwent , 187and 188.Fn setpwent 189are fairly useless in a networked environment and should be 190avoided, if possible. 191