1.\" $OpenBSD: getpwnam.3,v 1.11 2016/08/14 14:57:16 tb 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: August 14 2016 $ 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 getpwnam_shadow , 39.Nm getpwuid_shadow , 40.Nm setpassent 41.Nd password database operations 42.Sh SYNOPSIS 43.In pwd.h 44.Ft struct passwd * 45.Fn getpwnam "const char *login" 46.Ft struct passwd * 47.Fn getpwuid "uid_t uid" 48.Ft int 49.Fn getpwnam_r "const char *login" "struct passwd *pwstore" "char *buf" "size_t bufsize" "struct passwd **result" 50.Ft int 51.Fn getpwuid_r "uid_t uid" "struct passwd *pwstore" "char *buf" "size_t bufsize" "struct passwd **result" 52.Ft struct passwd * 53.Fn getpwnam_shadow "const char *login" 54.Ft struct passwd * 55.Fn getpwuid_shadow "uid_t uid" 56.Ft int 57.Fn setpassent "int stayopen" 58.Sh DESCRIPTION 59These functions operate on the password database file which is described in 60.Xr passwd 5 . 61Each entry in the database is defined by the structure 62.Li struct passwd 63found in the include file 64.In pwd.h : 65.Bd -literal -offset indent 66struct passwd { 67 char *pw_name; /* user name */ 68 char *pw_passwd; /* encrypted password */ 69 uid_t pw_uid; /* user uid */ 70 gid_t pw_gid; /* user gid */ 71 time_t pw_change; /* password change time */ 72 char *pw_class; /* user access class */ 73 char *pw_gecos; /* Honeywell login info */ 74 char *pw_dir; /* home directory */ 75 char *pw_shell; /* default shell */ 76 time_t pw_expire; /* account expiration */ 77}; 78.Ed 79.Pp 80The functions 81.Fn getpwnam 82and 83.Fn getpwuid 84search the password database for the given login name or user ID, 85respectively, always returning the first one encountered. 86.Pp 87The 88.Fn getpwnam_r 89and 90.Fn getpwuid_r 91functions both update the passwd structure pointed to by 92.Fa pwstore 93and store a pointer to that structure at the location pointed to by 94.Fa result . 95The structure is filled with an entry from the password database with a 96matching 97.Fa name 98or 99.Fa uid . 100Storage referenced by the passwd structure will be allocated from 101the memory provided with the 102.Fa buf 103parameter, which is 104.Fa bufsiz 105characters in size. 106The maximum size needed for this buffer can be determined with 107.Fn sysconf _SC_GETPW_R_SIZE_MAX . 108.Pp 109.Fn setpassent 110accomplishes two purposes. 111First, it causes 112.Xr getpwent 3 113to 114.Dq rewind 115to the beginning of the database. 116Additionally, if 117.Fa stayopen 118is non-zero, file descriptors are left open, significantly speeding 119up subsequent accesses for the lookup routines. 120These file descriptors can be closed by a call to 121.Xr endpwent 3 . 122.Pp 123It is dangerous for long-running programs to keep the file descriptors 124open as the database will become out of date if it is updated while the 125program is running. 126However the file descriptors are automatically closed when 127.Xr execve 2 128is called. 129.Pp 130These routines have been written to 131.Dq shadow 132the password file, that is, 133allow only certain programs to have access to the encrypted password. 134The default functions will not return the true encrypted password, but 135instead only the string 136.Ql * . 137If the process which calls them has an effective UID of 0 or has the 138.Dq _shadow 139group in its group vector, and wishes to access the encrypted password, 140it should use the 141.Fn getpwnam_shadow 142and 143.Fn getpwuid_shadow 144functions. 145.Ss YP support 146If YP is active, the functions 147.Fn getpwnam 148and 149.Fn getpwnam_r 150also use the 151.Pa master.passwd.byname 152YP map (if available) or the 153.Pa passwd.byname 154YP map; and the functions 155.Fn getpwuid 156and 157.Fn getpwuid_r 158also use the 159.Pa master.passwd.byuid 160YP map (if available) or the 161.Pa passwd.byuid 162YP map. 163This is in addition to the passwd file, 164and respects the order of both normal and YP 165entries in the passwd file. 166.Sh RETURN VALUES 167The functions 168.Fn getpwnam 169and 170.Fn getpwuid 171return a pointer to a passwd structure if a match is found or a 172.Dv NULL 173pointer if no match is found or an error occurs. 174.Pp 175The functions 176.Fn getpwnam_r 177and 178.Fn getpwuid_r 179update 180.Fa result 181to point to 182.Fa pwstore 183if a match is found or set it to 184.Dv NULL 185if no match is found or an error occurs. 186They return 0 on success, even if no match is found, 187or an error number if an error occurs; see 188.Sx ERRORS . 189.Pp 190The 191.Fn setpassent 192function returns 0 on failure or 1 on success. 193.Sh FILES 194.Bl -tag -width /etc/master.passwd -compact 195.It Pa /etc/pwd.db 196insecure password database file 197.It Pa /etc/spwd.db 198secure password database file 199.It Pa /etc/master.passwd 200current password file 201.It Pa /etc/passwd 202legacy password file 203.El 204.Sh ERRORS 205The 206.Fn getpwnam_r 207and 208.Fn getpwuid_r 209functions may fail if: 210.Bl -tag -width Er 211.It Bq Er ERANGE 212The storage supplied via 213.Fa buf 214and 215.Fa bufsize 216is too small and cannot contain all the strings to be returned in 217.Fa pwstore . 218.El 219.Pp 220The 221.Fn getpwnam , 222.Fn getpwnam_r , 223.Fn getpwuid , 224and 225.Fn getpwuid_r 226functions may also fail for any of the errors specified for 227.Xr dbopen 3 228and its 229.Fn get 230routine. 231.Pp 232If YP is active, they may also fail due to errors caused by the YP 233subsystem. 234.Sh SEE ALSO 235.Xr getlogin 2 , 236.Xr getgrent 3 , 237.Xr getgrouplist 3 , 238.Xr getpwent 3 , 239.Xr pw_dup 3 , 240.Xr sysconf 3 , 241.Xr passwd 5 , 242.Xr Makefile.yp 8 , 243.Xr pwd_mkdb 8 , 244.Xr vipw 8 , 245.Xr yp 8 246.Sh STANDARDS 247The 248.Fn getpwnam , 249.Fn getpwnam_r , 250.Fn getpwuid , 251and 252.Fn getpwuid_r 253functions are compliant with the 254.St -p1003.1-2008 255specification. 256.Pp 257.Sx YP support 258and the 259.Fn setpassent 260function are extensions to that specification. 261.Sh HISTORY 262A predecessor to 263.Fn getpwuid , 264.Fn getpw , 265first appeared in 266.At v4 . 267The 268.Fn getpwnam 269and 270.Fn getpwuid 271functions appeared in 272.At v7 . 273The 274.Fn setpassent 275function appeared in 276.Bx 4.3 Reno . 277.Sh BUGS 278The 279.Fn getpwnam 280and 281.Fn getpwuid 282functions store their results in an internal static buffer and return 283a pointer to that buffer. 284Subsequent calls to 285.Fn getpwent , 286.Fn getpwnam , 287or 288.Fn getpwuid 289will overwrite the same buffer. 290