2 * Copyright (C) 2004-2009 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2003 Internet Software Consortium.
5 * Permission to use, copy, modify, and/or distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
18 /* $Id: db.h,v 1.89.128.5.2.1 2009/12/31 21:45:53 each Exp $ */
29 * The DNS DB interface allows named rdatasets to be stored and retrieved.
31 * The dns_db_t type is like a "virtual class". To actually use
32 * DBs, an implementation of the class is required.
37 * \li The module ensures appropriate synchronization of data structures it
38 * creates and manipulates.
41 * \li No anticipated impact.
47 * \li No anticipated impact.
58 #include <isc/magic.h>
59 #include <isc/ondestroy.h>
60 #include <isc/stdtime.h>
63 #include <dns/types.h>
71 typedef struct dns_dbmethods {
72 void (*attach)(dns_db_t *source, dns_db_t **targetp);
73 void (*detach)(dns_db_t **dbp);
74 isc_result_t (*beginload)(dns_db_t *db, dns_addrdatasetfunc_t *addp,
75 dns_dbload_t **dbloadp);
76 isc_result_t (*endload)(dns_db_t *db, dns_dbload_t **dbloadp);
77 isc_result_t (*dump)(dns_db_t *db, dns_dbversion_t *version,
79 dns_masterformat_t masterformat);
80 void (*currentversion)(dns_db_t *db,
81 dns_dbversion_t **versionp);
82 isc_result_t (*newversion)(dns_db_t *db,
83 dns_dbversion_t **versionp);
84 void (*attachversion)(dns_db_t *db, dns_dbversion_t *source,
85 dns_dbversion_t **targetp);
86 void (*closeversion)(dns_db_t *db,
87 dns_dbversion_t **versionp,
88 isc_boolean_t commit);
89 isc_result_t (*findnode)(dns_db_t *db, dns_name_t *name,
91 dns_dbnode_t **nodep);
92 isc_result_t (*find)(dns_db_t *db, dns_name_t *name,
93 dns_dbversion_t *version,
94 dns_rdatatype_t type, unsigned int options,
96 dns_dbnode_t **nodep, dns_name_t *foundname,
97 dns_rdataset_t *rdataset,
98 dns_rdataset_t *sigrdataset);
99 isc_result_t (*findzonecut)(dns_db_t *db, dns_name_t *name,
100 unsigned int options, isc_stdtime_t now,
101 dns_dbnode_t **nodep,
102 dns_name_t *foundname,
103 dns_rdataset_t *rdataset,
104 dns_rdataset_t *sigrdataset);
105 void (*attachnode)(dns_db_t *db,
106 dns_dbnode_t *source,
107 dns_dbnode_t **targetp);
108 void (*detachnode)(dns_db_t *db,
109 dns_dbnode_t **targetp);
110 isc_result_t (*expirenode)(dns_db_t *db, dns_dbnode_t *node,
112 void (*printnode)(dns_db_t *db, dns_dbnode_t *node,
114 isc_result_t (*createiterator)(dns_db_t *db,
115 isc_boolean_t relative_names,
116 dns_dbiterator_t **iteratorp);
117 isc_result_t (*findrdataset)(dns_db_t *db, dns_dbnode_t *node,
118 dns_dbversion_t *version,
119 dns_rdatatype_t type,
120 dns_rdatatype_t covers,
122 dns_rdataset_t *rdataset,
123 dns_rdataset_t *sigrdataset);
124 isc_result_t (*allrdatasets)(dns_db_t *db, dns_dbnode_t *node,
125 dns_dbversion_t *version,
127 dns_rdatasetiter_t **iteratorp);
128 isc_result_t (*addrdataset)(dns_db_t *db, dns_dbnode_t *node,
129 dns_dbversion_t *version,
131 dns_rdataset_t *rdataset,
132 unsigned int options,
133 dns_rdataset_t *addedrdataset);
134 isc_result_t (*subtractrdataset)(dns_db_t *db, dns_dbnode_t *node,
135 dns_dbversion_t *version,
136 dns_rdataset_t *rdataset,
137 unsigned int options,
138 dns_rdataset_t *newrdataset);
139 isc_result_t (*deleterdataset)(dns_db_t *db, dns_dbnode_t *node,
140 dns_dbversion_t *version,
141 dns_rdatatype_t type,
142 dns_rdatatype_t covers);
143 isc_boolean_t (*issecure)(dns_db_t *db);
144 unsigned int (*nodecount)(dns_db_t *db);
145 isc_boolean_t (*ispersistent)(dns_db_t *db);
146 void (*overmem)(dns_db_t *db, isc_boolean_t overmem);
147 void (*settask)(dns_db_t *db, isc_task_t *);
148 isc_result_t (*getoriginnode)(dns_db_t *db, dns_dbnode_t **nodep);
149 void (*transfernode)(dns_db_t *db, dns_dbnode_t **sourcep,
150 dns_dbnode_t **targetp);
151 dns_stats_t *(*getrrsetstats)(dns_db_t *db);
155 (*dns_dbcreatefunc_t)(isc_mem_t *mctx, dns_name_t *name,
156 dns_dbtype_t type, dns_rdataclass_t rdclass,
157 unsigned int argc, char *argv[], void *driverarg,
160 #define DNS_DB_MAGIC ISC_MAGIC('D','N','S','D')
161 #define DNS_DB_VALID(db) ISC_MAGIC_VALID(db, DNS_DB_MAGIC)
164 * This structure is actually just the common prefix of a DNS db
165 * implementation's version of a dns_db_t.
167 * Direct use of this structure by clients is forbidden. DB implementations
168 * may change the structure. 'magic' must be DNS_DB_MAGIC for any of the
169 * dns_db_ routines to work. DB implementations must maintain all DB
174 unsigned int impmagic;
175 dns_dbmethods_t * methods;
176 isc_uint16_t attributes;
177 dns_rdataclass_t rdclass;
179 isc_ondestroy_t ondest;
183 #define DNS_DBATTR_CACHE 0x01
184 #define DNS_DBATTR_STUB 0x02
188 * Options that can be specified for dns_db_find().
190 #define DNS_DBFIND_GLUEOK 0x0001
191 #define DNS_DBFIND_VALIDATEGLUE 0x0002
192 #define DNS_DBFIND_NOWILD 0x0004
193 #define DNS_DBFIND_PENDINGOK 0x0008
194 #define DNS_DBFIND_NOEXACT 0x0010
195 #define DNS_DBFIND_FORCENSEC 0x0020
196 #define DNS_DBFIND_COVERINGNSEC 0x0040
197 #define DNS_DBFIND_ADDITIONALOK 0x0100
202 * Options that can be specified for dns_db_addrdataset().
204 #define DNS_DBADD_MERGE 0x01
205 #define DNS_DBADD_FORCE 0x02
206 #define DNS_DBADD_EXACT 0x04
207 #define DNS_DBADD_EXACTTTL 0x08
211 * Options that can be specified for dns_db_subtractrdataset().
213 #define DNS_DBSUB_EXACT 0x01
224 dns_db_create(isc_mem_t *mctx, const char *db_type, dns_name_t *origin,
225 dns_dbtype_t type, dns_rdataclass_t rdclass,
226 unsigned int argc, char *argv[], dns_db_t **dbp);
228 * Create a new database using implementation 'db_type'.
231 * \li All names in the database must be subdomains of 'origin' and in class
232 * 'rdclass'. The database makes its own copy of the origin, so the
233 * caller may do whatever they like with 'origin' and its storage once the
236 * \li DB implementation-specific parameters are passed using argc and argv.
240 * \li dbp != NULL and *dbp == NULL
242 * \li 'origin' is a valid absolute domain name.
244 * \li mctx is a valid memory context
248 * \li A copy of 'origin' has been made for the databases use, and the
249 * caller is free to do whatever they want with the name and storage
250 * associated with 'origin'.
255 * \li #ISC_R_NOMEMORY
256 * \li #ISC_R_NOTFOUND db_type not found
258 * \li Many other errors are possible, depending on what db_type was
263 dns_db_attach(dns_db_t *source, dns_db_t **targetp);
265 * Attach *targetp to source.
269 * \li 'source' is a valid database.
271 * \li 'targetp' points to a NULL dns_db_t *.
275 * \li *targetp is attached to source.
279 dns_db_detach(dns_db_t **dbp);
281 * Detach *dbp from its database.
285 * \li 'dbp' points to a valid database.
291 * \li If '*dbp' is the last reference to the database,
292 * all resources used by the database will be freed
296 dns_db_ondestroy(dns_db_t *db, isc_task_t *task, isc_event_t **eventp);
298 * Causes 'eventp' to be sent to be sent to 'task' when the database is
301 * Note; ownership of the eventp is taken from the caller (and *eventp is
302 * set to NULL). The sender field of the event is set to 'db' before it is
307 dns_db_iscache(dns_db_t *db);
309 * Does 'db' have cache semantics?
313 * \li 'db' is a valid database.
316 * \li #ISC_TRUE 'db' has cache semantics
317 * \li #ISC_FALSE otherwise
321 dns_db_iszone(dns_db_t *db);
323 * Does 'db' have zone semantics?
327 * \li 'db' is a valid database.
330 * \li #ISC_TRUE 'db' has zone semantics
331 * \li #ISC_FALSE otherwise
335 dns_db_isstub(dns_db_t *db);
337 * Does 'db' have stub semantics?
341 * \li 'db' is a valid database.
344 * \li #ISC_TRUE 'db' has zone semantics
345 * \li #ISC_FALSE otherwise
349 dns_db_issecure(dns_db_t *db);
355 * \li 'db' is a valid database with zone semantics.
358 * \li #ISC_TRUE 'db' is secure.
359 * \li #ISC_FALSE 'db' is not secure.
363 dns_db_origin(dns_db_t *db);
365 * The origin of the database.
367 * Note: caller must not try to change this name.
371 * \li 'db' is a valid database.
375 * \li The origin of the database.
379 dns_db_class(dns_db_t *db);
381 * The class of the database.
385 * \li 'db' is a valid database.
389 * \li The class of the database.
393 dns_db_beginload(dns_db_t *db, dns_addrdatasetfunc_t *addp,
394 dns_dbload_t **dbloadp);
396 * Begin loading 'db'.
400 * \li 'db' is a valid database.
402 * \li This is the first attempt to load 'db'.
404 * \li addp != NULL && *addp == NULL
406 * \li dbloadp != NULL && *dbloadp == NULL
410 * \li On success, *addp will be a valid dns_addrdatasetfunc_t suitable
411 * for loading 'db'. *dbloadp will be a valid DB load context which
412 * should be used as 'arg' when *addp is called.
417 * \li #ISC_R_NOMEMORY
419 * \li Other results are possible, depending upon the database
420 * implementation used, syntax errors in the master file, etc.
424 dns_db_endload(dns_db_t *db, dns_dbload_t **dbloadp);
426 * Finish loading 'db'.
430 * \li 'db' is a valid database that is being loaded.
432 * \li dbloadp != NULL and *dbloadp is a valid database load context.
436 * \li *dbloadp == NULL
441 * \li #ISC_R_NOMEMORY
443 * \li Other results are possible, depending upon the database
444 * implementation used, syntax errors in the master file, etc.
448 dns_db_load(dns_db_t *db, const char *filename);
451 dns_db_load2(dns_db_t *db, const char *filename, dns_masterformat_t format);
453 * Load master file 'filename' into 'db'.
456 * \li This routine is equivalent to calling
459 * dns_db_beginload();
460 * dns_master_loadfile();
466 * \li 'db' is a valid database.
468 * \li This is the first attempt to load 'db'.
473 * \li #ISC_R_NOMEMORY
475 * \li Other results are possible, depending upon the database
476 * implementation used, syntax errors in the master file, etc.
480 dns_db_dump(dns_db_t *db, dns_dbversion_t *version, const char *filename);
483 dns_db_dump2(dns_db_t *db, dns_dbversion_t *version, const char *filename,
484 dns_masterformat_t masterformat);
486 * Dump version 'version' of 'db' to master file 'filename'.
490 * \li 'db' is a valid database.
492 * \li 'version' is a valid version.
497 * \li #ISC_R_NOMEMORY
499 * \li Other results are possible, depending upon the database
500 * implementation used, OS file errors, etc.
508 dns_db_currentversion(dns_db_t *db, dns_dbversion_t **versionp);
510 * Open the current version for reading.
514 * \li 'db' is a valid database with zone semantics.
516 * \li versionp != NULL && *verisonp == NULL
520 * \li On success, '*versionp' is attached to the current version.
525 dns_db_newversion(dns_db_t *db, dns_dbversion_t **versionp);
527 * Open a new version for reading and writing.
531 * \li 'db' is a valid database with zone semantics.
533 * \li versionp != NULL && *verisonp == NULL
537 * \li On success, '*versionp' is attached to the current version.
542 * \li #ISC_R_NOMEMORY
544 * \li Other results are possible, depending upon the database
545 * implementation used.
549 dns_db_attachversion(dns_db_t *db, dns_dbversion_t *source,
550 dns_dbversion_t **targetp);
552 * Attach '*targetp' to 'source'.
556 * \li 'db' is a valid database with zone semantics.
558 * \li source is a valid open version
560 * \li targetp != NULL && *targetp == NULL
564 * \li '*targetp' is attached to source.
568 dns_db_closeversion(dns_db_t *db, dns_dbversion_t **versionp,
569 isc_boolean_t commit);
571 * Close version '*versionp'.
573 * Note: if '*versionp' is a read-write version and 'commit' is ISC_TRUE,
574 * then all changes made in the version will take effect, otherwise they
575 * will be rolled back. The value if 'commit' is ignored for read-only
580 * \li 'db' is a valid database with zone semantics.
582 * \li '*versionp' refers to a valid version.
584 * \li If committing a writable version, then there must be no other
585 * outstanding references to the version (e.g. an active rdataset
590 * \li *versionp == NULL
592 * \li If *versionp is a read-write version, and commit is ISC_TRUE, then
593 * the version will become the current version. If !commit, then all
594 * changes made in the version will be undone, and the version will
595 * not become the current version.
603 dns_db_findnode(dns_db_t *db, dns_name_t *name, isc_boolean_t create,
604 dns_dbnode_t **nodep);
606 * Find the node with name 'name'.
609 * \li If 'create' is ISC_TRUE and no node with name 'name' exists, then
610 * such a node will be created.
612 * \li This routine is for finding or creating a node with the specified
613 * name. There are no partial matches. It is not suitable for use
614 * in building responses to ordinary DNS queries; clients which wish
615 * to do that should use dns_db_find() instead.
619 * \li 'db' is a valid database.
621 * \li 'name' is a valid, non-empty, absolute name.
623 * \li nodep != NULL && *nodep == NULL
627 * \li On success, *nodep is attached to the node with name 'name'.
632 * \li #ISC_R_NOTFOUND If !create and name not found.
633 * \li #ISC_R_NOMEMORY Can only happen if create is ISC_TRUE.
635 * \li Other results are possible, depending upon the database
636 * implementation used.
640 dns_db_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version,
641 dns_rdatatype_t type, unsigned int options, isc_stdtime_t now,
642 dns_dbnode_t **nodep, dns_name_t *foundname,
643 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
645 * Find the best match for 'name' and 'type' in version 'version' of 'db'.
649 * \li If type == dns_rdataset_any, then rdataset will not be bound.
651 * \li If 'options' does not have #DNS_DBFIND_GLUEOK set, then no glue will
652 * be returned. For zone databases, glue is as defined in RFC2181.
653 * For cache databases, glue is any rdataset with a trust of
656 * \li If 'options' does not have #DNS_DBFIND_PENDINGOK set, then no
657 * pending data will be returned. This option is only meaningful for
660 * \li If the #DNS_DBFIND_NOWILD option is set, then wildcard matching will
661 * be disabled. This option is only meaningful for zone databases.
663 * \li If the #DNS_DBFIND_FORCENSEC option is set, the database is assumed to
664 * have NSEC records, and these will be returned when appropriate. This
665 * is only necessary when querying a database that was not secure
668 * \li If the DNS_DBFIND_COVERINGNSEC option is set, then look for a
669 * NSEC record that potentially covers 'name' if a answer cannot
670 * be found. Note the returned NSEC needs to be checked to ensure
671 * that it is correct. This only affects answers returned from the
674 * \li To respond to a query for SIG records, the caller should create a
675 * rdataset iterator and extract the signatures from each rdataset.
677 * \li Making queries of type ANY with #DNS_DBFIND_GLUEOK is not recommended,
678 * because the burden of determining whether a given rdataset is valid
679 * glue or not falls upon the caller.
681 * \li The 'now' field is ignored if 'db' is a zone database. If 'db' is a
682 * cache database, an rdataset will not be found unless it expires after
683 * 'now'. Any ANY query will not match unless at least one rdataset at
684 * the node expires after 'now'. If 'now' is zero, then the current time
689 * \li 'db' is a valid database.
691 * \li 'type' is not SIG, or a meta-RR type other than 'ANY' (e.g. 'OPT').
693 * \li 'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
695 * \li 'foundname' is a valid name with a dedicated buffer.
697 * \li 'rdataset' is NULL, or is a valid unassociated rdataset.
700 * on a non-error completion:
702 * \li If nodep != NULL, then it is bound to the found node.
704 * \li If foundname != NULL, then it contains the full name of the
707 * \li If rdataset != NULL and type != dns_rdatatype_any, then
708 * rdataset is bound to the found rdataset.
710 * Non-error results are:
712 * \li #ISC_R_SUCCESS The desired node and type were
715 * \li #DNS_R_WILDCARD The desired node and type were
716 * found after performing
717 * wildcard matching. This is
718 * only returned if the
719 * #DNS_DBFIND_INDICATEWILD
720 * option is set; otherwise
721 * #ISC_R_SUCCESS is returned.
723 * \li #DNS_R_GLUE The desired node and type were
724 * found, but are glue. This
725 * result can only occur if
726 * the DNS_DBFIND_GLUEOK option
727 * is set. This result can only
728 * occur if 'db' is a zone
729 * database. If type ==
730 * dns_rdatatype_any, then the
731 * node returned may contain, or
732 * consist entirely of invalid
733 * glue (i.e. data occluded by a
734 * zone cut). The caller must
735 * take care not to return invalid
738 * \li #DNS_R_DELEGATION The data requested is beneath
739 * a zone cut. node, foundname,
740 * and rdataset reference the
741 * NS RRset of the zone cut.
742 * If 'db' is a cache database,
743 * then this is the deepest known
746 * \li #DNS_R_ZONECUT type == dns_rdatatype_any, and
747 * the desired node is a zonecut.
748 * The caller must take care not
749 * to return inappropriate glue
750 * to a client. This result can
751 * only occur if 'db' is a zone
752 * database and DNS_DBFIND_GLUEOK
755 * \li #DNS_R_DNAME The data requested is beneath
756 * a DNAME. node, foundname,
757 * and rdataset reference the
760 * \li #DNS_R_CNAME The rdataset requested was not
761 * found, but there is a CNAME
762 * at the desired name. node,
763 * foundname, and rdataset
764 * reference the CNAME RRset.
766 * \li #DNS_R_NXDOMAIN The desired name does not
769 * \li #DNS_R_NXRRSET The desired name exists, but
770 * the desired type does not.
772 * \li #ISC_R_NOTFOUND The desired name does not
773 * exist, and no delegation could
774 * be found. This result can only
775 * occur if 'db' is a cache
776 * database. The caller should
777 * use its nameserver(s) of last
778 * resort (e.g. root hints).
780 * \li #DNS_R_NCACHENXDOMAIN The desired name does not
781 * exist. 'node' is bound to the
782 * cache node with the desired
783 * name, and 'rdataset' contains
784 * the negative caching proof.
786 * \li #DNS_R_NCACHENXRRSET The desired type does not
787 * exist. 'node' is bound to the
788 * cache node with the desired
789 * name, and 'rdataset' contains
790 * the negative caching proof.
792 * \li #DNS_R_EMPTYNAME The name exists but there is
793 * no data at the name.
795 * \li #DNS_R_COVERINGNSEC The returned data is a NSEC
796 * that potentially covers 'name'.
800 * \li #ISC_R_NOMEMORY
802 * \li #DNS_R_BADDB Data that is required to be
803 * present in the DB, e.g. an NSEC
804 * record in a secure zone, is not
807 * \li Other results are possible, and should all be treated as
812 dns_db_findzonecut(dns_db_t *db, dns_name_t *name,
813 unsigned int options, isc_stdtime_t now,
814 dns_dbnode_t **nodep, dns_name_t *foundname,
815 dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
817 * Find the deepest known zonecut which encloses 'name' in 'db'.
821 * \li If the #DNS_DBFIND_NOEXACT option is set, then the zonecut returned
822 * (if any) will be the deepest known ancestor of 'name'.
824 * \li If 'now' is zero, then the current time will be used.
828 * \li 'db' is a valid database with cache semantics.
830 * \li 'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
832 * \li 'foundname' is a valid name with a dedicated buffer.
834 * \li 'rdataset' is NULL, or is a valid unassociated rdataset.
836 * Ensures, on a non-error completion:
838 * \li If nodep != NULL, then it is bound to the found node.
840 * \li If foundname != NULL, then it contains the full name of the
843 * \li If rdataset != NULL and type != dns_rdatatype_any, then
844 * rdataset is bound to the found rdataset.
846 * Non-error results are:
850 * \li #ISC_R_NOTFOUND
852 * \li Other results are possible, and should all be treated as
857 dns_db_attachnode(dns_db_t *db, dns_dbnode_t *source, dns_dbnode_t **targetp);
859 * Attach *targetp to source.
863 * \li 'db' is a valid database.
865 * \li 'source' is a valid node.
867 * \li 'targetp' points to a NULL dns_dbnode_t *.
871 * \li *targetp is attached to source.
875 dns_db_detachnode(dns_db_t *db, dns_dbnode_t **nodep);
877 * Detach *nodep from its node.
881 * \li 'db' is a valid database.
883 * \li 'nodep' points to a valid node.
887 * \li *nodep is NULL.
891 dns_db_transfernode(dns_db_t *db, dns_dbnode_t **sourcep,
892 dns_dbnode_t **targetp);
894 * Transfer a node between pointer.
896 * This is equivalent to calling dns_db_attachnode() then dns_db_detachnode().
900 * \li 'db' is a valid database.
902 * \li '*sourcep' is a valid node.
904 * \li 'targetp' points to a NULL dns_dbnode_t *.
908 * \li '*sourcep' is NULL.
912 dns_db_expirenode(dns_db_t *db, dns_dbnode_t *node, isc_stdtime_t now);
914 * Mark as stale all records at 'node' which expire at or before 'now'.
916 * Note: if 'now' is zero, then the current time will be used.
920 * \li 'db' is a valid cache database.
922 * \li 'node' is a valid node.
926 dns_db_printnode(dns_db_t *db, dns_dbnode_t *node, FILE *out);
928 * Print a textual representation of the contents of the node to
931 * Note: this function is intended for debugging, not general use.
935 * \li 'db' is a valid database.
937 * \li 'node' is a valid node.
941 *** DB Iterator Creation
945 dns_db_createiterator(dns_db_t *db, isc_boolean_t relative_names,
946 dns_dbiterator_t **iteratorp);
948 * Create an iterator for version 'version' of 'db'.
952 * \li If 'relative_names' is ISC_TRUE, then node names returned by the
953 * iterator will be relative to the iterator's current origin. If
954 * #ISC_FALSE, then the node names will be absolute.
958 * \li 'db' is a valid database.
960 * \li iteratorp != NULL && *iteratorp == NULL
964 * \li On success, *iteratorp will be a valid database iterator.
969 * \li #ISC_R_NOMEMORY
977 * XXXRTH Should we check for glue and pending data in dns_db_findrdataset()?
981 dns_db_findrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
982 dns_rdatatype_t type, dns_rdatatype_t covers,
983 isc_stdtime_t now, dns_rdataset_t *rdataset,
984 dns_rdataset_t *sigrdataset);
986 * Search for an rdataset of type 'type' at 'node' that are in version
987 * 'version' of 'db'. If found, make 'rdataset' refer to it.
991 * \li If 'version' is NULL, then the current version will be used.
993 * \li Care must be used when using this routine to build a DNS response:
994 * 'node' should have been found with dns_db_find(), not
995 * dns_db_findnode(). No glue checking is done. No checking for
996 * pending data is done.
998 * \li The 'now' field is ignored if 'db' is a zone database. If 'db' is a
999 * cache database, an rdataset will not be found unless it expires after
1000 * 'now'. If 'now' is zero, then the current time will be used.
1004 * \li 'db' is a valid database.
1006 * \li 'node' is a valid node.
1008 * \li 'rdataset' is a valid, disassociated rdataset.
1010 * \li 'sigrdataset' is a valid, disassociated rdataset, or it is NULL.
1012 * \li If 'covers' != 0, 'type' must be SIG.
1014 * \li 'type' is not a meta-RR type such as 'ANY' or 'OPT'.
1018 * \li On success, 'rdataset' is associated with the found rdataset.
1022 * \li #ISC_R_SUCCESS
1023 * \li #ISC_R_NOTFOUND
1025 * \li Other results are possible, depending upon the database
1026 * implementation used.
1030 dns_db_allrdatasets(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
1031 isc_stdtime_t now, dns_rdatasetiter_t **iteratorp);
1033 * Make '*iteratorp' an rdataset iterator for all rdatasets at 'node' in
1034 * version 'version' of 'db'.
1038 * \li If 'version' is NULL, then the current version will be used.
1040 * \li The 'now' field is ignored if 'db' is a zone database. If 'db' is a
1041 * cache database, an rdataset will not be found unless it expires after
1042 * 'now'. Any ANY query will not match unless at least one rdataset at
1043 * the node expires after 'now'. If 'now' is zero, then the current time
1048 * \li 'db' is a valid database.
1050 * \li 'node' is a valid node.
1052 * \li iteratorp != NULL && *iteratorp == NULL
1056 * \li On success, '*iteratorp' is a valid rdataset iterator.
1060 * \li #ISC_R_SUCCESS
1061 * \li #ISC_R_NOTFOUND
1063 * \li Other results are possible, depending upon the database
1064 * implementation used.
1068 dns_db_addrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
1069 isc_stdtime_t now, dns_rdataset_t *rdataset,
1070 unsigned int options, dns_rdataset_t *addedrdataset);
1072 * Add 'rdataset' to 'node' in version 'version' of 'db'.
1076 * \li If the database has zone semantics, the #DNS_DBADD_MERGE option is set,
1077 * and an rdataset of the same type as 'rdataset' already exists at
1078 * 'node' then the contents of 'rdataset' will be merged with the existing
1079 * rdataset. If the option is not set, then rdataset will replace any
1080 * existing rdataset of the same type. If not merging and the
1081 * #DNS_DBADD_FORCE option is set, then the data will update the database
1082 * without regard to trust levels. If not forcing the data, then the
1083 * rdataset will only be added if its trust level is >= the trust level of
1084 * any existing rdataset. Forcing is only meaningful for cache databases.
1085 * If #DNS_DBADD_EXACT is set then there must be no rdata in common between
1086 * the old and new rdata sets. If #DNS_DBADD_EXACTTTL is set then both
1087 * the old and new rdata sets must have the same ttl.
1089 * \li The 'now' field is ignored if 'db' is a zone database. If 'db' is
1090 * a cache database, then the added rdataset will expire no later than
1091 * now + rdataset->ttl.
1093 * \li If 'addedrdataset' is not NULL, then it will be attached to the
1094 * resulting new rdataset in the database, or to the existing data if
1095 * the existing data was better.
1099 * \li 'db' is a valid database.
1101 * \li 'node' is a valid node.
1103 * \li 'rdataset' is a valid, associated rdataset with the same class
1106 * \li 'addedrdataset' is NULL, or a valid, unassociated rdataset.
1108 * \li The database has zone semantics and 'version' is a valid
1109 * read-write version, or the database has cache semantics
1110 * and version is NULL.
1112 * \li If the database has cache semantics, the #DNS_DBADD_MERGE option must
1117 * \li #ISC_R_SUCCESS
1118 * \li #DNS_R_UNCHANGED The operation did not change anything.
1119 * \li #ISC_R_NOMEMORY
1120 * \li #DNS_R_NOTEXACT
1122 * \li Other results are possible, depending upon the database
1123 * implementation used.
1127 dns_db_subtractrdataset(dns_db_t *db, dns_dbnode_t *node,
1128 dns_dbversion_t *version, dns_rdataset_t *rdataset,
1129 unsigned int options, dns_rdataset_t *newrdataset);
1131 * Remove any rdata in 'rdataset' from 'node' in version 'version' of
1136 * \li If 'newrdataset' is not NULL, then it will be attached to the
1137 * resulting new rdataset in the database, unless the rdataset has
1138 * become nonexistent. If DNS_DBSUB_EXACT is set then all elements
1139 * of 'rdataset' must exist at 'node'.
1143 * \li 'db' is a valid database.
1145 * \li 'node' is a valid node.
1147 * \li 'rdataset' is a valid, associated rdataset with the same class
1150 * \li 'newrdataset' is NULL, or a valid, unassociated rdataset.
1152 * \li The database has zone semantics and 'version' is a valid
1153 * read-write version.
1157 * \li #ISC_R_SUCCESS
1158 * \li #DNS_R_UNCHANGED The operation did not change anything.
1159 * \li #DNS_R_NXRRSET All rdata of the same type as those
1160 * in 'rdataset' have been deleted.
1161 * \li #DNS_R_NOTEXACT Some part of 'rdataset' did not
1162 * exist and DNS_DBSUB_EXACT was set.
1164 * \li Other results are possible, depending upon the database
1165 * implementation used.
1169 dns_db_deleterdataset(dns_db_t *db, dns_dbnode_t *node,
1170 dns_dbversion_t *version, dns_rdatatype_t type,
1171 dns_rdatatype_t covers);
1173 * Make it so that no rdataset of type 'type' exists at 'node' in version
1174 * version 'version' of 'db'.
1178 * \li If 'type' is dns_rdatatype_any, then no rdatasets will exist in
1179 * 'version' (provided that the dns_db_deleterdataset() isn't followed
1180 * by one or more dns_db_addrdataset() calls).
1184 * \li 'db' is a valid database.
1186 * \li 'node' is a valid node.
1188 * \li The database has zone semantics and 'version' is a valid
1189 * read-write version, or the database has cache semantics
1190 * and version is NULL.
1192 * \li 'type' is not a meta-RR type, except for dns_rdatatype_any, which is
1195 * \li If 'covers' != 0, 'type' must be SIG.
1199 * \li #ISC_R_SUCCESS
1200 * \li #DNS_R_UNCHANGED No rdatasets of 'type' existed before
1201 * the operation was attempted.
1203 * \li Other results are possible, depending upon the database
1204 * implementation used.
1208 dns_db_getsoaserial(dns_db_t *db, dns_dbversion_t *ver, isc_uint32_t *serialp);
1210 * Get the current SOA serial number from a zone database.
1213 * \li 'db' is a valid database with zone semantics.
1214 * \li 'ver' is a valid version.
1218 dns_db_overmem(dns_db_t *db, isc_boolean_t overmem);
1220 * Enable / disable aggressive cache cleaning.
1224 dns_db_nodecount(dns_db_t *db);
1226 * Count the number of nodes in 'db'.
1230 * \li 'db' is a valid database.
1233 * \li The number of nodes in the database
1237 dns_db_settask(dns_db_t *db, isc_task_t *task);
1239 * If task is set then the final detach maybe performed asynchronously.
1242 * \li 'db' is a valid database.
1243 * \li 'task' to be valid or NULL.
1247 dns_db_ispersistent(dns_db_t *db);
1249 * Is 'db' persistent? A persistent database does not need to be loaded
1250 * from disk or written to disk.
1254 * \li 'db' is a valid database.
1257 * \li #ISC_TRUE 'db' is persistent.
1258 * \li #ISC_FALSE 'db' is not persistent.
1262 dns_db_register(const char *name, dns_dbcreatefunc_t create, void *driverarg,
1263 isc_mem_t *mctx, dns_dbimplementation_t **dbimp);
1266 * Register a new database implementation and add it to the list of
1267 * supported implementations.
1271 * \li 'name' is not NULL
1272 * \li 'order' is a valid function pointer
1273 * \li 'mctx' is a valid memory context
1274 * \li dbimp != NULL && *dbimp == NULL
1277 * \li #ISC_R_SUCCESS The registration succeeded
1278 * \li #ISC_R_NOMEMORY Out of memory
1279 * \li #ISC_R_EXISTS A database implementation with the same name exists
1283 * \li *dbimp points to an opaque structure which must be passed to
1284 * dns_db_unregister().
1288 dns_db_unregister(dns_dbimplementation_t **dbimp);
1290 * Remove a database implementation from the list of supported
1291 * implementations. No databases of this type can be active when this
1295 * \li dbimp != NULL && *dbimp == NULL
1299 * \li Any memory allocated in *dbimp will be freed.
1303 dns_db_getoriginnode(dns_db_t *db, dns_dbnode_t **nodep);
1305 * Get the origin DB node corresponding to the DB's zone. This function
1306 * should typically succeed unless the underlying DB implementation doesn't
1307 * support the feature.
1311 * \li 'db' is a valid zone database.
1312 * \li 'nodep' != NULL && '*nodep' == NULL
1315 * \li On success, '*nodep' will point to the DB node of the zone's origin.
1318 * \li #ISC_R_SUCCESS
1319 * \li #ISC_R_NOTFOUND - the DB implementation does not support this feature.
1323 dns_db_getrrsetstats(dns_db_t *db);
1325 * Get statistics information counting RRsets stored in the DB, when available.
1326 * The statistics may not be available depending on the DB implementation.
1330 * \li 'db' is a valid database (zone or cache).
1333 * \li when available, a pointer to a statistics object created by
1334 * dns_rdatasetstats_create(); otherwise NULL.
1339 #endif /* DNS_DB_H */