1.\" $OpenBSD: getpwnam.3,v 1.6 2014/03/12 11:36:06 schwarze 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. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: March 12 2014 $ 31.Dt GETPWNAM 3 32.Os 33.Sh NAME 34.Nm getpwnam , 35.Nm getpwuid , 36.Nm getpwnam_r , 37.Nm getpwuid_r , 38.Nm setpassent 39.Nd password database operations 40.Sh SYNOPSIS 41.In sys/types.h 42.In pwd.h 43.Ft struct passwd * 44.Fn getpwnam "const char *login" 45.Ft struct passwd * 46.Fn getpwuid "uid_t uid" 47.Ft int 48.Fn getpwnam_r "const char *login" "struct passwd *pwstore" "char *buf" "size_t buflen" "struct passwd **result" 49.Ft int 50.Fn getpwuid_r "uid_t uid" "struct passwd *pwstore" "char *buf" "size_t buflen" "struct passwd **result" 51.Ft int 52.Fn setpassent "int stayopen" 53.Sh DESCRIPTION 54These functions operate on the password database file which is described in 55.Xr passwd 5 . 56Each entry in the database is defined by the structure 57.Li struct passwd 58found in the include file 59.In pwd.h : 60.Bd -literal -offset indent 61struct passwd { 62 char *pw_name; /* user name */ 63 char *pw_passwd; /* encrypted password */ 64 uid_t pw_uid; /* user uid */ 65 gid_t pw_gid; /* user gid */ 66 time_t pw_change; /* password change time */ 67 char *pw_class; /* user access class */ 68 char *pw_gecos; /* Honeywell login info */ 69 char *pw_dir; /* home directory */ 70 char *pw_shell; /* default shell */ 71 time_t pw_expire; /* account expiration */ 72}; 73.Ed 74.Pp 75The functions 76.Fn getpwnam 77and 78.Fn getpwuid 79search the password database for the given login name or user ID, 80respectively, always returning the first one encountered. 81.Pp 82The re-entrant versions, 83.Fn getpwnam_r 84and 85.Fn getpwuid_r , 86behave similarly but the various strings associated with the result 87are stored in 88.Fa buf , 89and 90.Fa pwstore 91is updated to reference those strings. 92.Pp 93.Fn setpassent 94accomplishes two purposes. 95First, it causes 96.Xr getpwent 3 97to 98.Dq rewind 99to the beginning of the database. 100Additionally, if 101.Fa stayopen 102is non-zero, file descriptors are left open, significantly speeding 103up subsequent accesses for the lookup routines. 104These file descriptors can be closed by a call to 105.Xr endpwent 3 . 106.Pp 107It is dangerous for long-running programs to keep the file descriptors 108open as the database will become out of date if it is updated while the 109program is running. 110Furthermore, programs that run child processes should be careful to call 111.Xr endpwent 3 112to close these descriptors before calling 113.Xr execve 2 114or 115.Xr system 3 . 116.Pp 117These routines have been written to 118.Dq shadow 119the password file, that is, 120allow only certain programs to have access to the encrypted password. 121If the process which calls them has an effective UID of 0 or has the 122.Dq _shadow 123group in its group vector, the encrypted password will be returned, otherwise, 124the password field of the returned structure will point to the string 125.Ql * . 126.Ss YP support 127If YP is active, the functions 128.Fn getpwnam 129and 130.Fn getpwnam_r 131also use the 132.Pa master.passwd.byname 133YP map (if available) or the 134.Pa passwd.byname 135YP map; and the functions 136.Fn getpwuid 137and 138.Fn getpwuid_r 139also use the 140.Pa master.passwd.byuid 141YP map (if available) or the 142.Pa passwd.byuid 143YP map. 144This is in addition to the passwd file, 145and respects the order of both normal and YP 146entries in the passwd file. 147.Sh RETURN VALUES 148The functions 149.Fn getpwnam 150and 151.Fn getpwuid 152return a pointer to a passwd structure if a match is found or a 153.Dv NULL 154pointer if no match is found or an error occurs. 155.Pp 156The functions 157.Fn getpwnam_r 158and 159.Fn getpwuid_r 160update 161.Fa result 162to point to 163.Fa pwstore 164if a match is found or set it to 165.Dv NULL 166if no match is found or an error occurs. 167They return 0 on success, even if no match is found, 168or an error number if an error occurs; see 169.Sx ERRORS . 170.Pp 171The 172.Fn setpassent 173function returns 0 on failure or 1 on success. 174.Sh FILES 175.Bl -tag -width /etc/master.passwd -compact 176.It Pa /etc/pwd.db 177insecure password database file 178.It Pa /etc/spwd.db 179secure password database file 180.It Pa /etc/master.passwd 181current password file 182.It Pa /etc/passwd 183a Version 7 format password file 184.El 185.Sh ERRORS 186The 187.Fn getpwnam_r 188and 189.Fn getpwuid_r 190functions may fail if: 191.Bl -tag -width Er 192.It Bq Er ERANGE 193The storage supplied via 194.Fa buf 195and 196.Fa buflen 197is too small and cannot contain all the strings to be returned in 198.Fa pwstore . 199.El 200.Pp 201The 202.Fn getpwnam , 203.Fn getpwnam_r , 204.Fn getpwuid , 205and 206.Fn getpwuid_r 207functions may also fail for any of the errors specified for 208.Xr dbopen 3 209and its 210.Fn get 211routine. 212.Pp 213If YP is active, they may also fail due to errors caused by the YP 214subsystem. 215.Sh SEE ALSO 216.Xr getlogin 2 , 217.Xr getgrent 3 , 218.Xr getgrouplist 3 , 219.Xr getpwent 3 , 220.Xr pw_dup 3 , 221.Xr passwd 5 , 222.Xr Makefile.yp 8 , 223.Xr pwd_mkdb 8 , 224.Xr vipw 8 , 225.Xr yp 8 226.Sh STANDARDS 227The 228.Fn getpwnam , 229.Fn getpwnam_r , 230.Fn getpwuid , 231and 232.Fn getpwuid_r 233functions are compliant with the 234.St -p1003.1-2008 235specification. 236.Pp 237.Sx YP support 238and the 239.Fn setpassent 240function are extensions to that specification. 241.Sh HISTORY 242A predecessor to 243.Fn getpwuid , 244.Fn getpw , 245first appeared in 246.At v4 . 247The 248.Fn getpwnam 249and 250.Fn getpwuid 251functions appeared in 252.At v7 . 253The 254.Fn setpassent 255function appeared in 256.Bx 4.3 Reno . 257.Sh BUGS 258The 259.Fn getpwnam 260and 261.Fn getpwuid 262functions store their results in an internal static buffer and return 263a pointer to that buffer. 264Subsequent calls to 265.Fn getpwent , 266.Fn getpwnam , 267or 268.Fn getpwuid 269will overwrite the same buffer. 270