ldap_cache(3)

     LDAP_CACHE(3)            OpenLDAP 2.1.12            LDAP_CACHE(3)

     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

     LIBRARY
          OpenLDAP LDAP (libldap, -lldap)

     SYNOPSIS
          #include <ldap.h>

          ldap_enable_cache( ld, timeout, maxmem )
          LDAP *ld;
          long timeout;
          long maxmem;

          void ldap_disable_cache( ld )
          LDAP *ld;

          void ldap_destroy_cache( ld )
          LDAP *ld;

          void ldap_flush_cache( ld )
          LDAP *ld;

          void ldap_uncache_entry( ld, dn )
          LDAP *ld;
          char *dn;

          void ldap_uncache_request( ld, msgid )
          LDAP *ld;
          int  msgid;

          void ldap_set_cache_options( ld, opts )
          LDAP      *ld;
          unsigned long  opts;

     DESCRIPTION
          These routines are used to control the behavior of the
          experimental client caching of ldap_search(3) and
          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.

          ldap_enable_cache() should be called to turn on local
          caching or to change cache parameters (lifetime of cached
          requests and memory used).  The ld parameter should be the
          result of a successful call to ldap_open(3).  The timeout is
          specified in seconds, and is used to decide how long to keep
          cached requests.  The maxmem value is in bytes, and is used
          to set an upper bound on how memory the cache will use.  You

     Page 1                                         (printed 1/20/103)

     LDAP_CACHE(3)            OpenLDAP 2.1.12            LDAP_CACHE(3)

          can specify 0 for maxmem to restrict the cache size by the
          timeout only.  The first call to ldap_enable_cache creates
          the cache; subsequent calls re-enable the cache and set the
          timeout and memory values.

          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.

          ldap_destroy_cache() turns off caching and completely
          removes the cache from memory.

          ldap_flush_cache() deletes the cache contents, but does not
          effect it in any other way.

          ldap_uncache_entry() removes all requests that make
          reference to the distinguished name dn from the cache.  It
          should be used, for example, after doing an ldap_modify(3)
          call involving dn.

          ldap_uncache_request() removes the request indicated by the
          LDAP request id msgid from the cache.

          ldap_set_cache_options() is used to change caching behavior.
          The current supported options are LDAP_CACHE_OPT_CACHENOERRS
          to suppress caching of any requests that result in an error,
          and 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 LDAP_SIZELIMIT_EXCEEDED are cached.

     ERRORS
          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.

     SEE ALSO
          ldap(3), ldap_search(3), ldap_compare(3)

     ACKNOWLEDGEMENTS
          OpenLDAP is developed and maintained by The OpenLDAP Project
          (http://www.openldap.org/).  OpenLDAP is derived from
          University of Michigan LDAP 3.3 Release.

     Page 2                                         (printed 1/20/103)