1.\" Copyright (c) 1988, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)getpwent.3 8.2 (Berkeley) 12/11/93 7.\" 8.Dd 9.Dt GETPWENT 3 10.Os 11.Sh NAME 12.Nm getpwent , 13.Nm getpwnam , 14.Nm getpwuid , 15.Nm setpassent , 16.Nm setpwent , 17.Nm endpwent 18.Nd password database operations 19.Sh SYNOPSIS 20.Fd #include <sys/types.h> 21.Fd #include <pwd.h> 22.Ft struct passwd * 23.Fn getpwent void 24.Ft struct passwd * 25.Fn getpwnam "const char *login" 26.Ft struct passwd * 27.Fn getpwuid "uid_t uid" 28.Ft int 29.Fn setpassent "int stayopen" 30.Ft int 31.Fn setpwent void 32.Ft void 33.Fn endpwent void 34.Sh DESCRIPTION 35These functions 36operate on the password database file 37which is described 38in 39.Xr passwd 5 . 40Each entry in the database is defined by the structure 41.Ar passwd 42found in the include 43file 44.Aq Pa pwd.h : 45.Bd -literal -offset indent 46struct passwd { 47 char *pw_name; /* user name */ 48 char *pw_passwd; /* encrypted password */ 49 uid_t pw_uid; /* user uid */ 50 gid_t pw_gid; /* user gid */ 51 time_t pw_change; /* password change time */ 52 char *pw_class; /* user access class */ 53 char *pw_gecos; /* Honeywell login info */ 54 char *pw_dir; /* home directory */ 55 char *pw_shell; /* default shell */ 56 time_t pw_expire; /* account expiration */ 57}; 58.Ed 59.Pp 60The functions 61.Fn getpwnam 62and 63.Fn getpwuid 64search the password database for the given login name or user uid, 65respectively, always returning the first one encountered. 66.Pp 67The 68.Fn getpwent 69function 70sequentially reads the password database and is intended for programs 71that wish to process the complete list of users. 72.Pp 73The 74.Fn setpassent 75function 76accomplishes two purposes. 77First, it causes 78.Fn getpwent 79to ``rewind'' to the beginning of the database. 80Additionally, if 81.Fa stayopen 82is non-zero, file descriptors are left open, significantly speeding 83up subsequent accesses for all of the routines. 84(This latter functionality is unnecessary for 85.Fn getpwent 86as it doesn't close its file descriptors by default.) 87.Pp 88It is dangerous for long-running programs to keep the file descriptors 89open as the database will become out of date if it is updated while the 90program is running. 91.Pp 92The 93.Fn setpwent 94function 95is identical to 96.Fn setpassent 97with an argument of zero. 98.Pp 99The 100.Fn endpwent 101function 102closes any open files. 103.Pp 104These routines have been written to ``shadow'' the password file, e.g. 105allow only certain programs to have access to the encrypted password. 106If the process which calls them has an effective uid of 0, the encrypted 107password will be returned, otherwise, the password field of the returned 108structure will point to the string 109.Ql * . 110.Sh RETURN VALUES 111The functions 112.Fn getpwent , 113.Fn getpwnam , 114and 115.Fn getpwuid , 116return a valid pointer to a passwd structure on success 117and a null pointer if end-of-file is reached or an error occurs. 118The functions 119.Fn setpassent 120and 121.Fn setpwent 122return 0 on failure and 1 on success. 123The 124.Fn endpwent 125function 126has no return value. 127.Sh FILES 128.Bl -tag -width /etc/master.passwd -compact 129.It Pa /var/db/pwd.db 130The insecure password database file 131.It Pa /var/db/spwd.db 132The secure password database file 133.It Pa /etc/master.passwd 134The current password file 135.It Pa /etc/passwd 136A Version 7 format password file 137.El 138.Sh SEE ALSO 139.Xr getlogin 3 , 140.Xr getgrent 3 , 141.Xr passwd 5 , 142.Xr pwd_mkdb 8 , 143.Xr vipw 8 144.Sh HISTORY 145The 146.Nm getpwent , 147.Nm getpwnam , 148.Nm getpwuid , 149.Nm setpwent, 150and 151.Nm endpwent 152functions appeared in 153.At v7 . 154The 155.Nm setpassent 156function appeared in 157.Bx 4.3 Reno . 158.Sh BUGS 159The functions 160.Fn getpwent , 161.Fn getpwnam , 162and 163.Fn getpwuid , 164leave their results in an internal static object and return 165a pointer to that object. Subsequent calls to 166the same function 167will modify the same object. 168.Pp 169The routines 170.Fn getpwent , 171.Fn endpwent , 172.Fn setpassent , 173and 174.Fn setpwent 175are fairly useless in a networked environment and should be 176avoided, if possible. 177.Sh COMPATIBILITY 178The historic function 179.Xr setpwfile 3 , 180which allowed the specification of alternate password databases, 181has been deprecated and is no longer available. 182