FM / dns

/usr/include/bind9/dns

Name	Size	Mode	Actions
acache.h	14232	0644	edit dl rm
acl.h	7242	0644	edit dl rm
adb.h	22595	0644	edit dl rm
badcache.h	3369	0644	edit dl rm
bit.h	807	0644	edit dl rm
byaddr.h	4002	0644	edit dl rm
cache.h	8643	0644	edit dl rm
callbacks.h	2271	0644	edit dl rm
catz.h	11833	0644	edit dl rm
cert.h	1466	0644	edit dl rm
client.h	22042	0644	edit dl rm
clientinfo.h	2006	0644	edit dl rm
compress.h	6646	0644	edit dl rm
db.h	47061	0644	edit dl rm
dbiterator.h	7422	0644	edit dl rm
dbtable.h	3165	0644	edit dl rm
diff.h	6980	0644	edit dl rm
dispatch.h	16427	0644	edit dl rm
dlz.h	10618	0644	edit dl rm
dlz_dlopen.h	4677	0644	edit dl rm
dns64.h	5635	0644	edit dl rm
dnssec.h	12371	0644	edit dl rm
dnstap.h	9364	0644	edit dl rm
ds.h	1225	0644	edit dl rm
dsdigest.h	1722	0644	edit dl rm
dyndb.h	4835	0644	edit dl rm
ecdb.h	809	0644	edit dl rm
edns.h	722	0644	edit dl rm
enumclass.h	1220	0644	edit dl rm
enumtype.h	8300	0644	edit dl rm
events.h	4059	0644	edit dl rm
fixedname.h	1663	0644	edit dl rm
forward.h	3452	0644	edit dl rm
geoip.h	2792	0644	edit dl rm
ipkeylist.h	2186	0644	edit dl rm
iptable.h	1621	0644	edit dl rm
journal.h	8227	0644	edit dl rm
keydata.h	1059	0644	edit dl rm
keyflags.h	1278	0644	edit dl rm
keytable.h	9462	0644	edit dl rm
keyvalues.h	4159	0644	edit dl rm
lib.h	1192	0644	edit dl rm
log.h	3964	0644	edit dl rm
lookup.h	2924	0644	edit dl rm
master.h	11289	0644	edit dl rm
masterdump.h	12647	0644	edit dl rm
message.h	39023	0644	edit dl rm
name.h	37115	0644	edit dl rm
ncache.h	4929	0644	edit dl rm
nsec.h	3397	0644	edit dl rm
nsec3.h	8032	0644	edit dl rm
nta.h	4548	0644	edit dl rm
opcode.h	1007	0644	edit dl rm
order.h	1999	0644	edit dl rm
peer.h	5966	0644	edit dl rm
portlist.h	2101	0644	edit dl rm
private.h	1935	0644	edit dl rm
rbt.h	40618	0644	edit dl rm
rcode.h	2481	0644	edit dl rm
rdata.h	21613	0644	edit dl rm
rdataclass.h	2257	0644	edit dl rm
rdatalist.h	2569	0644	edit dl rm
rdataset.h	21536	0644	edit dl rm
rdatasetiter.h	3926	0644	edit dl rm
rdataslab.h	4528	0644	edit dl rm
rdatastruct.h	61584	0644	edit dl rm
rdatatype.h	2298	0644	edit dl rm
request.h	11156	0644	edit dl rm
resolver.h	20227	0644	edit dl rm
result.h	9284	0644	edit dl rm
rootns.h	892	0644	edit dl rm
rpz.h	10335	0644	edit dl rm
rriterator.h	4230	0644	edit dl rm
rrl.h	6640	0644	edit dl rm
sdb.h	7224	0644	edit dl rm
sdlz.h	14214	0644	edit dl rm
secalg.h	1706	0644	edit dl rm
secproto.h	1557	0644	edit dl rm
soa.h	2186	0644	edit dl rm
ssu.h	8308	0644	edit dl rm
stats.h	13451	0644	edit dl rm
tcpmsg.h	3145	0644	edit dl rm
time.h	1695	0644	edit dl rm
timer.h	1051	0644	edit dl rm
tkey.h	7631	0644	edit dl rm
tsec.h	2949	0644	edit dl rm
tsig.h	8384	0644	edit dl rm
ttl.h	1945	0644	edit dl rm
types.h	14212	0644	edit dl rm
update.h	1653	0644	edit dl rm
validator.h	7161	0644	edit dl rm
version.h	868	0644	edit dl rm
view.h	35274	0644	edit dl rm
xfrin.h	2924	0644	edit dl rm
zone.h	60864	0644	edit dl rm
zonekey.h	777	0644	edit dl rm
zt.h	5562	0644	edit dl rm

