1.\" $NetBSD: pwcache.3,v 1.17 2008/05/02 18:11:04 martin 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 January 24, 2002 59.Dt PWCACHE 3 60.Os 61.Sh NAME 62.Nm pwcache , 63.Nm user_from_uid , 64.Nm group_from_gid 65.Nd cache password and group entries 66.Sh LIBRARY 67.Lb libc 68.Sh SYNOPSIS 69.In pwd.h 70.Ft const char * 71.Fn user_from_uid "uid_t uid" "int nouser" 72.Ft int 73.Fn uid_from_user "const char *name" "uid_t *uid" 74.Ft int 75.Fn pwcache_userdb "int (*setpassent)(int)" "void (*endpwent)(void)" "struct passwd * (*getpwnam)(const char *)" "struct passwd * (*getpwuid)(uid_t)" 76.In grp.h 77.Ft const char * 78.Fn group_from_gid "gid_t gid" "int nogroup" 79.Ft int 80.Fn gid_from_group "const char *name" "gid_t *gid" 81.Ft int 82.Fn pwcache_groupdb "int (*setgroupent)(int)" "void (*endgrent)(void)" "struct group * (*getgrnam)(const char *)" "struct group * (*getgrgid)(gid_t)" 83.Sh DESCRIPTION 84The 85.Fn user_from_uid 86function returns the user name associated with the argument 87.Fa uid . 88The user name is cached so that multiple calls with the same 89.Fa uid 90do not require additional calls to 91.Xr getpwuid 3 . 92If there is no user associated with the 93.Fa uid , 94a pointer is returned 95to a string representation of the 96.Fa uid , 97unless the argument 98.Fa nouser 99is non-zero, in which case a 100.Dv NULL 101pointer is returned. 102.Pp 103The 104.Fn group_from_gid 105function returns the group name associated with the argument 106.Fa gid . 107The group name is cached so that multiple calls with the same 108.Fa gid 109do not require additional calls to 110.Xr getgrgid 3 . 111If there is no group associated with the 112.Fa gid , 113a pointer is returned 114to a string representation of the 115.Fa gid , 116unless the argument 117.Fa nogroup 118is non-zero, in which case a 119.Dv NULL 120pointer is returned. 121.Pp 122The 123.Fn uid_from_user 124function returns the uid associated with the argument 125.Fa name . 126The uid is cached so that multiple calls with the same 127.Fa name 128do not require additional calls to 129.Xr getpwnam 3 . 130If there is no uid associated with the 131.Fa name , 132the 133.Fn uid_from_user 134function returns \-1; otherwise it stores the uid at the location pointed to by 135.Fa uid 136and returns 0. 137.Pp 138The 139.Fn gid_from_group 140function returns the gid associated with the argument 141.Fa name . 142The gid is cached so that multiple calls with the same 143.Fa name 144do not require additional calls to 145.Xr getgrnam 3 . 146If there is no gid associated with the 147.Fa name , 148the 149.Fn gid_from_group 150function returns \-1; otherwise it stores the gid at the location pointed to by 151.Fa gid 152and returns 0. 153.Pp 154The 155.Fn pwcache_userdb 156function changes the user database access routines which 157.Fn user_from_uid 158and 159.Fn uid_from_user 160call to search for users. 161The caches are flushed and the existing 162.Fn endpwent 163method is called before switching to the new routines. 164.Fa getpwnam 165and 166.Fa getpwuid 167must be provided, and 168.Fa setpassent 169and 170.Fa endpwent 171may be 172.Dv NULL 173pointers. 174.Pp 175The 176.Fn pwcache_groupdb 177function changes the group database access routines which 178.Fn group_from_gid 179and 180.Fn gid_from_group 181call to search for groups. 182The caches are flushed and the existing 183.Fn endgrent 184method is called before switching to the new routines. 185.Fa getgrnam 186and 187.Fa getgrgid 188must be provided, and 189.Fa setgroupent 190and 191.Fa endgrent 192may be 193.Dv NULL 194pointers. 195.Sh SEE ALSO 196.Xr getgrgid 3 , 197.Xr getgrnam 3 , 198.Xr getpwnam 3 , 199.Xr getpwuid 3 200.Sh HISTORY 201The 202.Fn user_from_uid 203and 204.Fn group_from_gid 205functions first appeared in 206.Bx 4.4 . 207.Pp 208The 209.Fn uid_from_user 210and 211.Fn gid_from_group 212functions first appeared in 213.Nx 1.4 . 214.Pp 215The 216.Fn pwcache_userdb 217and 218.Fn pwcache_groupdb 219functions first appeared in 220.Nx 1.6 . 221