contrib/libc-pwcache/pwcache.3

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