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