"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.11.23/lib/dns/include/dns/cache.h" (7 Sep 2020, 8150 Bytes) of package /linux/misc/dns/bind9/9.11.23/bind-9.11.23.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "cache.h" see the Fossies "Dox" file reference documentation.

    1 /*
    2  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
    3  *
    4  * This Source Code Form is subject to the terms of the Mozilla Public
    5  * License, v. 2.0. If a copy of the MPL was not distributed with this
    6  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
    7  *
    8  * See the COPYRIGHT file distributed with this work for additional
    9  * information regarding copyright ownership.
   10  */
   11 
   12 
   13 #ifndef DNS_CACHE_H
   14 #define DNS_CACHE_H 1
   15 
   16 /*****
   17  ***** Module Info
   18  *****/
   19 
   20 /*! \file dns/cache.h
   21  * \brief
   22  * Defines dns_cache_t, the cache object.
   23  *
   24  * Notes:
   25  *\li   A cache object contains DNS data of a single class.
   26  *  Multiple classes will be handled by creating multiple
   27  *  views, each with a different class and its own cache.
   28  *
   29  * MP:
   30  *\li   See notes at the individual functions.
   31  *
   32  * Reliability:
   33  *
   34  * Resources:
   35  *
   36  * Security:
   37  *
   38  * Standards:
   39  */
   40 
   41 /***
   42  ***    Imports
   43  ***/
   44 
   45 #include <stdbool.h>
   46 
   47 #include <isc/json.h>
   48 #include <isc/lang.h>
   49 #include <isc/stats.h>
   50 #include <isc/stdtime.h>
   51 
   52 #include <dns/types.h>
   53 
   54 ISC_LANG_BEGINDECLS
   55 
   56 /***
   57  ***    Functions
   58  ***/
   59 
   60 isc_result_t
   61 dns_cache_create(isc_mem_t *cmctx, isc_taskmgr_t *taskmgr,
   62          isc_timermgr_t *timermgr, dns_rdataclass_t rdclass,
   63          const char *db_type, unsigned int db_argc, char **db_argv,
   64          dns_cache_t **cachep);
   65 isc_result_t
   66 dns_cache_create2(isc_mem_t *cmctx, isc_taskmgr_t *taskmgr,
   67           isc_timermgr_t *timermgr, dns_rdataclass_t rdclass,
   68           const char *cachename, const char *db_type,
   69           unsigned int db_argc, char **db_argv, dns_cache_t **cachep);
   70 isc_result_t
   71 dns_cache_create3(isc_mem_t *cmctx, isc_mem_t *hmctx, isc_taskmgr_t *taskmgr,
   72           isc_timermgr_t *timermgr, dns_rdataclass_t rdclass,
   73           const char *cachename, const char *db_type,
   74           unsigned int db_argc, char **db_argv, dns_cache_t **cachep);
   75 /*%<
   76  * Create a new DNS cache.
   77  *
   78  * dns_cache_create2() will create a named cache.
   79  *
   80  * dns_cache_create3() will create a named cache using two separate memory
   81  * contexts, one for cache data which can be cleaned and a separate one for
   82  * memory allocated for the heap (which can grow without an upper limit and
   83  * has no mechanism for shrinking).
   84  *
   85  * dns_cache_create() is a backward compatible version that internally
   86  * specifies an empty cache name and a single memory context.
   87  *
   88  * Requires:
   89  *
   90  *\li   'cmctx' (and 'hmctx' if applicable) is a valid memory context.
   91  *
   92  *\li   'taskmgr' is a valid task manager and 'timermgr' is a valid timer
   93  *  manager, or both are NULL.  If NULL, no periodic cleaning of the
   94  *  cache will take place.
   95  *
   96  *\li   'cachename' is a valid string.  This must not be NULL.
   97  *
   98  *\li   'cachep' is a valid pointer, and *cachep == NULL
   99  *
  100  * Ensures:
  101  *
  102  *\li   '*cachep' is attached to the newly created cache
  103  *
  104  * Returns:
  105  *
  106  *\li   #ISC_R_SUCCESS
  107  *\li   #ISC_R_NOMEMORY
  108  */
  109 
  110 void
  111 dns_cache_attach(dns_cache_t *cache, dns_cache_t **targetp);
  112 /*%<
  113  * Attach *targetp to cache.
  114  *
  115  * Requires:
  116  *
  117  *\li   'cache' is a valid cache.
  118  *
  119  *\li   'targetp' points to a NULL dns_cache_t *.
  120  *
  121  * Ensures:
  122  *
  123  *\li   *targetp is attached to cache.
  124  */
  125 
  126 void
  127 dns_cache_detach(dns_cache_t **cachep);
  128 /*%<
  129  * Detach *cachep from its cache.
  130  *
  131  * Requires:
  132  *
  133  *\li   'cachep' points to a valid cache.
  134  *
  135  * Ensures:
  136  *
  137  *\li   *cachep is NULL.
  138  *
  139  *\li   If '*cachep' is the last reference to the cache,
  140  *      all resources used by the cache will be freed
  141  */
  142 
  143 void
  144 dns_cache_attachdb(dns_cache_t *cache, dns_db_t **dbp);
  145 /*%<
  146  * Attach *dbp to the cache's database.
  147  *
  148  * Notes:
  149  *
  150  *\li   This may be used to get a reference to the database for
  151  *  the purpose of cache lookups (XXX currently it is also
  152  *  the way to add data to the cache, but having a
  153  *  separate dns_cache_add() interface instead would allow
  154  *  more control over memory usage).
  155  *  The caller should call dns_db_detach() on the reference
  156  *  when it is no longer needed.
  157  *
  158  * Requires:
  159  *
  160  *\li   'cache' is a valid cache.
  161  *
  162  *\li   'dbp' points to a NULL dns_db *.
  163  *
  164  * Ensures:
  165  *
  166  *\li   *dbp is attached to the database.
  167  */
  168 
  169 
  170 isc_result_t
  171 dns_cache_setfilename(dns_cache_t *cache, const char *filename);
  172 /*%<
  173  * If 'filename' is non-NULL, make the cache persistent.
  174  * The cache's data will be stored in the given file.
  175  * If 'filename' is NULL, make the cache non-persistent.
  176  * Files that are no longer used are not unlinked automatically.
  177  *
  178  * Returns:
  179  *\li   #ISC_R_SUCCESS
  180  *\li   #ISC_R_NOMEMORY
  181  *\li   Various file-related failures
  182  */
  183 
  184 isc_result_t
  185 dns_cache_load(dns_cache_t *cache);
  186 /*%<
  187  * If the cache has a file name, load the cache contents from the file.
  188  * Previous cache contents are not discarded.
  189  * If no file name has been set, do nothing and return success.
  190  *
  191  * MT:
  192  *\li   Multiple simultaneous attempts to load or dump the cache
  193  *  will be serialized with respect to one another, but
  194  *  the cache may be read and updated while the dump is
  195  *  in progress.  Updates performed during loading
  196  *  may or may not be preserved, and reads may return
  197  *  either the old or the newly loaded data.
  198  *
  199  * Returns:
  200  *
  201  *\li   #ISC_R_SUCCESS
  202  *  \li    Various failures depending on the database implementation type
  203  */
  204 
  205 isc_result_t
  206 dns_cache_dump(dns_cache_t *cache);
  207 /*%<
  208  * If the cache has a file name, write the cache contents to disk,
  209  * overwriting any preexisting file.  If no file name has been set,
  210  * do nothing and return success.
  211  *
  212  * MT:
  213  *\li   Multiple simultaneous attempts to load or dump the cache
  214  *  will be serialized with respect to one another, but
  215  *  the cache may be read and updated while the dump is
  216  *  in progress.  Updates performed during the dump may
  217  *  or may not be reflected in the dumped file.
  218  *
  219  * Returns:
  220  *
  221  *\li   #ISC_R_SUCCESS
  222  *  \li    Various failures depending on the database implementation type
  223  */
  224 
  225 isc_result_t
  226 dns_cache_clean(dns_cache_t *cache, isc_stdtime_t now);
  227 /*%<
  228  * Force immediate cleaning of the cache, freeing all rdatasets
  229  * whose TTL has expired as of 'now' and that have no pending
  230  * references.
  231  */
  232 
  233 void
  234 dns_cache_setcleaninginterval(dns_cache_t *cache, unsigned int interval);
  235 /*%<
  236  * Set the periodic cache cleaning interval to 'interval' seconds.
  237  */
  238 
  239 unsigned int
  240 dns_cache_getcleaninginterval(dns_cache_t *cache);
  241 /*%<
  242  * Get the periodic cache cleaning interval to 'interval' seconds.
  243  */
  244 
  245 const char *
  246 dns_cache_getname(dns_cache_t *cache);
  247 /*%<
  248  * Get the cache name.
  249  */
  250 
  251 void
  252 dns_cache_setcachesize(dns_cache_t *cache, size_t size);
  253 /*%<
  254  * Set the maximum cache size.  0 means unlimited.
  255  */
  256 
  257 size_t
  258 dns_cache_getcachesize(dns_cache_t *cache);
  259 /*%<
  260  * Get the maximum cache size.
  261  */
  262 
  263 isc_result_t
  264 dns_cache_flush(dns_cache_t *cache);
  265 /*%<
  266  * Flushes all data from the cache.
  267  *
  268  * Returns:
  269  *\li   #ISC_R_SUCCESS
  270  *\li   #ISC_R_NOMEMORY
  271  */
  272 
  273 isc_result_t
  274 dns_cache_flushnode(dns_cache_t *cache, dns_name_t *name,
  275             bool tree);
  276 /*
  277  * Flush a given name from the cache.  If 'tree' is true, then
  278  * also flush all names under 'name'.
  279  *
  280  * Requires:
  281  *\li   'cache' to be valid.
  282  *\li   'name' to be valid.
  283  *
  284  * Returns:
  285  *\li   #ISC_R_SUCCESS
  286  *\li   #ISC_R_NOMEMORY
  287  *\li   other error returns.
  288  */
  289 
  290 isc_result_t
  291 dns_cache_flushname(dns_cache_t *cache, dns_name_t *name);
  292 /*
  293  * Flush a given name from the cache.  Equivalent to
  294  * dns_cache_flushpartial(cache, name, false).
  295  *
  296  * Requires:
  297  *\li   'cache' to be valid.
  298  *\li   'name' to be valid.
  299  *
  300  * Returns:
  301  *\li   #ISC_R_SUCCESS
  302  *\li   #ISC_R_NOMEMORY
  303  *\li   other error returns.
  304  */
  305 
  306 isc_stats_t *
  307 dns_cache_getstats(dns_cache_t *cache);
  308 /*
  309  * Return a pointer to the stats collection object for 'cache'
  310  */
  311 
  312 void
  313 dns_cache_dumpstats(dns_cache_t *cache, FILE *fp);
  314 /*
  315  * Dump cache statistics and status in text to 'fp'
  316  */
  317 
  318 void
  319 dns_cache_updatestats(dns_cache_t *cache, isc_result_t result);
  320 /*
  321  * Update cache statistics based on result code in 'result'
  322  */
  323 
  324 #ifdef HAVE_LIBXML2
  325 int
  326 dns_cache_renderxml(dns_cache_t *cache, xmlTextWriterPtr writer);
  327 /*
  328  * Render cache statistics and status in XML for 'writer'.
  329  */
  330 #endif /* HAVE_LIBXML2 */
  331 
  332 #ifdef HAVE_JSON
  333 isc_result_t
  334 dns_cache_renderjson(dns_cache_t *cache, json_object *cstats);
  335 /*
  336  * Render cache statistics and status in JSON
  337  */
  338 #endif /* HAVE_JSON */
  339 
  340 ISC_LANG_ENDDECLS
  341 
  342 #endif /* DNS_CACHE_H */