git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_cache.3

   1 .TH LDAP_CACHE 3  "14 November 1994" "U-M LDAP LDVERSION"
   2 .SH NAME
   3 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
   4 .SH SYNOPSIS
   5 .nf
   6 .ft B
   7 #include <lber.h>
   8 #include <ldap.h>
   9 .ft
  10 .LP
  11 .ft B
  12 ldap_enable_cache( ld, timeout, maxmem )
  13 .ft
  14 LDAP    *ld;
  15 long    timeout;
  16 long    maxmem;
  17 .LP
  18 .ft B
  19 void ldap_disable_cache( ld )
  20 .ft
  21 LDAP    *ld;
  22 .LP
  23 .ft B
  24 void ldap_destroy_cache( ld )
  25 .ft
  26 LDAP    *ld;
  27 .LP
  28 .ft B
  29 void ldap_flush_cache( ld )
  30 .ft
  31 LDAP    *ld;
  32 .LP
  33 .ft B
  34 void ldap_uncache_entry( ld, dn )
  35 .ft
  36 LDAP    *ld;
  37 char    *dn;
  38 .LP
  39 .ft B
  40 void ldap_uncache_request( ld, msgid )
  41 .ft
  42 LDAP    *ld;
  43 int     msgid;
  44 .LP
  45 .ft B
  46 void ldap_set_cache_options( ld, opts )
  47 .ft
  48 LDAP            *ld;
  49 unsigned long   opts;
  50 .fi
  51 .SH DESCRIPTION
  52 .LP
  53 These routines are used to control the behavior of client caching of
  54 .BR ldap_search (3),
  55 .BR cldap_search_s (3),
  56 and
  57 .BR ldap_compare (3)
  58 operations.  By
  59 default, the cache is disabled and no caching is done.  Enabling the
  60 cache can greatly improve performance and reduce network bandwidth when
  61 a client DUA makes repeated requests.
  62 .LP
  63 .B ldap_enable_cache()
  64 should be called to turn on local caching or to
  65 change cache parameters (lifetime of cached requests and memory used).
  66 The \fIld\fP parameter should be the result of a successful call to
  67 .BR ldap_open (3).
  68 The \fItimeout\fP is specified in seconds, and is used to
  69 decide how long to keep cached requests.  The \fImaxmem\fP value is in
  70 bytes, and is used to set an upper bound on how memory the cache will
  71 use.  You can specify 0 for \fImaxmem\fP to restrict the cache size by
  72 the \fItimeout\fP only.  The first call to ldap_enable_cache creates
  73 the cache; subsequent calls re-enable the cache and set the timeout and
  74 memory values.
  75 .LP
  76 .B ldap_disable_cache()
  77 temporarily disables use of the cache (new
  78 requests are not cached and the cache is not checked when returning
  79 results).  It does not delete the cache contents.
  80 .LP
  81 .B ldap_destroy_cache()
  82 turns off caching and completely removes the cache from memory.
  83 .LP
  84 .B ldap_flush_cache()
  85 deletes the cache contents, but does not effect it in any other way.
  86 .LP
  87 .B ldap_uncache_entry()
  88 removes all requests that make reference to the
  89 distinguished name \fIdn\fP from the cache.  It should be used, for
  90 example, after doing an
  91 .BR ldap_modify (3)
  92 call involving \fIdn\fP.
  93 .LP
  94 .B ldap_uncache_request()
  95 removes the request indicated by the LDAP request
  96 id \fImsgid\fP from the cache.
  97 .LP
  98 .B ldap_set_cache_options()
  99 is used to change caching behavior.  The current supported options are
 100 .B LDAP_CACHE_OPT_CACHENOERRS
 101 to suppress caching of any requests that result in an error, and
 102 .B LDAP_CACHE_OPT_CACHEALLERRS
 103 to enable caching of all requests.  The default behavior is to not
 104 cache requests that result in errors, except that request that result
 105 in the error
 106 .B LDAP_SIZELIMIT_EXCEEDED
 107 are cached.
 108 .SH ERRORS
 109 .B ldap_enable_cache()
 110 returns 0 upon success, and -1 if it is unable to
 111 allocate space for the cache.  All the other calls are declared as
 112 void and return nothing.
 113 .SH SEE ALSO
 114 .BR ldap (3),
 115 .BR ldap_search (3),
 116 .BR ldap_compare (3),
 117 .BR cldap_search_s (3)