1.\" $NetBSD: pwcache.3,v 1.18 2017/10/24 19:04:58 abhinav Exp $ 2.\" 3.\" Copyright (c) 1989, 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.\" 31.\" Copyright (c) 2002 The NetBSD Foundation, Inc. 32.\" All rights reserved. 33.\" 34.\" Redistribution and use in source and binary forms, with or without 35.\" modification, are permitted provided that the following conditions 36.\" are met: 37.\" 1. Redistributions of source code must retain the above copyright 38.\" notice, this list of conditions and the following disclaimer. 39.\" 2. Redistributions in binary form must reproduce the above copyright 40.\" notice, this list of conditions and the following disclaimer in the 41.\" documentation and/or other materials provided with the distribution. 42.\" 43.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 44.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 45.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 46.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 47.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 48.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 49.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 50.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 51.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 52.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 53.\" POSSIBILITY OF SUCH DAMAGE. 54.\" 55.\" 56.\" @(#)pwcache.3 8.1 (Berkeley) 6/9/93 57.\" 58.Dd April 4, 2018 59.Dt PWCACHE 3 60.Os 61.Sh NAME 62.Nm pwcache , 63.Nm user_from_uid , 64.Nm uid_from_user , 65.Nm pwcache_userdb , 66.Nm group_from_gid , 67.Nm gid_from_group , 68.Nm pwcache_groupdb 69.Nd cache password and group entries 70.Sh LIBRARY 71.Lb libc 72.Sh SYNOPSIS 73.In pwd.h 74.Ft const char * 75.Fn user_from_uid "uid_t uid" "int nouser" 76.Ft int 77.Fn uid_from_user "const char *name" "uid_t *uid" 78.Ft int 79.Fn pwcache_userdb "int (*setpassent)(int)" "void (*endpwent)(void)" "struct passwd * (*getpwnam)(const char *)" "struct passwd * (*getpwuid)(uid_t)" 80.In grp.h 81.Ft const char * 82.Fn group_from_gid "gid_t gid" "int nogroup" 83.Ft int 84.Fn gid_from_group "const char *name" "gid_t *gid" 85.Ft int 86.Fn pwcache_groupdb "int (*setgroupent)(int)" "void (*endgrent)(void)" "struct group * (*getgrnam)(const char *)" "struct group * (*getgrgid)(gid_t)" 87.Sh DESCRIPTION 88The 89.Fn user_from_uid 90function returns the user name associated with the argument 91.Fa uid . 92The user name is cached so that multiple calls with the same 93.Fa uid 94do not require additional calls to 95.Xr getpwuid 3 . 96If there is no user associated with the 97.Fa uid , 98a pointer is returned 99to a string representation of the 100.Fa uid , 101unless the argument 102.Fa nouser 103is non-zero, in which case a 104.Dv NULL 105pointer is returned. 106.Pp 107The 108.Fn group_from_gid 109function returns the group name associated with the argument 110.Fa gid . 111The group name is cached so that multiple calls with the same 112.Fa gid 113do not require additional calls to 114.Xr getgrgid 3 . 115If there is no group associated with the 116.Fa gid , 117a pointer is returned 118to a string representation of the 119.Fa gid , 120unless the argument 121.Fa nogroup 122is non-zero, in which case a 123.Dv NULL 124pointer is returned. 125.Pp 126The 127.Fn uid_from_user 128function returns the uid associated with the argument 129.Fa name . 130The uid is cached so that multiple calls with the same 131.Fa name 132do not require additional calls to 133.Xr getpwnam 3 . 134If there is no uid associated with the 135.Fa name , 136the 137.Fn uid_from_user 138function returns \-1; otherwise it stores the uid at the location pointed to by 139.Fa uid 140and returns 0. 141.Pp 142The 143.Fn gid_from_group 144function returns the gid associated with the argument 145.Fa name . 146The gid is cached so that multiple calls with the same 147.Fa name 148do not require additional calls to 149.Xr getgrnam 3 . 150If there is no gid associated with the 151.Fa name , 152the 153.Fn gid_from_group 154function returns \-1; otherwise it stores the gid at the location pointed to by 155.Fa gid 156and returns 0. 157.Pp 158The 159.Fn pwcache_userdb 160function changes the user database access routines which 161.Fn user_from_uid 162and 163.Fn uid_from_user 164call to search for users. 165The caches are flushed and the existing 166.Fn endpwent 167method is called before switching to the new routines. 168.Fa getpwnam 169and 170.Fa getpwuid 171must be provided, and 172.Fa setpassent 173and 174.Fa endpwent 175may be 176.Dv NULL 177pointers. 178.Pp 179The 180.Fn pwcache_groupdb 181function changes the group database access routines which 182.Fn group_from_gid 183and 184.Fn gid_from_group 185call to search for groups. 186The caches are flushed and the existing 187.Fn endgrent 188method is called before switching to the new routines. 189.Fa getgrnam 190and 191.Fa getgrgid 192must be provided, and 193.Fa setgroupent 194and 195.Fa endgrent 196may be 197.Dv NULL 198pointers. 199.Sh SEE ALSO 200.Xr getgrgid 3 , 201.Xr getgrnam 3 , 202.Xr getpwnam 3 , 203.Xr getpwuid 3 204.Sh HISTORY 205The 206.Fn user_from_uid 207and 208.Fn group_from_gid 209functions first appeared in 210.Bx 4.4 . 211.Pp 212The 213.Fn uid_from_user 214and 215.Fn gid_from_group 216functions first appeared in 217.Nx 1.4 . 218.Pp 219The 220.Fn pwcache_userdb 221and 222.Fn pwcache_groupdb 223functions first appeared in 224.Nx 1.6 . 225