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