lib/libc/gen/pwcache.3

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