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 int pw_uid; /* user uid */ 76 int 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 int pw_fields; /* internal: fields filled in */ 84}; 85.Ed 86.Pp 87The functions 88.Fn getpwnam 89and 90.Fn getpwuid 91search the password database for the given login name or user uid, 92respectively, always returning the first one encountered. 93.Pp 94The 95.Fn getpwent 96function 97sequentially reads the password database and is intended for programs 98that wish to process the complete list of users. 99.Pp 100The 101.Fn setpassent 102function 103accomplishes two purposes. 104First, it causes 105.Fn getpwent 106to ``rewind'' to the beginning of the database. 107Additionally, if 108.Fa stayopen 109is non-zero, file descriptors are left open, significantly speeding 110up subsequent accesses for all of the routines. 111(This latter functionality is unnecessary for 112.Fn getpwent 113as it doesn't close its file descriptors by default.) 114.Pp 115It is dangerous for long-running programs to keep the file descriptors 116open as the database will become out of date if it is updated while the 117program is running. 118.Pp 119The 120.Fn setpwent 121function 122is identical to 123.Fn setpassent 124with an argument of zero. 125.Pp 126The 127.Fn endpwent 128function 129closes any open files. 130.Pp 131These routines have been written to ``shadow'' the password file, e.g. 132allow only certain programs to have access to the encrypted password. 133If the process which calls them has an effective uid of 0, the encrypted 134password will be returned, otherwise, the password field of the returned 135structure will point to the string 136.Ql * . 137.Sh YP/NIS INTERACTION 138When the 139.Xr yp 4 140password database is enabled, the 141.Fn getpwnam 142and 143.Fn getpwuid 144functions use the YP maps 145.Dq Li passwd.byname 146and 147.Dq Li passwd.byuid , 148respectively, if the requested password entry is not found in the 149local database. The 150.Fn getpwent 151function will step through the YP map 152.Dq Li passwd.byname 153if the entire map is enabled as described in 154.Xr passwd 5 . 155.Sh RETURN VALUES 156The functions 157.Fn getpwent , 158.Fn getpwnam , 159and 160.Fn getpwuid , 161return a valid pointer to a passwd structure on success 162and a null pointer if end-of-file is reached or an error occurs. 163The functions 164.Fn setpassent 165and 166.Fn setpwent 167return 0 on failure and 1 on success. 168The 169.Fn endpwent 170function 171has no return value. 172.Sh FILES 173.Bl -tag -width /etc/master.passwd -compact 174.It Pa /etc/pwd.db 175The insecure password database file 176.It Pa /etc/spwd.db 177The secure password database file 178.It Pa /etc/master.passwd 179The current password file 180.It Pa /etc/passwd 181A Version 7 format password file 182.El 183.Sh SEE ALSO 184.Xr getlogin 2 , 185.Xr getgrent 3 , 186.Xr yp 4 , 187.Xr passwd 5 , 188.Xr pwd_mkdb 8 , 189.Xr vipw 8 190.Sh HISTORY 191The 192.Fn getpwent , 193.Fn getpwnam , 194.Fn getpwuid , 195.Fn setpwent, 196and 197.Fn endpwent 198functions appeared in 199.At v7 . 200The 201.Fn setpassent 202function appeared in 203.Bx 4.3 Reno . 204.Sh COMPATIBILITY 205The historic function 206.Xr setpwfile 3 , 207which allowed the specification of alternate password databases, 208has been deprecated and is no longer available. 209.Sh BUGS 210The functions 211.Fn getpwent , 212.Fn getpwnam , 213and 214.Fn getpwuid , 215leave their results in an internal static object and return 216a pointer to that object. Subsequent calls to 217the same function 218will modify the same object. 219