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