share/man/man3ldap/ldap_memcache.3ldap

   1 '\" te
   2 .\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
   3 .\" Portions Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH LDAP_MEMCACHE 3LDAP "April 9, 2016"
   8 .SH NAME
   9 ldap_memcache, ldap_memcache_init, ldap_memcache_set, ldap_memcache_get,
  10 ldap_memcache_flush, ldap_memcache_destroy, ldap_memcache_update \- LDAP client
  11 caching functions
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 \fBcc\fR \fB-flag \&.\|.\|.\fR \fIfile\fR\&.\|.\|.\fB-l\fRldap [\fB -library \&.\|.\|. \fR]
  16 #include <ldap.h>
  17
  18 \fBint\fR \fBldap_memcache_init\fR(\fBunsigned long\fR \fIttl\fR, \fBunsigned long\fR \fIsize\fR,
  19      \fBchar **\fR\fIbaseDNs\fR,\fBstruct ldap_thread_fns *\fR\fIthread_fns\fR,
  20      \fBLDAPMemCache **\fR\fIcachep\fR
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBint\fR \fBldap_memcache_set\fR(\fBLDAP *\fR\fIld\fR, \fBLDAPMemCache **\fR\fIcache\fR
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBint\fR \fBldap_memcache_get\fR(\fBLDAP *\fR\fIld\fR, \fBLDAPMemCache **\fR\fIcachep\fR
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBvoid\fR \fBldap_memcache_flush\fR(\fBLDAPMemCache *\fR\fIcache\fR, \fBchar *\fR\fIdn\fR, \fBint\fR \fIscope\fR
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBvoid\fR \fBldap_memcache_destroy\fR(\fBLDAPMemCache *\fR\fIcache\fR
  41 .fi
  42
  43 .LP
  44 .nf
  45 \fBvoid\fR \fBldap_memcache_update\fR(\fBLDAPMemCache *\fR\fIcache\fR
  46 .fi
  47
  48 .SH DESCRIPTION
  49 .LP
  50 Use the \fBldap_memcache\fR functions to maintain an in-memory client side
  51 cache to store search requests. Caching improves performance and reduces
  52 network bandwidth when a client makes repeated requests. The \fIcache\fR uses
  53 search criteria as the key to the cached items. When you send a search request,
  54 the \fIcache\fR checks the search criteria to determine if that request has
  55 been previously stored . If the request was stored, the search results are read
  56 from the \fIcache\fR.
  57 .sp
  58 .LP
  59 Make a call to \fBldap_memcache_init()\fR to create the in-memory client side
  60 \fIcache\fR. The function passes back a pointer to an \fBLDAPMemCache\fR
  61 structure, which represents the \fIcache\fR. Make a call to the
  62 \fBldap_memcache_set()\fR function to associate this \fIcache\fR with an LDAP
  63 connection handle, an LDAP structure. \fIttl\fR is the maximum amount of
  64 time (in seconds) that an item can be cached. If a \fIttl\fR value  of 0 is
  65 passed, there is no limit to the amount of time that an item  can be cached.
  66 \fIsize\fR is the maximum amount of memory (in bytes) that the cache will
  67 consume. A zero value of \fIsize\fR means the cache has  no size limit.
  68 \fIbaseDNS\fR is an array of the base DN strings representing  the base DNs of
  69 the search requests you want cached. If \fIbaseDNS\fR is not \fINULL\fR, only
  70 the search requests with the specified base DNs will be cached. If
  71 \fIbaseDNS\fR is \fINULL\fR,  all search requests are cached. The
  72 \fIthread_fns\fR parameter takes an \fBldap_thread_fns structure\fR specifying
  73 the functions that you want used to ensure that the cache is thread-safe. You
  74 should specify this if you have multiple threads that are using the same
  75 connection handle and cache. If you are not using multiple threads, pass
  76 \fINULL\fR for this parameter.
  77 .sp
  78 .LP
  79 \fBldap_memcache_set()\fR associates an in-memory \fIcache\fR that you have
  80 already  created by calling the \fBldap_memcache_init()\fR function with an
  81 LDAP connection handle. The \fIld\fR parameter should be the result of a
  82 successful call to \fBldap_open\fR(3LDAP). The \fIcache\fR parameter should be
  83 the result  of a \fIcache\fR created by the \fBldap_memcache_init()\fR call.
  84 After you call this function, search requests made over the specified LDAP
  85 connection will use this cache. To disassociate the cache from the LDAP
  86 connection handle, make a call to the \fBldap_bind\fR(3LDAP) or
  87 \fBldap_bind\fR(3LDAP) function. Make a call to \fBldap_memcache_set()\fR if
  88 you want to associate  a cache with multiple LDAP connection handles. For
  89 example, call  the \fBldap_memcache_get()\fR function to get the \fIcache\fR
  90 associated with one connection, then you can call this function and associate
  91 the \fIcache\fR with another connection.
  92 .sp
  93 .LP
  94 The \fBldap_memcache_get()\fR function gets the \fIcache\fR associated with the
  95 specified connection handle (LDAP structure). This \fIcache\fR is used by all
  96 search  requests made through that connection. When you call this function, the
  97 function sets the \fIcachep\fR parameter as a pointer to the \fBLDAPMemCache\fR
  98 structure that is associated with the connection handle.
  99 .sp
 100 .LP
 101 \fBldap_memcache_flush()\fR flushes search requests from the \fIcache\fR. If
 102 the base DN of a search request is within the scope specified by the \fIdn\fR
 103 and \fIscope\fR arguments, the search request is flushed from the \fIcache\fR.
 104 If no DN is specified, the entire cache is flushed. The \fIscope\fR parameter,
 105 along with the \fIdn\fR parameter, identifies the search requests that you want
 106 flushed from the \fIcache\fR. This argument can have one of the following
 107 values:
 108 .br
 109 .in +2
 110 \fBLDAP_SCOPE_BASE\fR
 111 .in -2
 112 .br
 113 .in +2
 114 \fBLDAP_SCOPE_ONELEVEL\fR
 115 .in -2
 116 .br
 117 .in +2
 118 \fBLDAP_SCOPE_SUBTREE\fR
 119 .in -2
 120 .sp
 121 .LP
 122 \fBldap_memcache_destroy()\fR frees the specified \fBLDAPMemCache\fR structure
 123 pointed to by \fIcache\fR from memory. Call this function after you are done
 124 working with a \fIcache\fR.
 125 .sp
 126 .LP
 127 \fBldap_memcache_update()\fR checks the cache for items that have expired  and
 128 removes them. This check is typically done as part of the way the \fIcache\fR
 129 normally works. You do not need to call this function unless you  want to
 130 update the \fIcache\fR at this point in time. This function is only  useful in
 131 a multithreaded application, since it will not return until the \fIcache\fR is
 132 destroyed.
 133 .SH PARAMETERS
 134 .ne 2
 135 .na
 136 \fB\fIttl\fR\fR
 137 .ad
 138 .RS 14n
 139 The maximum amount of time (in seconds) that an item can be cached
 140 .RE
 141
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fIsize\fR\fR
 146 .ad
 147 .RS 14n
 148 The maximum amount of memory (in bytes)  that the cache will consume.
 149 .RE
 150
 151 .sp
 152 .ne 2
 153 .na
 154 \fB\fIbaseDNs\fR\fR
 155 .ad
 156 .RS 14n
 157 An array of the base DN strings representing  the base DNs of the search
 158 requests you want cached
 159 .RE
 160
 161 .sp
 162 .ne 2
 163 .na
 164 \fB\fIthread_fns\fR\fR
 165 .ad
 166 .RS 14n
 167 A pointer to the \fBldap_thread_fns structure\fR structure.
 168 .RE
 169
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fIcachep\fR\fR
 174 .ad
 175 .RS 14n
 176 A pointer to the \fBLDAPMemCache\fR structure
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fIcache\fR\fR
 183 .ad
 184 .RS 14n
 185 The result of a \fIcache\fR created by the \fBldap_memcache_init()\fR call
 186 .RE
 187
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fIld\fR\fR
 192 .ad
 193 .RS 14n
 194 The result of a successful call to \fBldap_open\fR(3LDAP)
 195 .RE
 196
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fIdn\fR\fR
 201 .ad
 202 .RS 14n
 203 The search requests that you want flushed from the \fIcache\fR
 204 .RE
 205
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fIscope\fR\fR
 210 .ad
 211 .RS 14n
 212 The search requests that you want flushed from the \fIcache\fR
 213 .RE
 214
 215 .SH ERRORS
 216 .LP
 217 The functions that have \fBint\fR return values return \fBLDAP_SUCCESS\fR if
 218 the operation was successful. Otherwise, they return another LDAP error code.
 219 See \fBldap_error\fR(3LDAP) for a list of the LDAP error codes.
 220 .SH ATTRIBUTES
 221 .LP
 222 See \fBattributes\fR(5) for descriptions of the following attributes:
 223 .sp
 224
 225 .sp
 226 .TS
 227 box;
 228 c | c
 229 l | l .
 230 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 231 _
 232 Interface Stability     Evolving
 233 .TE
 234
 235 .SH SEE ALSO
 236 .LP
 237 \fBldap_error\fR(3LDAP), \fBldap_open\fR(3LDAP), \fBldap_search\fR(3LDAP),
 238 \fBattributes\fR(5)