Edit: /usr/include/bind9/dns/acache.h (14232B)

/*
 * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, you can obtain one at https://mozilla.org/MPL/2.0/.
 *
 * See the COPYRIGHT file distributed with this work for additional
 * information regarding copyright ownership.
 */

#ifndef DNS_ACACHE_H
#define DNS_ACACHE_H 1

/*****
 ***** Module Info
 *****/

/*
 * Acache
 *
 * The Additional Cache Object
 *
 *	This module manages internal caching entries that correspond to
 *	the additional section data of a DNS DB node (an RRset header, more
 *	accurately).  An additional cache entry is expected to be (somehow)
 *	attached to a particular RR in a particular DB node, and contains a set
 *	of information of an additional data for the DB node.
 *
 *	An additional cache object is intended to be created as a per-view
 *	object, and manages all cache entries within the view.
 *
 *	The intended usage of the additional caching is to provide a short cut
 *	to additional glue RRs of an NS RR.  For each NS RR, it is often
 *	necessary to look for glue RRs to make a proper response.  Once the
 *	glue RRs are known, the additional caching allows the client to
 *	associate the information to the original NS RR so that further
 *	expensive lookups can be avoided for the NS RR.
 *
 *	Each additional cache entry contains information to identify a
 *	particular DB node and (optionally) an associated RRset.  The
 *	information consists of its zone, database, the version of the
 *	database, database node, and RRset.
 *
 *	A "negative" information can also be cached.  For example, if a glue
 *	RR does not exist as an authoritative data in the same zone as that
 *	of the NS RR, this fact can be cached by specifying a NULL pointer
 *	for the database, version, and node.  (See the description for
 *	dns_acache_getentry() below for more details.)
 *
 *	Since each member stored in an additional cache entry holds a reference
 *	to a corresponding object, a stale cache entry may cause unnecessary
 *	memory consumption.  For instance, when a zone is reloaded, additional
 *	cache entries that have a reference to the zone (and its DB and/or
 *	DB nodes) can delay the cleanup of the referred objects.  In order to
 *	minimize such a bad effect, this module provides several cleanup
 *	mechanisms.
 *
 *	The first one is a shutdown procedure called when the associated view
 *	is shut down.  In this case, dns_acache_shutdown() will be called and
 *	all cache entries will be purged.  This mechanism will help the
 *	situation when the configuration is reloaded or the main server is
 *	stopped.
 *
 *	Per-DB cleanup mechanism is also provided.  Each additional cache entry
 *	is associated with related DB, which is expected to have been
 *	registered when the DB was created by dns_acache_setdb().  If a
 *	particular DB is going to be destroyed, the primary holder of the DB,
 *	a typical example of which is a zone, will call dns_acache_putdb().
 *	Then this module will clean-up all cache entries associated with the
 *	DB.  This mechanism is effective when a secondary zone DB is going to
 *	be stale after a zone transfer.
 *
 *	Finally, this module supports for periodic clean-up of stale entries.
 *	Each cache entry has a timestamp field, which is updated every time
 *	the entry is referred.  A periodically invoked cleaner checks the
 *	timestamp of each entry, and purge entries that have not been referred
 *	for a certain period.  The cleaner interval can be specified by
 *	dns_acache_setcleaninginterval().  If the periodic clean-up is not
 *	enough, it is also possible to specify the upper limit of entries
 *	in terms of the memory consumption.  If the maximum value is
 *	specified, the cleaner is invoked when the memory consumption reaches
 *	the high watermark inferred from the maximum value.  In this case,
 *	the cleaner will use more aggressive algorithm to decide the "victim"
 *	entries.  The maximum value can be specified by
 *	dns_acache_setcachesize().
 *
 *	When a cache entry is going to be purged within this module, the
 *	callback function specified at the creation time will be called.
 *	The callback function is expected to release all internal resources
 *	related to the entry, which will typically be specific to DB
 *	implementation, and to call dns_acache_detachentry().  The callback
 *	mechanism is very important, since the holder of an additional cache
 *	entry may not be able to initiate the clean-up of the entry, due to
 *	the reference ordering.  For example, as long as an additional cache
 *	entry has a reference to a DB object, the DB cannot be freed, in which
 *	a DB node may have a reference to the cache entry.
 *
 *	Credits:
 *	The basic idea of this kind of short-cut for frequently used
 *	information is similar to the "pre-compiled answer" approach adopted
 *	in nsd by NLnet LABS with RIPE NCC.  Our work here is an independent
 *	effort, but the success of nsd encouraged us to pursue this path.
 *
 *	The design and implementation of the periodic memory management and
 *	the upper limitation of memory consumption was derived from the cache
 *	DB implementation of BIND9.
 *
 * MP:
 *	There are two main locks in this module.  One is for each entry, and
 *	the other is for the additional cache object.
 *
 * Reliability:
 *	The callback function for a cache entry is called with holding the
 *	entry lock.  Thus, it implicitly assumes the callback function does not
 *	call a function that can require the lock.  Typically, the only
 *	function that can be called from the callback function safely is
 *	dns_acache_detachentry().  The breakage of this implicit assumption
 *	may cause a deadlock.
 *
 * Resources:
 *	In a 32-bit architecture (such as i386), the following additional
 *	memory is required comparing to the case that disables this module.
 *	- 76 bytes for each additional cache entry
 *	- if the entry has a DNS name and associated RRset,
 *	  * 44 bytes + size of the name (1-255 bytes)
 *	  * 52 bytes x number_of_RRs
 *	- 28 bytes for each DB related to this module
 *
 *	Using the additional cache also requires extra memory consumption in
 *	the DB implementation.  In the current implementation for rbtdb, we
 *	need:
 *	- two additional pointers for each DB node (8 bytes for a 32-bit
 *	  architecture
 *	- for each RR associated to an RR in a DB node, we also need
 *	  a pointer and management objects to support the additional cache
 *	  function.  These are allocated on-demand.  The total size is
 *	  32 bytes for a 32-bit architecture.
 *
 * Security:
 *	Since this module does not handle any low-level data directly,
 *	no security issue specific to this module is anticipated.
 *
 * Standards:
 *	None.
 */

