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.\" @(#)getpwent.3 8.2 (Berkeley) 12/11/93 33.\" 34.Dd December 11, 1993 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 RETURN VALUES 137The functions 138.Fn getpwent , 139.Fn getpwnam , 140and 141.Fn getpwuid , 142return a valid pointer to a passwd structure on success 143and a null pointer if end-of-file is reached or an error occurs. 144The functions 145.Fn setpassent 146and 147.Fn setpwent 148return 0 on failure and 1 on success. 149The 150.Fn endpwent 151function 152has no return value. 153.Sh FILES 154.Bl -tag -width /etc/master.passwd -compact 155.It Pa /var/db/pwd.db 156The insecure password database file 157.It Pa /var/db/spwd.db 158The secure password database file 159.It Pa /etc/master.passwd 160The current password file 161.It Pa /etc/passwd 162A Version 7 format password file 163.El 164.Sh SEE ALSO 165.Xr getlogin 3 , 166.Xr getgrent 3 , 167.Xr passwd 5 , 168.Xr pwd_mkdb 8 , 169.Xr vipw 8 170.Sh HISTORY 171The 172.Nm getpwent , 173.Nm getpwnam , 174.Nm getpwuid , 175.Nm setpwent, 176and 177.Nm endpwent 178functions appeared in 179.At v7 . 180The 181.Nm setpassent 182function appeared in 183.Bx 4.3 Reno . 184.Sh BUGS 185The functions 186.Fn getpwent , 187.Fn getpwnam , 188and 189.Fn getpwuid , 190leave their results in an internal static object and return 191a pointer to that object. Subsequent calls to 192the same function 193will modify the same object. 194.Pp 195The routines 196.Fn getpwent , 197.Fn endpwent , 198.Fn setpassent , 199and 200.Fn setpwent 201are fairly useless in a networked environment and should be 202avoided, if possible. 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