acache.h revision ec5347e2c775f027573ce5648b910361aa926c01
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Copyright (C) 2004, 2006 Internet Systems Consortium, Inc. ("ISC")
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Permission to use, copy, modify, and/or distribute this software for any
6ea2385360e9e2167e65f9286447da9eea189457Tinderbox User * purpose with or without fee is hereby granted, provided that the above
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * copyright notice and this permission notice appear in all copies.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * PERFORMANCE OF THIS SOFTWARE.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt/* $Id: acache.h,v 1.7 2007/06/18 23:47:42 tbox Exp $ */
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt ***** Module Info
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * The Additional Cache Object
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * This module manages internal caching entries that correspond to
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * the additional section data of a DNS DB node (an RRset header, more
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * accurately). An additional cache entry is expected to be (somehow)
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * attached to a particular RR in a particular DB node, and contains a set
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * of information of an additional data for the DB node.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * An additional cache object is intended to be created as a per-view
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * object, and manages all cache entries within the view.
207cee019eb5cbbe7c905f7c52f7b5d11f8c0305Automatic Updater * The intended usage of the additional caching is to provide a short cut
6ea2385360e9e2167e65f9286447da9eea189457Tinderbox User * to additional glue RRs of an NS RR. For each NS RR, it is often
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * necessary to look for glue RRs to make a proper response. Once the
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * glue RRs are known, the additional caching allows the client to
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * associate the information to the original NS RR so that further
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * expensive lookups can be avoided for the NS RR.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Each additional cache entry contains information to identify a
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * particular DB node and (optionally) an associated RRset. The
b843f577bbcd6660fbaa506d9e55b156c689a5a8Evan Hunt * information consists of its zone, database, the version of the
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * database, database node, and RRset.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * A "negative" information can also be cached. For example, if a glue
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * RR does not exist as an authoritative data in the same zone as that
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * of the NS RR, this fact can be cached by specifying a NULL pointer
b843f577bbcd6660fbaa506d9e55b156c689a5a8Evan Hunt * for the database, version, and node. (See the description for
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * dns_acache_getentry() below for more details.)
42782931073786f98d3d0a617351db40066949a4Mukund Sivaraman * Since each member stored in an additional cache entry holds a reference
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * to a corresponding object, a stale cache entry may cause unnecessary
8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont * memory consumption. For instance, when a zone is reloaded, additional
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * cache entries that have a reference to the zone (and its DB and/or
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * DB nodes) can delay the cleanup of the referred objects. In order to
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * minimize such a bad effect, this module provides several cleanup
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * mechanisms.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * The first one is a shutdown procedure called when the associated view
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * is shut down. In this case, dns_acache_shutdown() will be called and
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * all cache entries will be purged. This mechanism will help the
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * situation when the configuration is reloaded or the main server is
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Per-DB cleanup mechanism is also provided. Each additional cache entry
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * is associated with related DB, which is expected to have been
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * registered when the DB was created by dns_acache_setdb(). If a
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * particular DB is going to be destroyed, the primary holder of the DB,
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * a typical example of which is a zone, will call dns_acache_putdb().
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Then this module will clean-up all cache entries associated with the
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * DB. This mechanism is effective when a secondary zone DB is going to
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * be stale after a zone transfer.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Finally, this module supports for periodic clean-up of stale entries.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Each cache entry has a timestamp field, which is updated every time
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * the entry is referred. A periodically invoked cleaner checks the
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * timestamp of each entry, and purge entries that have not been referred
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * for a certain period. The cleaner interval can be specified by
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * dns_acache_setcleaninginterval(). If the periodic clean-up is not
d7be2b79ed0934483d550e17e2bd09de4eaff8f5Evan Hunt * enough, it is also possible to specify the upper limit of entries
d7be2b79ed0934483d550e17e2bd09de4eaff8f5Evan Hunt * in terms of the memory consumption. If the maximum value is
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * specified, the cleaner is invoked when the memory consumption reaches
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * the high watermark inferred from the maximum value. In this case,
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * the cleaner will use more aggressive algorithm to decide the "victim"
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * entries. The maximum value can be specified by
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * dns_acache_setcachesize().
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * When a cache entry is going to be purged within this module, the
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * callback function specified at the creation time will be called.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * The callback function is expected to release all internal resources
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * related to the entry, which will typically be specific to DB
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * implementation, and to call dns_acache_detachentry(). The callback
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * mechanism is very important, since the holder of an additional cache
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * entry may not be able to initiate the clean-up of the entry, due to
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * the reference ordering. For example, as long as an additional cache
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * entry has a reference to a DB object, the DB cannot be freed, in which
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * a DB node may have a reference to the cache entry.
10a759cee69dcc3ce3a4d65e6e263c66e7f60ee8Evan Hunt * The basic idea of this kind of short-cut for frequently used
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * information is similar to the "pre-compiled answer" approach adopted
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * in nsd by NLnet LABS with RIPE NCC. Our work here is an independent
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * effort, but the success of nsd encouraged us to pursue this path.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * The design and implementation of the periodic memory management and
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * the upper limitation of memory consumption was derived from the cache
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * DB implementation of BIND9.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * There are two main locks in this module. One is for each entry, and
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * the other is for the additional cache object.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Reliability:
61bcc232038f0a2cb77ed6269675fdc288f5ec98Evan Hunt * The callback function for a cache entry is called with holding the
61bcc232038f0a2cb77ed6269675fdc288f5ec98Evan Hunt * entry lock. Thus, it implicitly assumes the callback function does not
61bcc232038f0a2cb77ed6269675fdc288f5ec98Evan Hunt * call a function that can require the lock. Typically, the only
61bcc232038f0a2cb77ed6269675fdc288f5ec98Evan Hunt * function that can be called from the callback function safely is
61bcc232038f0a2cb77ed6269675fdc288f5ec98Evan Hunt * dns_acache_detachentry(). The breakage of this implicit assumption
61bcc232038f0a2cb77ed6269675fdc288f5ec98Evan Hunt * may cause a deadlock.
61bcc232038f0a2cb77ed6269675fdc288f5ec98Evan Hunt * Resources:
61bcc232038f0a2cb77ed6269675fdc288f5ec98Evan Hunt * In a 32-bit architecture (such as i386), the following additional
61bcc232038f0a2cb77ed6269675fdc288f5ec98Evan Hunt * memory is required comparing to the case that disables this module.
61bcc232038f0a2cb77ed6269675fdc288f5ec98Evan Hunt * - 76 bytes for each additional cache entry
61bcc232038f0a2cb77ed6269675fdc288f5ec98Evan Hunt * - if the entry has a DNS name and associated RRset,
61bcc232038f0a2cb77ed6269675fdc288f5ec98Evan Hunt * * 44 bytes + size of the name (1-255 bytes)
61bcc232038f0a2cb77ed6269675fdc288f5ec98Evan Hunt * * 52 bytes x number_of_RRs
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * - 28 bytes for each DB related to this module
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Using the additional cache also requires extra memory consumption in
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * the DB implementation. In the current implementation for rbtdb, we
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * - two additional pointers for each DB node (8 bytes for a 32-bit
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * architecture
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * - for each RR associated to an RR in a DB node, we also need
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * a pointer and management objects to support the additional cache
42782931073786f98d3d0a617351db40066949a4Mukund Sivaraman * function. These are allocated on-demand. The total size is
42782931073786f98d3d0a617351db40066949a4Mukund Sivaraman * 32 bytes for a 32-bit architecture.
42782931073786f98d3d0a617351db40066949a4Mukund Sivaraman * Since this module does not handle any low-level data directly,
42782931073786f98d3d0a617351db40066949a4Mukund Sivaraman * no security issue specific to this module is anticipated.
ba751492fcc4f161a18b983d4f018a1a52938cb9Evan Hunt *** Functions
ba751492fcc4f161a18b983d4f018a1a52938cb9Evan Huntdns_acache_create(dns_acache_t **acachep, isc_mem_t *mctx,
ba751492fcc4f161a18b983d4f018a1a52938cb9Evan Hunt isc_taskmgr_t *taskmgr, isc_timermgr_t *timermgr);
8b78c993cb475cc94e88560941b28c37684789d9Francis Dupont * Create a new DNS additional cache object.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 'mctx' is a valid memory context
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 'taskmgr' is a valid task manager
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 'timermgr' is a valid timer or NULL. If NULL, no periodic cleaning of
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * the cache will take place.
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * 'acachep' is a valid pointer, and *acachep == NULL
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * '*acachep' is attached to the newly created cache
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * ISC_R_SUCCESS
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * ISC_R_NOMEMORY
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * ISC_R_UNEXPECTED
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Huntdns_acache_attach(dns_acache_t *source, dns_acache_t **targetp);
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Attach *targetp to cache.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 'acache' is a valid additional cache.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 'targetp' points to a NULL dns_acache_t *.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * *targetp is attached to the 'source' additional cache.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Detach *acachep from its cache.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * '*acachep' points to a valid additional cache.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * *acachep is NULL.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * If '*acachep' is the last reference to the cache and the additional
b843f577bbcd6660fbaa506d9e55b156c689a5a8Evan Hunt * cache does not have an outstanding task, all resources used by the
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * cache will be freed.
b843f577bbcd6660fbaa506d9e55b156c689a5a8Evan Huntdns_acache_setcleaninginterval(dns_acache_t *acache, unsigned int t);
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Set the periodic cleaning interval of an additional cache to 'interval'
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Huntdns_acache_setcachesize(dns_acache_t *acache, isc_uint32_t size);
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Set the maximum additional cache size. 0 means unlimited.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Huntdns_acache_setdb(dns_acache_t *acache, dns_db_t *db);
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Set 'db' in 'acache' when the db can be referred from acache, in order
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * to provide a hint for resolving the back reference.
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * 'acache' is a valid acache pointer.
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * 'db' is a valid DNS DB pointer.
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * 'acache' will have a reference to 'db'.
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * ISC_R_SUCCESS
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * ISC_R_EXISTS (which means the specified 'db' is already set)
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * ISC_R_NOMEMORY
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrewsdns_acache_putdb(dns_acache_t *acache, dns_db_t *db);
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * Release 'db' from 'acache' if it has been set by dns_acache_setdb().
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * 'acache' is a valid acache pointer.
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * 'db' is a valid DNS DB pointer.
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * 'acache' will release the reference to 'db'. Additionally, the content
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * of each cache entry that is related to the 'db' will be released via
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * the callback function.
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * ISC_R_SUCCESS
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * ISC_R_NOTFOUND (which means the specified 'db' is not set in 'acache')
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * ISC_R_NOMEMORY
c6f4972c745f8903aba6dcca41f17a44c473db66Mark Andrews * Shutdown 'acache'.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * '*acache' is a valid additional cache.
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Huntdns_acache_createentry(dns_acache_t *acache, dns_db_t *origdb,
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * Create an additional cache entry. A new entry is created and attached to
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * the given additional cache object. A callback function is also associated
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * with the created entry, which will be called when the cache entry is purged
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * for some reason.
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * 'acache' is a valid additional cache.
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * 'entryp' is a valid pointer, and *entryp == NULL
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * 'origdb' is a valid DNS DB pointer.
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * 'callback' and 'cbarg' can be NULL. In this case, however, the entry
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * is meaningless (and will be cleaned-up in the next periodical
c5259c013bba297cb0d38b85bd1c83fc26ef268cMark Andrews * cleaning).
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * '*entryp' will point to a new additional cache entry.
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * ISC_R_SUCCESS
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * ISC_R_NOMEMORY
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Huntdns_acache_getentry(dns_acacheentry_t *entry, dns_zone_t **zonep,
eab9975bcf5830a73f18ed8f320ae18ea32775eeEvan Hunt * Get content from a particular additional cache entry.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 'entry' is a valid additional cache entry.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 'zonep' is a NULL pointer or '*zonep' == NULL (this is the only
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * optional parameter.)
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 'dbp' is a valid pointer, and '*dbp' == NULL
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 'versionp' is a valid pointer, and '*versionp' == NULL
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 'nodep' is a valid pointer, and '*nodep' == NULL
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 'fname' is a valid DNS name.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 'msg' is a valid DNS message.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * Several possible cases can happen according to the content.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 1. For a positive cache entry,
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * '*zonep' will point to the corresponding zone (if zonep is a valid
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * '*dbp' will point to a DB for the zone,
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * '*versionp' will point to its version, and
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * '*nodep' will point to the corresponding DB node.
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 'fname' will have the DNS name of the DB node and contain a list of
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * rdataset for the node (which can be an empty list).
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * 2. For a negative cache entry that means no corresponding zone exists,
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * '*zonep' == NULL (if zonep is a valid pointer)
553ead32ff5b00284e574dcabc39115d4d74ec66Evan Hunt * '*dbp', '*versionp', and '*nodep' will be NULL.