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