ldap_memcache(3LDAP)					      LDAP Library Functions					      ldap_memcache(3LDAP)

NAME

       ldap_memcache, ldap_memcache_init, ldap_memcache_set, ldap_memcache_get, ldap_memcache_flush, ldap_memcache_destroy, ldap_memcache_update -
       LDAP client caching functions

SYNOPSIS

       cc -flag ... file...-lldap [ -library ... ]
       #include <ldap.h>

       int ldap_memcache_init(unsigned long ttl, unsigned long size,
	    char **baseDNs,struct ldap_thread_fns *thread_fns,
	    LDAPMemCache **cachep

       int ldap_memcache_set(LDAP *ld, LDAPMemCache **cache

       int ldap_memcache_get(LDAP *ld, LDAPMemCache **cachep

       void ldap_memcache_flush(LDAPMemCache *cache, char *dn, int scope

       void ldap_memcache_destroy(LDAPMemCache *cache

       void ldap_memcache_update(LDAPMemCache *cache

DESCRIPTION

       Use the ldap_memcache functions to maintain an in-memory client side cache to store  search  requests.  Caching	improves  performance  and
       reduces	network  bandwidth  when a client makes repeated requests. The cache uses search criteria as the key to the cached items. When you
       send a search request, the cache checks the search criteria to determine if that request has been previously stored . If  the  request  was
       stored, the search results are read from the cache.

       Make a call to ldap_memcache_init() to create the in-memory client side cache. The function passes back a pointer to an LDAPMemCache struc-
       ture, which represents the cache. Make a call to the ldap_memcache_set() function to associate this cache with an LDAP  connection  handle,
       an LDAP structure. ttl is the the maximum  amount of time (in seconds) that an item can be cached. If a ttl value  of 0 is passed, there is
       no limit to the amount of time that an item  can be cached. size is the maximum amount of memory (in bytes) that the cache will consume.  A
       zero  value of size means the cache has	no size limit. baseDNS is an array of the base DN strings representing	the base DNs of the search
       requests you want cached. If baseDNS is not NULL, only the search requests with the specified base DNs will be cached. If baseDNS is  NULL,
       all  search requests are cached. The thread_fns parameter takes an ldap_thread_fns structure specifying the functions that you want used to
       ensure that the cache is thread-safe. You should specify this if you have multiple threads that are using the same  connection  handle  and
       cache. If you are not using multiple threads, pass NULL for this parameter.

       ldap_memcache_set()  associates an in-memory cache that you have already  created by calling the ldap_memcache_init() function with an LDAP
       connection handle. The ld parameter should be the result of a successful call to ldap_open(3LDAP). The cache parameter should be the result
       of  a cache created by the ldap_memcache_init() call. After you call this function, search requests made over the specified LDAP connection
       will use this cache. To disassociate the cache from the LDAP connection handle, make a call to  the  ldap_bind(3LDAP)  or  ldap_bind(3LDAP)
       function.  Make	a  call  to ldap_memcache_set() if you want to associate  a cache with multiple LDAP connection handles. For example, call
       the ldap_memcache_get() function to get the cache associated with one connection, then you can call this function and associate	the  cache
       with another connection.

       The ldap_memcache_get() function gets the cache associated with the specified connection handle (LDAP structure). This cache is used by all
       search  requests made through that connection. When you call this function, the function sets the cachep parameter  as  a  pointer  to  the
       LDAPMemCache structure that is associated with the connection handle.

       ldap_memcache_flush()  flushes  search  requests from the cache. If the base DN of a search request is within the scope specified by the dn
       and scope arguments, the search request is flushed from the cache. If no DN is specified, the entire cache is flushed. The scope parameter,
       along with the dn parameter, identifies the search requests that you want flushed from the cache. This argument can have one of the follow-
       ing values:
	 LDAP_SCOPE_BASE
	 LDAP_SCOPE_ONELEVEL
	 LDAP_SCOPE_SUBTREE

       ldap_memcache_destroy() frees the specified LDAPMemCache structure pointed to by cache from memory. Call this function after you  are  done
       working with a cache.

       ldap_memcache_update()  checks the cache for items that have expired  and removes them. This check is typically done as part of the way the
       cache normally works. You do not need to call this function unless you  want to update the cache at this point in time.	This  function	is
       only  useful in a multithreaded application, since it will not return until the cache is destroyed.

PARAMETERS

       ttl	     The maximum amount of time (in seconds) that an item can be cached

       size	     The maximum amount of memory (in bytes)  that the cache will consume.

       baseDNs	     An array of the base DN strings representing  the base DNs of the search requests you want cached

       thread_fns    A pointer to the ldap_thread_fns structure structure.

       cachep	     A pointer to the LDAPMemCache structure

       cache	     The result of a cache created by the ldap_memcache_init() call

       ld	     The result of a successful call to ldap_open(3LDAP)

       dn	     The search requests that you want flushed from the cache

       scope	     The search requests that you want flushed from the cache

ERRORS

       The  functions  that  have int return values return LDAP_SUCCESS if the operation was successful. Otherwise, they return another LDAP error
       code. See ldap_error(3LDAP) for a list of the LDAP error codes.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsl (32-bit)		   |
       +-----------------------------+-----------------------------+
       |			     |SUNWcslx (64-bit) 	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       ldap_error(3LDAP), ldap_open(3LDAP), ldap_search(3LDAP), attributes(5)

SunOS 5.11							    6 Jan 2003						      ldap_memcache(3LDAP)