/***
 *** Imports
 ***/

#include <isc/mutex.h>
#include <isc/lang.h>
#include <isc/stdtime.h>

#include <dns/types.h>

/***
 *** Functions
 ***/
ISC_LANG_BEGINDECLS

isc_result_t
dns_acache_create(dns_acache_t **acachep, isc_mem_t *mctx,
		  isc_taskmgr_t *taskmgr, isc_timermgr_t *timermgr);
/*
 * Create a new DNS additional cache object.
 *
 * Requires:
 *
 *	'mctx' is a valid memory context
 *
 *	'taskmgr' is a valid task manager
 *
 *	'timermgr' is a valid timer or NULL.  If NULL, no periodic cleaning of
 *	the cache will take place.
 *
 *	'acachep' is a valid pointer, and *acachep == NULL
 *
 * Ensures:
 *
 *	'*acachep' is attached to the newly created cache
 *
 * Returns:
 *
 *	ISC_R_SUCCESS
 *	ISC_R_NOMEMORY
 *	ISC_R_UNEXPECTED
 */

void
dns_acache_attach(dns_acache_t *source, dns_acache_t **targetp);
/*
 * Attach *targetp to cache.
 *
 * Requires:
 *
 *	'acache' is a valid additional cache.
 *
 *	'targetp' points to a NULL dns_acache_t *.
 *
 * Ensures:
 *
 *	*targetp is attached to the 'source' additional cache.
 */

