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