1.\" $OpenBSD: getpwnam.3,v 1.13 2018/08/21 20:20:04 millert 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 21 2018 $ 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 , 169.Fn getpwnam_shadow , 170.Fn getpwuid , 171and 172.Fn getpwuid_shadow 173return a pointer to a passwd structure if a match is found or a null 174pointer if no match is found or an error occurs. 175Subsequent calls to 176.Fn getpwent , 177.Fn getpwnam , 178.Fn getpwnam_shadow , 179.Fn getpwuid 180or 181.Fn getpwuid_shadow 182may invalidate the returned pointer or overwrite the contents 183of the passwd structure it points to. 184.Pp 185The functions 186.Fn getpwnam_r 187and 188.Fn getpwuid_r 189update 190.Fa result 191to point to 192.Fa pwstore 193if a match is found or set it to 194.Dv NULL 195if no match is found or an error occurs. 196They return 0 on success, even if no match is found, 197or an error number if an error occurs; see 198.Sx ERRORS . 199.Pp 200The 201.Fn setpassent 202function returns 0 on failure or 1 on success. 203.Sh FILES 204.Bl -tag -width /etc/master.passwd -compact 205.It Pa /etc/pwd.db 206insecure password database file 207.It Pa /etc/spwd.db 208secure password database file 209.It Pa /etc/master.passwd 210current password file 211.It Pa /etc/passwd 212legacy password file 213.El 214.Sh ERRORS 215The 216.Fn getpwnam_r 217and 218.Fn getpwuid_r 219functions may fail if: 220.Bl -tag -width Er 221.It Bq Er ERANGE 222The storage supplied via 223.Fa buf 224and 225.Fa bufsize 226is too small and cannot contain all the strings to be returned in 227.Fa pwstore . 228.El 229.Pp 230The 231.Fn getpwnam , 232.Fn getpwnam_r , 233.Fn getpwuid , 234and 235.Fn getpwuid_r 236functions may also fail for any of the errors specified for 237.Xr dbopen 3 238and its 239.Fn get 240routine. 241.Pp 242If YP is active, they may also fail due to errors caused by the YP 243subsystem. 244.Sh SEE ALSO 245.Xr getlogin 2 , 246.Xr getgrent 3 , 247.Xr getgrouplist 3 , 248.Xr getpwent 3 , 249.Xr pw_dup 3 , 250.Xr sysconf 3 , 251.Xr passwd 5 , 252.Xr Makefile.yp 8 , 253.Xr pwd_mkdb 8 , 254.Xr vipw 8 , 255.Xr yp 8 256.Sh STANDARDS 257The 258.Fn getpwnam , 259.Fn getpwnam_r , 260.Fn getpwuid , 261and 262.Fn getpwuid_r 263functions are compliant with the 264.St -p1003.1-2008 265specification. 266.Pp 267.Sx YP support 268and the 269.Fn setpassent 270function are extensions to that specification. 271.Sh HISTORY 272A predecessor to 273.Fn getpwuid , 274.Fn getpw , 275first appeared in 276.At v4 . 277The 278.Fn getpwnam 279and 280.Fn getpwuid 281functions appeared in 282.At v7 , 283.Fn setpassent 284in 285.Bx 4.3 Reno , 286and 287.Fn getpwnam_shadow 288and 289.Fn getpwuid_shadow 290in 291.Ox 5.9 . 292