lib/libc/gen/pwcache.3

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