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.\" 4. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" From: @(#)getpwent.3 8.2 (Berkeley) 12/11/93 29.\" $FreeBSD$ 30.\" 31.Dd April 16, 2003 32.Dt GETPWENT 3 33.Os 34.Sh NAME 35.Nm getpwent , 36.Nm getpwent_r , 37.Nm getpwnam , 38.Nm getpwnam_r , 39.Nm getpwuid , 40.Nm getpwuid_r , 41.Nm setpassent , 42.Nm setpwent , 43.Nm endpwent 44.Nd password database operations 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.In sys/types.h 49.In pwd.h 50.Ft struct passwd * 51.Fn getpwent void 52.Ft int 53.Fn getpwent_r "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result" 54.Ft struct passwd * 55.Fn getpwnam "const char *login" 56.Ft int 57.Fn getpwnam_r "const char *name" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result" 58.Ft struct passwd * 59.Fn getpwuid "uid_t uid" 60.Ft int 61.Fn getpwuid_r "uid_t uid" "struct passwd *pwd" "char *buffer" "size_t bufsize" "struct passwd **result" 62.Ft int 63.Fn setpassent "int stayopen" 64.Ft void 65.Fn setpwent void 66.Ft void 67.Fn endpwent void 68.Sh DESCRIPTION 69These functions 70operate on the password database file 71which is described 72in 73.Xr passwd 5 . 74Each entry in the database is defined by the structure 75.Vt passwd 76found in the include 77file 78.In pwd.h : 79.Bd -literal -offset indent 80struct passwd { 81 char *pw_name; /* user name */ 82 char *pw_passwd; /* encrypted password */ 83 uid_t pw_uid; /* user uid */ 84 gid_t pw_gid; /* user gid */ 85 time_t pw_change; /* password change time */ 86 char *pw_class; /* user access class */ 87 char *pw_gecos; /* Honeywell login info */ 88 char *pw_dir; /* home directory */ 89 char *pw_shell; /* default shell */ 90 time_t pw_expire; /* account expiration */ 91 int pw_fields; /* internal: fields filled in */ 92}; 93.Ed 94.Pp 95The functions 96.Fn getpwnam 97and 98.Fn getpwuid 99search the password database for the given login name or user uid, 100respectively, always returning the first one encountered. 101.Pp 102The 103.Fn getpwent 104function 105sequentially reads the password database and is intended for programs 106that wish to process the complete list of users. 107.Pp 108The functions 109.Fn getpwent_r , 110.Fn getpwnam_r , 111and 112.Fn getpwuid_r 113are thread-safe versions of 114.Fn getpwent , 115.Fn getpwnam , 116and 117.Fn getpwuid , 118respectively. 119The caller must provide storage for the results of the search in 120the 121.Fa pwd , 122.Fa buffer , 123.Fa bufsize , 124and 125.Fa result 126arguments. 127When these functions are successful, the 128.Fa pwd 129argument will be filled-in, and a pointer to that argument will be 130stored in 131.Fa result . 132If an entry is not found or an error occurs, 133.Fa result 134will be set to 135.Dv NULL . 136.Pp 137The 138.Fn setpassent 139function 140accomplishes two purposes. 141First, it causes 142.Fn getpwent 143to ``rewind'' to the beginning of the database. 144Additionally, if 145.Fa stayopen 146is non-zero, file descriptors are left open, significantly speeding 147up subsequent accesses for all of the routines. 148(This latter functionality is unnecessary for 149.Fn getpwent 150as it does not close its file descriptors by default.) 151.Pp 152It is dangerous for long-running programs to keep the file descriptors 153open as the database will become out of date if it is updated while the 154program is running. 155.Pp 156The 157.Fn setpwent 158function 159is identical to 160.Fn setpassent 161with an argument of zero. 162.Pp 163The 164.Fn endpwent 165function 166closes any open files. 167.Pp 168These routines have been written to ``shadow'' the password file, e.g.\& 169allow only certain programs to have access to the encrypted password. 170If the process which calls them has an effective uid of 0, the encrypted 171password will be returned, otherwise, the password field of the returned 172structure will point to the string 173.Ql * . 174.Sh RETURN VALUES 175The functions 176.Fn getpwent , 177.Fn getpwnam , 178and 179.Fn getpwuid 180return a valid pointer to a passwd structure on success 181or 182.Dv NULL 183if the entry is not found or if an error occurs. 184If an error does occur, 185.Va errno 186will be set. 187Note that programs must explicitly set 188.Va errno 189to zero before calling any of these functions if they need to 190distinguish between a non-existent entry and an error. 191The functions 192.Fn getpwent_r , 193.Fn getpwnam_r , 194and 195.Fn getpwuid_r 196return 0 if no error occurred, or an error number to indicate failure. 197It is not an error if a matching entry is not found. 198(Thus, if 199.Fa result 200is 201.Dv NULL 202and the return value is 0, no matching entry exists.) 203.Pp 204The 205.Fn setpassent 206function returns 0 on failure and 1 on success. 207The 208.Fn endpwent 209and 210.Fn setpwent 211functions 212have no return value. 213.Sh FILES 214.Bl -tag -width /etc/master.passwd -compact 215.It Pa /etc/pwd.db 216The insecure password database file 217.It Pa /etc/spwd.db 218The secure password database file 219.It Pa /etc/master.passwd 220The current password file 221.It Pa /etc/passwd 222A Version 7 format password file 223.El 224.Sh COMPATIBILITY 225The historic function 226.Xr setpwfile 3 , 227which allowed the specification of alternate password databases, 228has been deprecated and is no longer available. 229.Sh ERRORS 230These routines may fail for any of the errors specified in 231.Xr open 2 , 232.Xr dbopen 3 , 233.Xr socket 2 , 234and 235.Xr connect 2 , 236in addition to the following: 237.Bl -tag -width Er 238.It Bq Er ERANGE 239The buffer specified by the 240.Fa buffer 241and 242.Fa bufsize 243arguments was insufficiently sized to store the result. 244The caller should retry with a larger buffer. 245.El 246.Sh SEE ALSO 247.Xr getlogin 2 , 248.Xr getgrent 3 , 249.Xr nsswitch.conf 5 , 250.Xr passwd 5 , 251.Xr pwd_mkdb 8 , 252.Xr vipw 8 , 253.Xr yp 8 254.Sh STANDARDS 255The 256.Fn getpwent , 257.Fn getpwnam , 258.Fn getpwnam_r , 259.Fn getpwuid , 260.Fn getpwuid_r , 261.Fn setpwent , 262and 263.Fn endpwent 264functions conform to 265.St -p1003.1-96 . 266.Sh HISTORY 267The 268.Fn getpwent , 269.Fn getpwnam , 270.Fn getpwuid , 271.Fn setpwent , 272and 273.Fn endpwent 274functions appeared in 275.At v7 . 276The 277.Fn setpassent 278function appeared in 279.Bx 4.3 Reno . 280The 281.Fn getpwent_r , 282.Fn getpwnam_r , 283and 284.Fn getpwuid_r 285functions appeared in 286.Fx 5.1 . 287.Sh BUGS 288The functions 289.Fn getpwent , 290.Fn getpwnam , 291and 292.Fn getpwuid , 293leave their results in an internal static object and return 294a pointer to that object. 295Subsequent calls to 296the same function 297will modify the same object. 298.Pp 299The functions 300.Fn getpwent , 301.Fn getpwent_r , 302.Fn endpwent , 303.Fn setpassent , 304and 305.Fn setpwent 306are fairly useless in a networked environment and should be 307avoided, if possible. 308The 309.Fn getpwent 310and 311.Fn getpwent_r 312functions 313make no attempt to suppress duplicate information if multiple 314sources are specified in 315.Xr nsswitch.conf 5 . 316