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"
9 ldap_memcache, ldap_memcache_init, ldap_memcache_set, ldap_memcache_get,
10 ldap_memcache_flush, ldap_memcache_destroy, ldap_memcache_update \- LDAP client
15 \fBcc\fR \fB-flag \&.\|.\|.\fR \fIfile\fR\&.\|.\|.\fB-l\fRldap [\fB -library \&.\|.\|. \fR]
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
25 \fBint\fR \fBldap_memcache_set\fR(\fBLDAP *\fR\fIld\fR, \fBLDAPMemCache **\fR\fIcache\fR
30 \fBint\fR \fBldap_memcache_get\fR(\fBLDAP *\fR\fIld\fR, \fBLDAPMemCache **\fR\fIcachep\fR
35 \fBvoid\fR \fBldap_memcache_flush\fR(\fBLDAPMemCache *\fR\fIcache\fR, \fBchar *\fR\fIdn\fR, \fBint\fR \fIscope\fR
40 \fBvoid\fR \fBldap_memcache_destroy\fR(\fBLDAPMemCache *\fR\fIcache\fR
45 \fBvoid\fR \fBldap_memcache_update\fR(\fBLDAPMemCache *\fR\fIcache\fR
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
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.
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.
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.
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
110 \fBLDAP_SCOPE_BASE\fR
114 \fBLDAP_SCOPE_ONELEVEL\fR
118 \fBLDAP_SCOPE_SUBTREE\fR
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.
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
139 The maximum amount of time (in seconds) that an item can be cached
148 The maximum amount of memory (in bytes) that the cache will consume.
157 An array of the base DN strings representing the base DNs of the search
158 requests you want cached
164 \fB\fIthread_fns\fR\fR
167 A pointer to the \fBldap_thread_fns structure\fR structure.
176 A pointer to the \fBLDAPMemCache\fR structure
185 The result of a \fIcache\fR created by the \fBldap_memcache_init()\fR call
194 The result of a successful call to \fBldap_open\fR(3LDAP)
203 The search requests that you want flushed from the \fIcache\fR
212 The search requests that you want flushed from the \fIcache\fR
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.
222 See \fBattributes\fR(5) for descriptions of the following attributes:
230 ATTRIBUTE TYPE ATTRIBUTE VALUE
232 Interface Stability Evolving
237 \fBldap_error\fR(3LDAP), \fBldap_open\fR(3LDAP), \fBldap_search\fR(3LDAP),