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