1.\" $OpenBSD: getpwent.3,v 1.31 2016/08/14 14:57:16 tb 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: August 14 2016 $ 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.Li 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. 119.Pp 120The 121.Fn endpwent 122and 123.Fn setpwent 124functions have no return value. 125.Sh FILES 126.Bl -tag -width /etc/master.passwd -compact 127.It Pa /etc/pwd.db 128insecure password database file 129.It Pa /etc/spwd.db 130secure password database file 131.It Pa /etc/master.passwd 132current password file 133.It Pa /etc/passwd 134legacy password file 135.El 136.Sh ERRORS 137The 138.Fn getpwent 139function may fail for any of the errors specified for 140.Xr dbopen 3 141and its 142.Fn get 143routine. 144.Pp 145If YP is active, it may also fail due to errors caused by the YP subsystem. 146.Sh SEE ALSO 147.Xr getlogin 2 , 148.Xr getgrent 3 , 149.Xr getgrouplist 3 , 150.Xr getpwnam 3 , 151.Xr pw_dup 3 , 152.Xr passwd 5 , 153.Xr Makefile.yp 8 , 154.Xr pwd_mkdb 8 , 155.Xr vipw 8 , 156.Xr yp 8 157.Sh STANDARDS 158These functions are compliant with the X/Open System Interfaces option of the 159.St -p1003.1-2008 160specification. 161.Sh HISTORY 162The 163.Fn getpwent , 164.Fn setpwent , 165and 166.Fn endpwent 167functions appeared in 168.At v7 . 169.Pp 170The historic function 171.Fn setpwfile , 172which allowed the specification of alternate password databases, 173has been deprecated and is no longer available. 174.Sh BUGS 175The 176.Fn getpwent 177function stores its results in an internal static buffer and returns 178a pointer to that buffer. 179Subsequent calls to 180.Fn getpwent , 181.Fn getpwnam , 182or 183.Fn getpwuid 184will overwrite the same buffer. 185.Pp 186The routines 187.Fn getpwent , 188.Fn endpwent , 189and 190.Fn setpwent 191are fairly useless in a networked environment and should be 192avoided, if possible. 193