1.\" $OpenBSD: getpwnam.3,v 1.2 2009/06/02 05:09:16 jmc 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: June 2 2009 $ 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.Fd #include <sys/types.h> 42.Fd #include <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.Aq Pa 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.Va buf , 89and 90.Va 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.Sh 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 valid pointer to a passwd structure on success 153or a null pointer if end-of-file is reached or an error occurs. 154.Pp 155The functions 156.Fn getpwnam_r 157and 158.Fn getpwuid_r 159update 160.Va result 161to point to 162.Va pwstore 163and then return 0 on success. 164.Pp 165The 166.Fn setpassent 167function returns 0 on failure or 1 on success. 168.Sh FILES 169.Bl -tag -width /etc/master.passwd -compact 170.It Pa /etc/pwd.db 171insecure password database file 172.It Pa /etc/spwd.db 173secure password database file 174.It Pa /etc/master.passwd 175current password file 176.It Pa /etc/passwd 177a Version 7 format password file 178.El 179.Sh SEE ALSO 180.Xr getlogin 2 , 181.Xr getgrent 3 , 182.Xr getgrouplist 3 , 183.Xr getpwent 3 , 184.Xr pw_dup 3 , 185.Xr passwd 5 , 186.Xr Makefile.yp 8 , 187.Xr pwd_mkdb 8 , 188.Xr vipw 8 , 189.Xr yp 8 190.Sh HISTORY 191The 192.Fn getpwnam 193and 194.Fn getpwuid 195functions appeared in 196.At v7 . 197The 198.Fn setpassent 199function appeared in 200.Bx 4.3 Reno . 201.Sh BUGS 202The 203.Fn getpwnam 204and 205.Fn getpwuid 206functions store their results in an internal static buffer and return 207a pointer to that buffer. 208Subsequent calls to 209.Fn getpwent , 210.Fn getpwnam , 211or 212.Fn getpwuid 213will overwrite the same buffer. 214