.TH LDAP_CACHE 3 "22 September 1998" "OpenLDAP LDVERSION" .\" $OpenLDAP: pkg/ldap/doc/man/man3/ldap_cache.3,v 1.8 2002/01/04 20:17:34 kurt Exp $ .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_enable_cache, ldap_disable_cache, ldap_destroy_cache, ldap_flush_cache, ldap_uncache_entry, ldap_uncache_request, ldap_set_cache_options \- LDAP client caching routines .SH SYNOPSIS .nf .ft B #include <ldap.h> .ft .LP .ft B ldap_enable_cache( ld, timeout, maxmem ) .ft LDAP *ld; long timeout; long maxmem; .LP .ft B void ldap_disable_cache( ld ) .ft LDAP *ld; .LP .ft B void ldap_destroy_cache( ld ) .ft LDAP *ld; .LP .ft B void ldap_flush_cache( ld ) .ft LDAP *ld; .LP .ft B void ldap_uncache_entry( ld, dn ) .ft LDAP *ld; char *dn; .LP .ft B void ldap_uncache_request( ld, msgid ) .ft LDAP *ld; int msgid; .LP .ft B void ldap_set_cache_options( ld, opts ) .ft LDAP *ld; unsigned long opts; .fi .SH DESCRIPTION .LP These routines are used to control the behavior of the .B experimental client caching of .BR ldap_search (3) and .BR ldap_compare (3) operations. By default, the cache is disabled and no caching is done. Enabling the cache can greatly improve performance and reduce network bandwidth when a client DUA makes repeated requests. .LP .B ldap_enable_cache() should be called to turn on local caching or to change cache parameters (lifetime of cached requests and memory used). The \fIld\fP parameter should be the result of a successful call to .BR ldap_open (3). The \fItimeout\fP is specified in seconds, and is used to decide how long to keep cached requests. The \fImaxmem\fP value is in bytes, and is used to set an upper bound on how memory the cache will use. You can specify 0 for \fImaxmem\fP to restrict the cache size by the \fItimeout\fP only. The first call to ldap_enable_cache creates the cache; subsequent calls re-enable the cache and set the timeout and memory values. .LP .B ldap_disable_cache() temporarily disables use of the cache (new requests are not cached and the cache is not checked when returning results). It does not delete the cache contents. .LP .B ldap_destroy_cache() turns off caching and completely removes the cache from memory. .LP .B ldap_flush_cache() deletes the cache contents, but does not effect it in any other way. .LP .B ldap_uncache_entry() removes all requests that make reference to the distinguished name \fIdn\fP from the cache. It should be used, for example, after doing an .BR ldap_modify (3) call involving \fIdn\fP. .LP .B ldap_uncache_request() removes the request indicated by the LDAP request id \fImsgid\fP from the cache. .LP .B ldap_set_cache_options() is used to change caching behavior. The current supported options are .B LDAP_CACHE_OPT_CACHENOERRS to suppress caching of any requests that result in an error, and .B LDAP_CACHE_OPT_CACHEALLERRS to enable caching of all requests. The default behavior is to not cache requests that result in errors, except that request that result in the error .B LDAP_SIZELIMIT_EXCEEDED are cached. .SH ERRORS .B ldap_enable_cache() returns 0 upon success, and -1 if it is unable to allocate space for the cache. All the other calls are declared as void and return nothing. .SH SEE ALSO .BR ldap (3), .BR ldap_search (3), .BR ldap_compare (3) .SH ACKNOWLEDGEMENTS .B OpenLDAP is developed and maintained by The OpenLDAP Project (http://www.openldap.org/). .B OpenLDAP is derived from University of Michigan LDAP 3.3 Release.