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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" From: @(#)getpwent.3 8.2 (Berkeley) 12/11/93 33.\" 34.Dd September 20, 1994 35.Dt GETPWENT 3 36.Os 37.Sh NAME 38.Nm getpwent , 39.Nm getpwnam , 40.Nm getpwuid , 41.Nm setpassent , 42.Nm setpwent , 43.Nm endpwent 44.Nd password database operations 45.Sh SYNOPSIS 46.Fd #include <sys/types.h> 47.Fd #include <pwd.h> 48.Ft struct passwd * 49.Fn getpwent void 50.Ft struct passwd * 51.Fn getpwnam "const char *login" 52.Ft struct passwd * 53.Fn getpwuid "uid_t uid" 54.Ft int 55.Fn setpassent "int stayopen" 56.Ft int 57.Fn setpwent void 58.Ft void 59.Fn endpwent void 60.Sh DESCRIPTION 61These functions 62operate on the password database file 63which is described 64in 65.Xr passwd 5 . 66Each entry in the database is defined by the structure 67.Ar passwd 68found in the include 69file 70.Aq Pa pwd.h : 71.Bd -literal -offset indent 72struct passwd { 73 char *pw_name; /* user name */ 74 char *pw_passwd; /* encrypted password */ 75 uid_t pw_uid; /* user uid */ 76 gid_t pw_gid; /* user gid */ 77 time_t pw_change; /* password change time */ 78 char *pw_class; /* user access class */ 79 char *pw_gecos; /* Honeywell login info */ 80 char *pw_dir; /* home directory */ 81 char *pw_shell; /* default shell */ 82 time_t pw_expire; /* account expiration */ 83}; 84.Ed 85.Pp 86The functions 87.Fn getpwnam 88and 89.Fn getpwuid 90search the password database for the given login name or user uid, 91respectively, always returning the first one encountered. 92.Pp 93The 94.Fn getpwent 95function 96sequentially reads the password database and is intended for programs 97that wish to process the complete list of users. 98.Pp 99The 100.Fn setpassent 101function 102accomplishes two purposes. 103First, it causes 104.Fn getpwent 105to ``rewind'' to the beginning of the database. 106Additionally, if 107.Fa stayopen 108is non-zero, file descriptors are left open, significantly speeding 109up subsequent accesses for all of the routines. 110(This latter functionality is unnecessary for 111.Fn getpwent 112as it doesn't close its file descriptors by default.) 113.Pp 114It is dangerous for long-running programs to keep the file descriptors 115open as the database will become out of date if it is updated while the 116program is running. 117.Pp 118The 119.Fn setpwent 120function 121is identical to 122.Fn setpassent 123with an argument of zero. 124.Pp 125The 126.Fn endpwent 127function 128closes any open files. 129.Pp 130These routines have been written to ``shadow'' the password file, e.g. 131allow only certain programs to have access to the encrypted password. 132If the process which calls them has an effective uid of 0, the encrypted 133password will be returned, otherwise, the password field of the returned 134structure will point to the string 135.Ql * . 136.Sh YP/NIS INTERACTION 137When the 138.Xr yp 4 139password database is enabled, the 140.Fn getpwnam 141and 142.Fn getpwuid 143functions use the YP maps 144.Dq Li passwd.byname 145and 146.Dq Li passwd.byuid , 147respectively, if the requested password entry is not found in the 148local database. The 149.Fn getpwent 150function will step through the YP map 151.Dq Li passwd.byname 152if the entire map is enabled as described in 153.Xr passwd 5 . 154.Sh RETURN VALUES 155The functions 156.Fn getpwent , 157.Fn getpwnam , 158and 159.Fn getpwuid , 160return a valid pointer to a passwd structure on success 161and a null pointer if end-of-file is reached or an error occurs. 162The functions 163.Fn setpassent 164and 165.Fn setpwent 166return 0 on failure and 1 on success. 167The 168.Fn endpwent 169function 170has no return value. 171.Sh FILES 172.Bl -tag -width /etc/master.passwd -compact 173.It Pa /var/db/pwd.db 174The insecure password database file 175.It Pa /var/db/spwd.db 176The secure password database file 177.It Pa /etc/master.passwd 178The current password file 179.It Pa /etc/passwd 180A Version 7 format password file 181.El 182.Sh SEE ALSO 183.Xr getlogin 3 , 184.Xr getgrent 3 , 185.Xr passwd 5 , 186.Xr pwd_mkdb 8 , 187.Xr vipw 8 , 188.Xr yp 4 189.Sh HISTORY 190The 191.Nm getpwent , 192.Nm getpwnam , 193.Nm getpwuid , 194.Nm setpwent, 195and 196.Nm endpwent 197functions appeared in 198.At v7 . 199The 200.Nm setpassent 201function appeared in 202.Bx 4.3 Reno . 203.Sh COMPATIBILITY 204The historic function 205.Xr setpwfile 3 , 206which allowed the specification of alternate password databases, 207has been deprecated and is no longer available. 208.Sh BUGS 209The functions 210.Fn getpwent , 211.Fn getpwnam , 212and 213.Fn getpwuid , 214leave their results in an internal static object and return 215a pointer to that object. Subsequent calls to 216the same function 217will modify the same object. 218