void
dns_acache_detach(dns_acache_t **acachep);
/*
 * Detach *acachep from its cache.
 *
 * Requires:
 *
 *	'*acachep' points to a valid additional cache.
 *
 * Ensures:
 *
 *	*acachep is NULL.
 *
 *	If '*acachep' is the last reference to the cache and the additional
 *	cache does not have an outstanding task, all resources used by the
 *	cache will be freed.
 */

void
dns_acache_setcleaninginterval(dns_acache_t *acache, unsigned int t);
/*
 * Set the periodic cleaning interval of an additional cache to 'interval'
 * seconds.
 */

void
dns_acache_setcachesize(dns_acache_t *acache, size_t size);
/*
 * Set the maximum additional cache size.  0 means unlimited.
 */

isc_result_t
dns_acache_setdb(dns_acache_t *acache, dns_db_t *db);
/*
 * Set 'db' in 'acache' when the db can be referred from acache, in order
 * to provide a hint for resolving the back reference.
 *
 * Requires:
 *	'acache' is a valid acache pointer.
 *	'db' is a valid DNS DB pointer.
 *
 * Ensures:
 *	'acache' will have a reference to 'db'.
 *
 * Returns:
 *	ISC_R_SUCCESS
 *	ISC_R_EXISTS	(which means the specified 'db' is already set)
 *	ISC_R_NOMEMORY
 */

isc_result_t
dns_acache_putdb(dns_acache_t *acache, dns_db_t *db);
/*
 * Release 'db' from 'acache' if it has been set by dns_acache_setdb().
 *
 * Requires:
 *	'acache' is a valid acache pointer.
 *	'db' is a valid DNS DB pointer.
 *
 * Ensures:
 *	'acache' will release the reference to 'db'.  Additionally, the content
 *	of each cache entry that is related to the 'db' will be released via
 *	the callback function.
 *
 * Returns:
 *	ISC_R_SUCCESS
 *	ISC_R_NOTFOUND	(which means the specified 'db' is not set in 'acache')
 *	ISC_R_NOMEMORY
 */

void
dns_acache_shutdown(dns_acache_t *acache);
/*
 * Shutdown 'acache'.
 *
 * Requires:
 *
 * 	'*acache' is a valid additional cache.
 */

isc_result_t
dns_acache_createentry(dns_acache_t *acache, dns_db_t *origdb,
		       void (*callback)(dns_acacheentry_t *, void **),
		       void *cbarg, dns_acacheentry_t **entryp);
/*
 * Create an additional cache entry.  A new entry is created and attached to
 * the given additional cache object.  A callback function is also associated
 * with the created entry, which will be called when the cache entry is purged
 * for some reason.
 *
 * Requires:
 *
 * 	'acache' is a valid additional cache.
 *	'entryp' is a valid pointer, and *entryp == NULL
 *	'origdb' is a valid DNS DB pointer.
 *	'callback' and 'cbarg' can be NULL.  In this case, however, the entry
 *	is meaningless (and will be cleaned-up in the next periodical
 *	cleaning).
 *
 * Ensures:
 *	'*entryp' will point to a new additional cache entry.
 *
 * Returns:
 *	ISC_R_SUCCESS
 *	ISC_R_NOMEMORY
 */

isc_result_t
dns_acache_getentry(dns_acacheentry_t *entry, dns_zone_t **zonep,
		    dns_db_t **dbp, dns_dbversion_t **versionp,
		    dns_dbnode_t **nodep, dns_name_t *fname,
		    dns_message_t *msg, isc_stdtime_t now);
