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