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