/*
 * Get content from a particular additional cache entry.
 *
 * Requires:
 *
 * 	'entry' is a valid additional cache entry.
 *	'zonep' is a NULL pointer or '*zonep' == NULL (this is the only
 *	optional parameter.)
 *	'dbp' is a valid pointer, and '*dbp' == NULL
 *	'versionp' is a valid pointer, and '*versionp' == NULL
 *	'nodep' is a valid pointer, and '*nodep' == NULL
 *	'fname' is a valid DNS name.
 *	'msg' is a valid DNS message.
 *
 * Ensures:
 *	Several possible cases can happen according to the content.
 *	1. For a positive cache entry,
 *	'*zonep' will point to the corresponding zone (if zonep is a valid
 *	pointer),
 *	'*dbp' will point to a DB for the zone,
 *	'*versionp' will point to its version, and
 *	'*nodep' will point to the corresponding DB node.
 *	'fname' will have the DNS name of the DB node and contain a list of
 *	rdataset for the node (which can be an empty list).
 *
 * 	2. For a negative cache entry that means no corresponding zone exists,
 *	'*zonep' == NULL (if zonep is a valid pointer)
 *	'*dbp', '*versionp', and '*nodep' will be NULL.
 *
 *	3. For a negative cache entry that means no corresponding DB node
 *	exists, '*zonep' will point to the corresponding zone (if zonep is a
 *	valid pointer),
 *	'*dbp' will point to a corresponding DB for zone,
 *	'*versionp' will point to its version.
 *	'*nodep' will be kept as NULL.
 *	'fname' will not change.
 *
 *	On failure, no new references will be created.
 *
 * Returns:
 *	ISC_R_SUCCESS
 *	ISC_R_NOMEMORY
 */

isc_result_t
dns_acache_setentry(dns_acache_t *acache, dns_acacheentry_t *entry,
		    dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *version,
		    dns_dbnode_t *node, dns_name_t *fname);
/*
 * Set content to a particular additional cache entry.
 *
 * Requires:
 *	'acache' is a valid additional cache.
 *	'entry' is a valid additional cache entry.
 *	All the others pointers are NULL or a valid pointer of the
 *	corresponding type.
 *
 * Returns:
 *	ISC_R_SUCCESS
 *	ISC_R_NOMEMORY
 *	ISC_R_NOTFOUND
 */

bool
dns_acache_cancelentry(dns_acacheentry_t *entry);
/*
 * Cancel the use of the cache entry 'entry'.  This function is supposed to
 * be called when the node that holds the entry finds the content is not
 * correct any more.  This function will try to release as much dependency as
 * possible, and will be ready to be cleaned-up.  The registered callback
 * function will be canceled and will never called.
 *
 * Requires:
 *	'entry' is a valid additional cache entry.
 *
 * Returns:
 * 	true if the entry was active when canceled
 */

void
dns_acache_attachentry(dns_acacheentry_t *source, dns_acacheentry_t **targetp);
/*
 * Attach *targetp to the cache entry 'source'.
 *
 * Requires:
 *
 *	'source' is a valid additional cache entry.
 *
 *	'targetp' points to a NULL dns_acacheentry_t *.
 *
 * Ensures:
 *
 *	*targetp is attached to 'source'.
 */

void
dns_acache_detachentry(dns_acacheentry_t **entryp);
/*
 * Detach *entryp from its cache.
 *
 * Requires:
 *
 *	'*entryp' points to a valid additional cache entry.
 *
 * Ensures:
 *
 *	*entryp is NULL.
 *
 *	If '*entryp' is the last reference to the entry,
 *	cache does not have an outstanding task, all resources used by the
 *	entry (including the entry object itself) will be freed.
 */

void
dns_acache_countquerymiss(dns_acache_t *acache);
/*
 * Count up a missed acache query.  XXXMLG need more docs.
 */

ISC_LANG_ENDDECLS

#endif /* DNS_ACACHE_H */

cmd: