"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.16.7/lib/dns/include/dns/db.h" (4 Sep 2020, 47271 Bytes) of package /linux/misc/dns/bind9/9.16.7/bind-9.16.7.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "db.h" see the Fossies "Dox" file reference documentation and the last Fossies "Diffs" side-by-side code changes report: 9.17.3_vs_9.17.4.

    1 /*
    2  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
    3  *
    4  * This Source Code Form is subject to the terms of the Mozilla Public
    5  * License, v. 2.0. If a copy of the MPL was not distributed with this
    6  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
    7  *
    8  * See the COPYRIGHT file distributed with this work for additional
    9  * information regarding copyright ownership.
   10  */
   11 
   12 #ifndef DNS_DB_H
   13 #define DNS_DB_H 1
   14 
   15 /*****
   16 ***** Module Info
   17 *****/
   18 
   19 /*! \file dns/db.h
   20  * \brief
   21  * The DNS DB interface allows named rdatasets to be stored and retrieved.
   22  *
   23  * The dns_db_t type is like a "virtual class".  To actually use
   24  * DBs, an implementation of the class is required.
   25  *
   26  * XXX more XXX
   27  *
   28  * MP:
   29  * \li  The module ensures appropriate synchronization of data structures it
   30  *  creates and manipulates.
   31  *
   32  * Reliability:
   33  * \li  No anticipated impact.
   34  *
   35  * Resources:
   36  * \li  TBS
   37  *
   38  * Security:
   39  * \li  No anticipated impact.
   40  *
   41  * Standards:
   42  * \li  None.
   43  */
   44 
   45 /*****
   46 ***** Imports
   47 *****/
   48 
   49 #include <inttypes.h>
   50 #include <stdbool.h>
   51 
   52 #include <isc/deprecated.h>
   53 #include <isc/lang.h>
   54 #include <isc/magic.h>
   55 #include <isc/stats.h>
   56 #include <isc/stdtime.h>
   57 
   58 #include <dns/clientinfo.h>
   59 #include <dns/fixedname.h>
   60 #include <dns/name.h>
   61 #include <dns/rdata.h>
   62 #include <dns/rdataset.h>
   63 #include <dns/types.h>
   64 
   65 ISC_LANG_BEGINDECLS
   66 
   67 /*****
   68 ***** Types
   69 *****/
   70 
   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,
   75                   dns_rdatacallbacks_t *callbacks);
   76     isc_result_t (*endload)(dns_db_t *db, dns_rdatacallbacks_t *callbacks);
   77     isc_result_t (*serialize)(dns_db_t *db, dns_dbversion_t *version,
   78                   FILE *file);
   79     isc_result_t (*dump)(dns_db_t *db, dns_dbversion_t *version,
   80                  const char *   filename,
   81                  dns_masterformat_t masterformat);
   82     void (*currentversion)(dns_db_t *db, dns_dbversion_t **versionp);
   83     isc_result_t (*newversion)(dns_db_t *db, 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, dns_dbversion_t **versionp,
   87                  bool commit);
   88     isc_result_t (*findnode)(dns_db_t *db, const dns_name_t *name,
   89                  bool create, dns_dbnode_t **nodep);
   90     isc_result_t (*find)(dns_db_t *db, const dns_name_t *name,
   91                  dns_dbversion_t *version, dns_rdatatype_t type,
   92                  unsigned int options, isc_stdtime_t now,
   93                  dns_dbnode_t **nodep, dns_name_t *foundname,
   94                  dns_rdataset_t *rdataset,
   95                  dns_rdataset_t *sigrdataset);
   96     isc_result_t (*findzonecut)(dns_db_t *db, const dns_name_t *name,
   97                     unsigned int options, isc_stdtime_t now,
   98                     dns_dbnode_t **nodep, dns_name_t *foundname,
   99                     dns_name_t *    dcname,
  100                     dns_rdataset_t *rdataset,
  101                     dns_rdataset_t *sigrdataset);
  102     void (*attachnode)(dns_db_t *db, dns_dbnode_t *source,
  103                dns_dbnode_t **targetp);
  104     void (*detachnode)(dns_db_t *db, dns_dbnode_t **targetp);
  105     isc_result_t (*expirenode)(dns_db_t *db, dns_dbnode_t *node,
  106                    isc_stdtime_t now);
  107     void (*printnode)(dns_db_t *db, dns_dbnode_t *node, FILE *out);
  108     isc_result_t (*createiterator)(dns_db_t *db, unsigned int options,
  109                        dns_dbiterator_t **iteratorp);
  110     isc_result_t (*findrdataset)(dns_db_t *db, dns_dbnode_t *node,
  111                      dns_dbversion_t *version,
  112                      dns_rdatatype_t  type,
  113                      dns_rdatatype_t covers, isc_stdtime_t now,
  114                      dns_rdataset_t *rdataset,
  115                      dns_rdataset_t *sigrdataset);
  116     isc_result_t (*allrdatasets)(dns_db_t *db, dns_dbnode_t *node,
  117                      dns_dbversion_t *    version,
  118                      isc_stdtime_t    now,
  119                      dns_rdatasetiter_t **iteratorp);
  120     isc_result_t (*addrdataset)(dns_db_t *db, dns_dbnode_t *node,
  121                     dns_dbversion_t *version, isc_stdtime_t now,
  122                     dns_rdataset_t *rdataset,
  123                     unsigned int    options,
  124                     dns_rdataset_t *addedrdataset);
  125     isc_result_t (*subtractrdataset)(dns_db_t *db, dns_dbnode_t *node,
  126                      dns_dbversion_t *version,
  127                      dns_rdataset_t * rdataset,
  128                      unsigned int     options,
  129                      dns_rdataset_t * newrdataset);
  130     isc_result_t (*deleterdataset)(dns_db_t *db, dns_dbnode_t *node,
  131                        dns_dbversion_t *version,
  132                        dns_rdatatype_t  type,
  133                        dns_rdatatype_t  covers);
  134     bool (*issecure)(dns_db_t *db);
  135     unsigned int (*nodecount)(dns_db_t *db);
  136     bool (*ispersistent)(dns_db_t *db);
  137     void (*overmem)(dns_db_t *db, bool overmem);
  138     void (*settask)(dns_db_t *db, isc_task_t *);
  139     isc_result_t (*getoriginnode)(dns_db_t *db, dns_dbnode_t **nodep);
  140     void (*transfernode)(dns_db_t *db, dns_dbnode_t **sourcep,
  141                  dns_dbnode_t **targetp);
  142     isc_result_t (*getnsec3parameters)(dns_db_t *       db,
  143                        dns_dbversion_t *version,
  144                        dns_hash_t *hash, uint8_t *flags,
  145                        uint16_t *     iterations,
  146                        unsigned char *salt,
  147                        size_t *   salt_len);
  148     isc_result_t (*findnsec3node)(dns_db_t *db, const dns_name_t *name,
  149                       bool create, dns_dbnode_t **nodep);
  150     isc_result_t (*setsigningtime)(dns_db_t *db, dns_rdataset_t *rdataset,
  151                        isc_stdtime_t resign);
  152     isc_result_t (*getsigningtime)(dns_db_t *db, dns_rdataset_t *rdataset,
  153                        dns_name_t *name);
  154     void (*resigned)(dns_db_t *db, dns_rdataset_t *rdataset,
  155              dns_dbversion_t *version);
  156     bool (*isdnssec)(dns_db_t *db);
  157     dns_stats_t *(*getrrsetstats)(dns_db_t *db);
  158     void (*rpz_attach)(dns_db_t *db, void *rpzs, uint8_t rpz_num);
  159     isc_result_t (*rpz_ready)(dns_db_t *db);
  160     isc_result_t (*findnodeext)(dns_db_t *db, const dns_name_t *name,
  161                     bool             create,
  162                     dns_clientinfomethods_t *methods,
  163                     dns_clientinfo_t *       clientinfo,
  164                     dns_dbnode_t **      nodep);
  165     isc_result_t (*findext)(dns_db_t *db, const dns_name_t *name,
  166                 dns_dbversion_t *version, dns_rdatatype_t type,
  167                 unsigned int options, isc_stdtime_t now,
  168                 dns_dbnode_t **nodep, dns_name_t *foundname,
  169                 dns_clientinfomethods_t *methods,
  170                 dns_clientinfo_t *   clientinfo,
  171                 dns_rdataset_t *     rdataset,
  172                 dns_rdataset_t *     sigrdataset);
  173     isc_result_t (*setcachestats)(dns_db_t *db, isc_stats_t *stats);
  174     size_t (*hashsize)(dns_db_t *db);
  175     isc_result_t (*nodefullname)(dns_db_t *db, dns_dbnode_t *node,
  176                      dns_name_t *name);
  177     isc_result_t (*getsize)(dns_db_t *db, dns_dbversion_t *version,
  178                 uint64_t *records, uint64_t *bytes);
  179     isc_result_t (*setservestalettl)(dns_db_t *db, dns_ttl_t ttl);
  180     isc_result_t (*getservestalettl)(dns_db_t *db, dns_ttl_t *ttl);
  181     isc_result_t (*setgluecachestats)(dns_db_t *db, isc_stats_t *stats);
  182     isc_result_t (*adjusthashsize)(dns_db_t *db, size_t size);
  183 } dns_dbmethods_t;
  184 
  185 typedef isc_result_t (*dns_dbcreatefunc_t)(isc_mem_t *       mctx,
  186                        const dns_name_t *name,
  187                        dns_dbtype_t      type,
  188                        dns_rdataclass_t  rdclass,
  189                        unsigned int argc, char *argv[],
  190                        void *driverarg, dns_db_t **dbp);
  191 
  192 typedef isc_result_t (*dns_dbupdate_callback_t)(dns_db_t *db, void *fn_arg);
  193 
  194 #define DNS_DB_MAGIC     ISC_MAGIC('D', 'N', 'S', 'D')
  195 #define DNS_DB_VALID(db) ISC_MAGIC_VALID(db, DNS_DB_MAGIC)
  196 
  197 /*%
  198  * This structure is actually just the common prefix of a DNS db
  199  * implementation's version of a dns_db_t.
  200  * \brief
  201  * Direct use of this structure by clients is forbidden.  DB implementations
  202  * may change the structure.  'magic' must be DNS_DB_MAGIC for any of the
  203  * dns_db_ routines to work.  DB implementations must maintain all DB
  204  * invariants.
  205  */
  206 struct dns_db {
  207     unsigned int     magic;
  208     unsigned int     impmagic;
  209     dns_dbmethods_t *methods;
  210     uint16_t     attributes;
  211     dns_rdataclass_t rdclass;
  212     dns_name_t   origin;
  213     isc_mem_t *  mctx;
  214     ISC_LIST(dns_dbonupdatelistener_t) update_listeners;
  215 };
  216 
  217 #define DNS_DBATTR_CACHE 0x01
  218 #define DNS_DBATTR_STUB  0x02
  219 
  220 struct dns_dbonupdatelistener {
  221     dns_dbupdate_callback_t onupdate;
  222     void *          onupdate_arg;
  223     ISC_LINK(dns_dbonupdatelistener_t) link;
  224 };
  225 
  226 /*@{*/
  227 /*%
  228  * Options that can be specified for dns_db_find().
  229  */
  230 #define DNS_DBFIND_GLUEOK   0x0001
  231 #define DNS_DBFIND_VALIDATEGLUE 0x0002
  232 #define DNS_DBFIND_NOWILD   0x0004
  233 #define DNS_DBFIND_PENDINGOK    0x0008
  234 #define DNS_DBFIND_NOEXACT  0x0010
  235 #define DNS_DBFIND_FORCENSEC    0x0020
  236 #define DNS_DBFIND_COVERINGNSEC 0x0040
  237 #define DNS_DBFIND_FORCENSEC3   0x0080
  238 #define DNS_DBFIND_ADDITIONALOK 0x0100
  239 #define DNS_DBFIND_NOZONECUT    0x0200
  240 #define DNS_DBFIND_STALEOK  0x0400
  241 /*@}*/
  242 
  243 /*@{*/
  244 /*%
  245  * Options that can be specified for dns_db_addrdataset().
  246  */
  247 #define DNS_DBADD_MERGE    0x01
  248 #define DNS_DBADD_FORCE    0x02
  249 #define DNS_DBADD_EXACT    0x04
  250 #define DNS_DBADD_EXACTTTL 0x08
  251 #define DNS_DBADD_PREFETCH 0x10
  252 /*@}*/
  253 
  254 /*%
  255  * Options that can be specified for dns_db_subtractrdataset().
  256  */
  257 #define DNS_DBSUB_EXACT   0x01
  258 #define DNS_DBSUB_WANTOLD 0x02
  259 
  260 /*@{*/
  261 /*%
  262  * Iterator options
  263  */
  264 #define DNS_DB_RELATIVENAMES 0x1
  265 #define DNS_DB_NSEC3ONLY     0x2
  266 #define DNS_DB_NONSEC3       0x4
  267 /*@}*/
  268 
  269 /*****
  270 ***** Methods
  271 *****/
  272 
  273 /***
  274  *** Basic DB Methods
  275  ***/
  276 
  277 isc_result_t
  278 dns_db_create(isc_mem_t *mctx, const char *db_type, const dns_name_t *origin,
  279           dns_dbtype_t type, dns_rdataclass_t rdclass, unsigned int argc,
  280           char *argv[], dns_db_t **dbp);
  281 /*%<
  282  * Create a new database using implementation 'db_type'.
  283  *
  284  * Notes:
  285  * \li  All names in the database must be subdomains of 'origin' and in class
  286  *  'rdclass'.  The database makes its own copy of the origin, so the
  287  *  caller may do whatever they like with 'origin' and its storage once the
  288  *  call returns.
  289  *
  290  * \li  DB implementation-specific parameters are passed using argc and argv.
  291  *
  292  * Requires:
  293  *
  294  * \li  dbp != NULL and *dbp == NULL
  295  *
  296  * \li  'origin' is a valid absolute domain name.
  297  *
  298  * \li  mctx is a valid memory context
  299  *
  300  * Ensures:
  301  *
  302  * \li  A copy of 'origin' has been made for the databases use, and the
  303  *  caller is free to do whatever they want with the name and storage
  304  *  associated with 'origin'.
  305  *
  306  * Returns:
  307  *
  308  * \li  #ISC_R_SUCCESS
  309  * \li  #ISC_R_NOMEMORY
  310  * \li  #ISC_R_NOTFOUND             db_type not found
  311  *
  312  * \li  Many other errors are possible, depending on what db_type was
  313  *  specified.
  314  */
  315 
  316 void
  317 dns_db_attach(dns_db_t *source, dns_db_t **targetp);
  318 /*%<
  319  * Attach *targetp to source.
  320  *
  321  * Requires:
  322  *
  323  * \li  'source' is a valid database.
  324  *
  325  * \li  'targetp' points to a NULL dns_db_t *.
  326  *
  327  * Ensures:
  328  *
  329  * \li  *targetp is attached to source.
  330  */
  331 
  332 void
  333 dns_db_detach(dns_db_t **dbp);
  334 /*%<
  335  * Detach *dbp from its database.
  336  *
  337  * Requires:
  338  *
  339  * \li  'dbp' points to a valid database.
  340  *
  341  * Ensures:
  342  *
  343  * \li  *dbp is NULL.
  344  *
  345  * \li  If '*dbp' is the last reference to the database,
  346  *      all resources used by the database will be freed
  347  */
  348 
  349 bool
  350 dns_db_iscache(dns_db_t *db);
  351 /*%<
  352  * Does 'db' have cache semantics?
  353  *
  354  * Requires:
  355  *
  356  * \li  'db' is a valid database.
  357  *
  358  * Returns:
  359  * \li  #true   'db' has cache semantics
  360  * \li  #false  otherwise
  361  */
  362 
  363 bool
  364 dns_db_iszone(dns_db_t *db);
  365 /*%<
  366  * Does 'db' have zone semantics?
  367  *
  368  * Requires:
  369  *
  370  * \li  'db' is a valid database.
  371  *
  372  * Returns:
  373  * \li  #true   'db' has zone semantics
  374  * \li  #false  otherwise
  375  */
  376 
  377 bool
  378 dns_db_isstub(dns_db_t *db);
  379 /*%<
  380  * Does 'db' have stub semantics?
  381  *
  382  * Requires:
  383  *
  384  * \li  'db' is a valid database.
  385  *
  386  * Returns:
  387  * \li  #true   'db' has zone semantics
  388  * \li  #false  otherwise
  389  */
  390 
  391 bool
  392 dns_db_issecure(dns_db_t *db);
  393 /*%<
  394  * Is 'db' secure?
  395  *
  396  * Requires:
  397  *
  398  * \li  'db' is a valid database with zone semantics.
  399  *
  400  * Returns:
  401  * \li  #true   'db' is secure.
  402  * \li  #false  'db' is not secure.
  403  */
  404 
  405 bool
  406 dns_db_isdnssec(dns_db_t *db);
  407 /*%<
  408  * Is 'db' secure or partially secure?
  409  *
  410  * Requires:
  411  *
  412  * \li  'db' is a valid database with zone semantics.
  413  *
  414  * Returns:
  415  * \li  #true   'db' is secure or is partially.
  416  * \li  #false  'db' is not secure.
  417  */
  418 
  419 dns_name_t *
  420 dns_db_origin(dns_db_t *db);
  421 /*%<
  422  * The origin of the database.
  423  *
  424  * Note: caller must not try to change this name.
  425  *
  426  * Requires:
  427  *
  428  * \li  'db' is a valid database.
  429  *
  430  * Returns:
  431  *
  432  * \li  The origin of the database.
  433  */
  434 
  435 dns_rdataclass_t
  436 dns_db_class(dns_db_t *db);
  437 /*%<
  438  * The class of the database.
  439  *
  440  * Requires:
  441  *
  442  * \li  'db' is a valid database.
  443  *
  444  * Returns:
  445  *
  446  * \li  The class of the database.
  447  */
  448 
  449 isc_result_t
  450 dns_db_beginload(dns_db_t *db, dns_rdatacallbacks_t *callbacks);
  451 /*%<
  452  * Begin loading 'db'.
  453  *
  454  * Requires:
  455  *
  456  * \li  'db' is a valid database.
  457  *
  458  * \li  This is the first attempt to load 'db'.
  459  *
  460  * \li  'callbacks' is a pointer to an initialized dns_rdatacallbacks_t
  461  *       structure.
  462  *
  463  * Ensures:
  464  *
  465  * \li  On success, callbacks->add will be a valid dns_addrdatasetfunc_t
  466  *      suitable for loading records into 'db' from a raw or text zone
  467  *      file. callbacks->add_private will be a valid DB load context
  468  *      which should be used as 'arg' when callbacks->add is called.
  469  *      callbacks->deserialize will be a valid dns_deserialize_func_t
  470  *      suitable for loading 'db' from a map format zone file.
  471  *
  472  * Returns:
  473  *
  474  * \li  #ISC_R_SUCCESS
  475  * \li  #ISC_R_NOMEMORY
  476  *
  477  * \li  Other results are possible, depending upon the database
  478  *  implementation used, syntax errors in the master file, etc.
  479  */
  480 
  481 isc_result_t
  482 dns_db_endload(dns_db_t *db, dns_rdatacallbacks_t *callbacks);
  483 /*%<
  484  * Finish loading 'db'.
  485  *
  486  * Requires:
  487  *
  488  * \li  'db' is a valid database that is being loaded.
  489  *
  490  * \li  'callbacks' is a valid dns_rdatacallbacks_t structure.
  491  *
  492  * \li  callbacks->add_private is not NULL and is a valid database load context.
  493  *
  494  * Ensures:
  495  *
  496  * \li  'callbacks' is returned to its state prior to calling dns_db_beginload()
  497  *
  498  * Returns:
  499  *
  500  * \li  #ISC_R_SUCCESS
  501  * \li  #ISC_R_NOMEMORY
  502  *
  503  * \li  Other results are possible, depending upon the database
  504  *  implementation used, syntax errors in the master file, etc.
  505  */
  506 
  507 isc_result_t
  508 dns_db_load(dns_db_t *db, const char *filename, dns_masterformat_t format,
  509         unsigned int options);
  510 /*%<
  511  * Load master file 'filename' into 'db'.
  512  *
  513  * Notes:
  514  * \li  This routine is equivalent to calling
  515  *
  516  *\code
  517  *      dns_db_beginload();
  518  *      dns_master_loadfile();
  519  *      dns_db_endload();
  520  *\endcode
  521  *
  522  * Requires:
  523  *
  524  * \li  'db' is a valid database.
  525  *
  526  * \li  This is the first attempt to load 'db'.
  527  *
  528  * Returns:
  529  *
  530  * \li  #ISC_R_SUCCESS
  531  * \li  #ISC_R_NOMEMORY
  532  *
  533  * \li  Other results are possible, depending upon the database
  534  *  implementation used, syntax errors in the master file, etc.
  535  */
  536 
  537 isc_result_t
  538 dns_db_serialize(dns_db_t *db, dns_dbversion_t *version, FILE *rbtfile);
  539 /*%<
  540  * Dump version 'version' of 'db' to map-format file 'filename'.
  541  *
  542  * Requires:
  543  *
  544  * \li  'db' is a valid database.
  545  *
  546  * \li  'version' is a valid version.
  547  *
  548  * Returns:
  549  *
  550  * \li  #ISC_R_SUCCESS
  551  * \li  #ISC_R_NOMEMORY
  552  *
  553  * \li  Other results are possible, depending upon the database
  554  *  implementation used, OS file errors, etc.
  555  */
  556 
  557 isc_result_t
  558 dns_db_dump(dns_db_t *db, dns_dbversion_t *version, const char *filename);
  559 /*%<
  560  * Dump version 'version' of 'db' to master file 'filename'.
  561  *
  562  * Requires:
  563  *
  564  * \li  'db' is a valid database.
  565  *
  566  * \li  'version' is a valid version.
  567  *
  568  * Returns:
  569  *
  570  * \li  #ISC_R_SUCCESS
  571  * \li  #ISC_R_NOMEMORY
  572  *
  573  * \li  Other results are possible, depending upon the database
  574  *  implementation used, OS file errors, etc.
  575  */
  576 
  577 /***
  578  *** Version Methods
  579  ***/
  580 
  581 void
  582 dns_db_currentversion(dns_db_t *db, dns_dbversion_t **versionp);
  583 /*%<
  584  * Open the current version for reading.
  585  *
  586  * Requires:
  587  *
  588  * \li  'db' is a valid database with zone semantics.
  589  *
  590  * \li  versionp != NULL && *verisonp == NULL
  591  *
  592  * Ensures:
  593  *
  594  * \li  On success, '*versionp' is attached to the current version.
  595  *
  596  */
  597 
  598 isc_result_t
  599 dns_db_newversion(dns_db_t *db, dns_dbversion_t **versionp);
  600 /*%<
  601  * Open a new version for reading and writing.
  602  *
  603  * Requires:
  604  *
  605  * \li  'db' is a valid database with zone semantics.
  606  *
  607  * \li  versionp != NULL && *verisonp == NULL
  608  *
  609  * Ensures:
  610  *
  611  * \li  On success, '*versionp' is attached to the current version.
  612  *
  613  * Returns:
  614  *
  615  * \li  #ISC_R_SUCCESS
  616  * \li  #ISC_R_NOMEMORY
  617  *
  618  * \li  Other results are possible, depending upon the database
  619  *  implementation used.
  620  */
  621 
  622 void
  623 dns_db_attachversion(dns_db_t *db, dns_dbversion_t *source,
  624              dns_dbversion_t **targetp);
  625 /*%<
  626  * Attach '*targetp' to 'source'.
  627  *
  628  * Requires:
  629  *
  630  * \li  'db' is a valid database with zone semantics.
  631  *
  632  * \li  source is a valid open version
  633  *
  634  * \li  targetp != NULL && *targetp == NULL
  635  *
  636  * Ensures:
  637  *
  638  * \li  '*targetp' is attached to source.
  639  */
  640 
  641 void
  642 dns_db_closeversion(dns_db_t *db, dns_dbversion_t **versionp, bool commit);
  643 /*%<
  644  * Close version '*versionp'.
  645  *
  646  * Note: if '*versionp' is a read-write version and 'commit' is true,
  647  * then all changes made in the version will take effect, otherwise they
  648  * will be rolled back.  The value of 'commit' is ignored for read-only
  649  * versions.
  650  *
  651  * Requires:
  652  *
  653  * \li  'db' is a valid database with zone semantics.
  654  *
  655  * \li  '*versionp' refers to a valid version.
  656  *
  657  * \li  If committing a writable version, then there must be no other
  658  *  outstanding references to the version (e.g. an active rdataset
  659  *  iterator).
  660  *
  661  * Ensures:
  662  *
  663  * \li  *versionp == NULL
  664  *
  665  * \li  If *versionp is a read-write version, and commit is true, then
  666  *  the version will become the current version.  If !commit, then all
  667  *  changes made in the version will be undone, and the version will
  668  *  not become the current version.
  669  */
  670 
  671 /***
  672  *** Node Methods
  673  ***/
  674 
  675 isc_result_t
  676 dns_db_findnode(dns_db_t *db, const dns_name_t *name, bool create,
  677         dns_dbnode_t **nodep);
  678 
  679 isc_result_t
  680 dns_db_findnodeext(dns_db_t *db, const dns_name_t *name, bool create,
  681            dns_clientinfomethods_t *methods,
  682            dns_clientinfo_t *clientinfo, dns_dbnode_t **nodep);
  683 /*%<
  684  * Find the node with name 'name'.
  685  *
  686  * dns_db_findnodeext() (findnode extended) also accepts parameters
  687  * 'methods' and 'clientinfo', which, when provided, enable the database to
  688  * retrieve information about the client from the caller, and modify its
  689  * response on the basis of that information.
  690  *
  691  * Notes:
  692  * \li  If 'create' is true and no node with name 'name' exists, then
  693  *  such a node will be created.
  694  *
  695  * \li  This routine is for finding or creating a node with the specified
  696  *  name.  There are no partial matches.  It is not suitable for use
  697  *  in building responses to ordinary DNS queries; clients which wish
  698  *  to do that should use dns_db_find() instead.
  699  *
  700  * Requires:
  701  *
  702  * \li  'db' is a valid database.
  703  *
  704  * \li  'name' is a valid, non-empty, absolute name.
  705  *
  706  * \li  nodep != NULL && *nodep == NULL
  707  *
  708  * Ensures:
  709  *
  710  * \li  On success, *nodep is attached to the node with name 'name'.
  711  *
  712  * Returns:
  713  *
  714  * \li  #ISC_R_SUCCESS
  715  * \li  #ISC_R_NOTFOUND         If !create and name not found.
  716  * \li  #ISC_R_NOMEMORY         Can only happen if create is true.
  717  *
  718  * \li  Other results are possible, depending upon the database
  719  *  implementation used.
  720  */
  721 
  722 isc_result_t
  723 dns_db_find(dns_db_t *db, const dns_name_t *name, dns_dbversion_t *version,
  724         dns_rdatatype_t type, unsigned int options, isc_stdtime_t now,
  725         dns_dbnode_t **nodep, dns_name_t *foundname,
  726         dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
  727 
  728 isc_result_t
  729 dns_db_findext(dns_db_t *db, const dns_name_t *name, dns_dbversion_t *version,
  730            dns_rdatatype_t type, unsigned int options, isc_stdtime_t now,
  731            dns_dbnode_t **nodep, dns_name_t *foundname,
  732            dns_clientinfomethods_t *methods, dns_clientinfo_t *clientinfo,
  733            dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
  734 /*%<
  735  * Find the best match for 'name' and 'type' in version 'version' of 'db'.
  736  *
  737  * dns_db_findext() (find extended) also accepts parameters 'methods'
  738  * and 'clientinfo', which when provided enable the database to retrieve
  739  * information about the client from the caller, and modify its response
  740  * on the basis of this information.
  741  *
  742  * Notes:
  743  *
  744  * \li  If type == dns_rdataset_any, then rdataset will not be bound.
  745  *
  746  * \li  If 'options' does not have #DNS_DBFIND_GLUEOK set, then no glue will
  747  *  be returned.  For zone databases, glue is as defined in RFC2181.
  748  *  For cache databases, glue is any rdataset with a trust of
  749  *  dns_trust_glue.
  750  *
  751  * \li  If 'options' does not have #DNS_DBFIND_ADDITIONALOK set, then no
  752  *  additional records will be returned.  Only caches can have
  753  *  rdataset with trust dns_trust_additional.
  754  *
  755  * \li  If 'options' does not have #DNS_DBFIND_PENDINGOK set, then no
  756  *  pending data will be returned.  This option is only meaningful for
  757  *  cache databases.
  758  *
  759  * \li  If the #DNS_DBFIND_NOWILD option is set, then wildcard matching will
  760  *  be disabled.  This option is only meaningful for zone databases.
  761  *
  762  * \li  If the #DNS_DBFIND_NOZONECUT option is set, the database is
  763  *  assumed to contain no zone cuts above 'name'.  An implementation
  764  *  may therefore choose to search for a match beginning at 'name'
  765  *  rather than walking down the tree to check check for delegations.
  766  *  If #DNS_DBFIND_NOWILD is not set, wildcard matching will be
  767  *  attempted at each node starting at the direct ancestor of 'name'
  768  *  and working up to the zone origin.  This option is only meaningful
  769  *  when querying redirect zones.
  770  *
  771  * \li  If the #DNS_DBFIND_FORCENSEC option is set, the database is assumed to
  772  *  have NSEC records, and these will be returned when appropriate.  This
  773  *  is only necessary when querying a database that was not secure
  774  *  when created.
  775  *
  776  * \li  If the DNS_DBFIND_COVERINGNSEC option is set, then look for a
  777  *  NSEC record that potentially covers 'name' if a answer cannot
  778  *  be found.  Note the returned NSEC needs to be checked to ensure
  779  *  that it is correct.  This only affects answers returned from the
  780  *  cache.
  781  *
  782  * \li  If the #DNS_DBFIND_FORCENSEC3 option is set, then we are looking
  783  *  in the NSEC3 tree and not the main tree.  Without this option being
  784  *  set NSEC3 records will not be found.
  785  *
  786  * \li  To respond to a query for SIG records, the caller should create a
  787  *  rdataset iterator and extract the signatures from each rdataset.
  788  *
  789  * \li  Making queries of type ANY with #DNS_DBFIND_GLUEOK is not recommended,
  790  *  because the burden of determining whether a given rdataset is valid
  791  *  glue or not falls upon the caller.
  792  *
  793  * \li  The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
  794  *  cache database, an rdataset will not be found unless it expires after
  795  *  'now'.  Any ANY query will not match unless at least one rdataset at
  796  *  the node expires after 'now'.  If 'now' is zero, then the current time
  797  *  will be used.
  798  *
  799  * Requires:
  800  *
  801  * \li  'db' is a valid database.
  802  *
  803  * \li  'type' is not SIG, or a meta-RR type other than 'ANY' (e.g. 'OPT').
  804  *
  805  * \li  'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
  806  *
  807  * \li  'foundname' is a valid name with a dedicated buffer.
  808  *
  809  * \li  'rdataset' is NULL, or is a valid unassociated rdataset.
  810  *
  811  * Ensures,
  812  *  on a non-error completion:
  813  *
  814  *  \li If nodep != NULL, then it is bound to the found node.
  815  *
  816  *  \li If foundname != NULL, then it contains the full name of the
  817  *      found node.
  818  *
  819  *  \li If rdataset != NULL and type != dns_rdatatype_any, then
  820  *      rdataset is bound to the found rdataset.
  821  *
  822  *  Non-error results are:
  823  *
  824  *  \li #ISC_R_SUCCESS          The desired node and type were
  825  *                      found.
  826  *
  827  *  \li #DNS_R_GLUE         The desired node and type were
  828  *                      found, but are glue.  This
  829  *                      result can only occur if
  830  *                      the DNS_DBFIND_GLUEOK option
  831  *                      is set.  This result can only
  832  *                      occur if 'db' is a zone
  833  *                      database.  If type ==
  834  *                      dns_rdatatype_any, then the
  835  *                      node returned may contain, or
  836  *                      consist entirely of invalid
  837  *                      glue (i.e. data occluded by a
  838  *                      zone cut).  The caller must
  839  *                      take care not to return invalid
  840  *                      glue to a client.
  841  *
  842  *  \li #DNS_R_DELEGATION       The data requested is beneath
  843  *                      a zone cut.  node, foundname,
  844  *                      and rdataset reference the
  845  *                      NS RRset of the zone cut.
  846  *                      If 'db' is a cache database,
  847  *                      then this is the deepest known
  848  *                      delegation.
  849  *
  850  *  \li #DNS_R_ZONECUT          type == dns_rdatatype_any, and
  851  *                      the desired node is a zonecut.
  852  *                      The caller must take care not
  853  *                      to return inappropriate glue
  854  *                      to a client.  This result can
  855  *                      only occur if 'db' is a zone
  856  *                      database and DNS_DBFIND_GLUEOK
  857  *                      is set.
  858  *
  859  *  \li #DNS_R_DNAME            The data requested is beneath
  860  *                      a DNAME.  node, foundname,
  861  *                      and rdataset reference the
  862  *                      DNAME RRset.
  863  *
  864  *  \li #DNS_R_CNAME            The rdataset requested was not
  865  *                      found, but there is a CNAME
  866  *                      at the desired name.  node,
  867  *                      foundname, and rdataset
  868  *                      reference the CNAME RRset.
  869  *
  870  *  \li #DNS_R_NXDOMAIN         The desired name does not
  871  *                      exist.
  872  *
  873  *  \li #DNS_R_NXRRSET          The desired name exists, but
  874  *                      the desired type does not.
  875  *
  876  *  \li #ISC_R_NOTFOUND         The desired name does not
  877  *                      exist, and no delegation could
  878  *                      be found.  This result can only
  879  *                      occur if 'db' is a cache
  880  *                      database.  The caller should
  881  *                      use its nameserver(s) of last
  882  *                      resort (e.g. root hints).
  883  *
  884  *  \li #DNS_R_NCACHENXDOMAIN       The desired name does not
  885  *                      exist.  'node' is bound to the
  886  *                      cache node with the desired
  887  *                      name, and 'rdataset' contains
  888  *                      the negative caching proof.
  889  *
  890  *  \li #DNS_R_NCACHENXRRSET        The desired type does not
  891  *                      exist.  'node' is bound to the
  892  *                      cache node with the desired
  893  *                      name, and 'rdataset' contains
  894  *                      the negative caching proof.
  895  *
  896  *  \li #DNS_R_EMPTYNAME        The name exists but there is
  897  *                      no data at the name.
  898  *
  899  *  \li #DNS_R_COVERINGNSEC     The returned data is a NSEC
  900  *                      that potentially covers 'name'.
  901  *
  902  *  \li #DNS_R_EMPTYWILD        The name is a wildcard without
  903  *                      resource records.
  904  *
  905  *  Error results:
  906  *
  907  *  \li #ISC_R_NOMEMORY
  908  *
  909  *  \li #DNS_R_BADDB            Data that is required to be
  910  *                      present in the DB, e.g. an NSEC
  911  *                      record in a secure zone, is not
  912  *                      present.
  913  *
  914  *  \li Other results are possible, and should all be treated as
  915  *      errors.
  916  */
  917 
  918 isc_result_t
  919 dns_db_findzonecut(dns_db_t *db, const dns_name_t *name, unsigned int options,
  920            isc_stdtime_t now, dns_dbnode_t **nodep,
  921            dns_name_t *foundname, dns_name_t *dcname,
  922            dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
  923 /*%<
  924  * Find the deepest known zonecut which encloses 'name' in 'db'.
  925  *
  926  * Notes:
  927  *
  928  * \li  If the #DNS_DBFIND_NOEXACT option is set, then the zonecut returned
  929  *  (if any) will be the deepest known ancestor of 'name'.
  930  *
  931  * \li  If 'now' is zero, then the current time will be used.
  932  *
  933  * Requires:
  934  *
  935  * \li  'db' is a valid database with cache semantics.
  936  *
  937  * \li  'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
  938  *
  939  * \li  'foundname' is a valid name with a dedicated buffer.
  940  *
  941  * \li  'dcname' is a valid name with a dedicated buffer.
  942  *
  943  * \li  'rdataset' is NULL, or is a valid unassociated rdataset.
  944  *
  945  * Ensures, on a non-error completion:
  946  *
  947  * \li  If nodep != NULL, then it is bound to the found node.
  948  *
  949  * \li  If foundname != NULL, then it contains the full name of the
  950  *  found node.
  951  *
  952  * \li  If dcname != NULL, then it contains the deepest cached name
  953  *      that exists in the database.
  954  *
  955  * \li  If rdataset != NULL and type != dns_rdatatype_any, then
  956  *  rdataset is bound to the found rdataset.
  957  *
  958  * Non-error results are:
  959  *
  960  * \li  #ISC_R_SUCCESS
  961  *
  962  * \li  #ISC_R_NOTFOUND
  963  *
  964  * \li  Other results are possible, and should all be treated as
  965  *  errors.
  966  */
  967 
  968 void
  969 dns_db_attachnode(dns_db_t *db, dns_dbnode_t *source, dns_dbnode_t **targetp);
  970 /*%<
  971  * Attach *targetp to source.
  972  *
  973  * Requires:
  974  *
  975  * \li  'db' is a valid database.
  976  *
  977  * \li  'source' is a valid node.
  978  *
  979  * \li  'targetp' points to a NULL dns_dbnode_t *.
  980  *
  981  * Ensures:
  982  *
  983  * \li  *targetp is attached to source.
  984  */
  985 
  986 void
  987 dns_db_detachnode(dns_db_t *db, dns_dbnode_t **nodep);
  988 /*%<
  989  * Detach *nodep from its node.
  990  *
  991  * Requires:
  992  *
  993  * \li  'db' is a valid database.
  994  *
  995  * \li  'nodep' points to a valid node.
  996  *
  997  * Ensures:
  998  *
  999  * \li  *nodep is NULL.
 1000  */
 1001 
 1002 void
 1003 dns_db_transfernode(dns_db_t *db, dns_dbnode_t **sourcep,
 1004             dns_dbnode_t **targetp);
 1005 /*%<
 1006  * Transfer a node between pointer.
 1007  *
 1008  * This is equivalent to calling dns_db_attachnode() then dns_db_detachnode().
 1009  *
 1010  * Requires:
 1011  *
 1012  * \li  'db' is a valid database.
 1013  *
 1014  * \li  '*sourcep' is a valid node.
 1015  *
 1016  * \li  'targetp' points to a NULL dns_dbnode_t *.
 1017  *
 1018  * Ensures:
 1019  *
 1020  * \li  '*sourcep' is NULL.
 1021  */
 1022 
 1023 isc_result_t
 1024 dns_db_expirenode(dns_db_t *db, dns_dbnode_t *node, isc_stdtime_t now);
 1025 /*%<
 1026  * Mark as stale all records at 'node' which expire at or before 'now'.
 1027  *
 1028  * Note: if 'now' is zero, then the current time will be used.
 1029  *
 1030  * Requires:
 1031  *
 1032  * \li  'db' is a valid cache database.
 1033  *
 1034  * \li  'node' is a valid node.
 1035  */
 1036 
 1037 void
 1038 dns_db_printnode(dns_db_t *db, dns_dbnode_t *node, FILE *out);
 1039 /*%<
 1040  * Print a textual representation of the contents of the node to
 1041  * 'out'.
 1042  *
 1043  * Note: this function is intended for debugging, not general use.
 1044  *
 1045  * Requires:
 1046  *
 1047  * \li  'db' is a valid database.
 1048  *
 1049  * \li  'node' is a valid node.
 1050  */
 1051 
 1052 /***
 1053  *** DB Iterator Creation
 1054  ***/
 1055 
 1056 isc_result_t
 1057 dns_db_createiterator(dns_db_t *db, unsigned int options,
 1058               dns_dbiterator_t **iteratorp);
 1059 /*%<
 1060  * Create an iterator for version 'version' of 'db'.
 1061  *
 1062  * Notes:
 1063  *
 1064  * \li  One or more of the following options can be set.
 1065  *  #DNS_DB_RELATIVENAMES
 1066  *  #DNS_DB_NSEC3ONLY
 1067  *  #DNS_DB_NONSEC3
 1068  *
 1069  * Requires:
 1070  *
 1071  * \li  'db' is a valid database.
 1072  *
 1073  * \li  iteratorp != NULL && *iteratorp == NULL
 1074  *
 1075  * Ensures:
 1076  *
 1077  * \li  On success, *iteratorp will be a valid database iterator.
 1078  *
 1079  * Returns:
 1080  *
 1081  * \li  #ISC_R_SUCCESS
 1082  * \li  #ISC_R_NOMEMORY
 1083  */
 1084 
 1085 /***
 1086  *** Rdataset Methods
 1087  ***/
 1088 
 1089 /*
 1090  * XXXRTH  Should we check for glue and pending data in dns_db_findrdataset()?
 1091  */
 1092 
 1093 isc_result_t
 1094 dns_db_findrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
 1095             dns_rdatatype_t type, dns_rdatatype_t covers,
 1096             isc_stdtime_t now, dns_rdataset_t *rdataset,
 1097             dns_rdataset_t *sigrdataset);
 1098 
 1099 /*%<
 1100  * Search for an rdataset of type 'type' at 'node' that are in version
 1101  * 'version' of 'db'.  If found, make 'rdataset' refer to it.
 1102  *
 1103  * Notes:
 1104  *
 1105  * \li  If 'version' is NULL, then the current version will be used.
 1106  *
 1107  * \li  Care must be used when using this routine to build a DNS response:
 1108  *  'node' should have been found with dns_db_find(), not
 1109  *  dns_db_findnode().  No glue checking is done.  No checking for
 1110  *  pending data is done.
 1111  *
 1112  * \li  The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
 1113  *  cache database, an rdataset will not be found unless it expires after
 1114  *  'now'.  If 'now' is zero, then the current time will be used.
 1115  *
 1116  * Requires:
 1117  *
 1118  * \li  'db' is a valid database.
 1119  *
 1120  * \li  'node' is a valid node.
 1121  *
 1122  * \li  'rdataset' is a valid, disassociated rdataset.
 1123  *
 1124  * \li  'sigrdataset' is a valid, disassociated rdataset, or it is NULL.
 1125  *
 1126  * \li  If 'covers' != 0, 'type' must be RRSIG.
 1127  *
 1128  * \li  'type' is not a meta-RR type such as 'ANY' or 'OPT'.
 1129  *
 1130  * Ensures:
 1131  *
 1132  * \li  On success, 'rdataset' is associated with the found rdataset.
 1133  *
 1134  * Returns:
 1135  *
 1136  * \li  #ISC_R_SUCCESS
 1137  * \li  #ISC_R_NOTFOUND
 1138  *
 1139  * \li  Other results are possible, depending upon the database
 1140  *  implementation used.
 1141  */
 1142 
 1143 isc_result_t
 1144 dns_db_allrdatasets(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
 1145             isc_stdtime_t now, dns_rdatasetiter_t **iteratorp);
 1146 /*%<
 1147  * Make '*iteratorp' an rdataset iterator for all rdatasets at 'node' in
 1148  * version 'version' of 'db'.
 1149  *
 1150  * Notes:
 1151  *
 1152  * \li  If 'version' is NULL, then the current version will be used.
 1153  *
 1154  * \li  The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
 1155  *  cache database, an rdataset will not be found unless it expires after
 1156  *  'now'.  Any ANY query will not match unless at least one rdataset at
 1157  *  the node expires after 'now'.  If 'now' is zero, then the current time
 1158  *  will be used.
 1159  *
 1160  * Requires:
 1161  *
 1162  * \li  'db' is a valid database.
 1163  *
 1164  * \li  'node' is a valid node.
 1165  *
 1166  * \li  iteratorp != NULL && *iteratorp == NULL
 1167  *
 1168  * Ensures:
 1169  *
 1170  * \li  On success, '*iteratorp' is a valid rdataset iterator.
 1171  *
 1172  * Returns:
 1173  *
 1174  * \li  #ISC_R_SUCCESS
 1175  * \li  #ISC_R_NOTFOUND
 1176  *
 1177  * \li  Other results are possible, depending upon the database
 1178  *  implementation used.
 1179  */
 1180 
 1181 isc_result_t
 1182 dns_db_addrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
 1183            isc_stdtime_t now, dns_rdataset_t *rdataset,
 1184            unsigned int options, dns_rdataset_t *addedrdataset);
 1185 /*%<
 1186  * Add 'rdataset' to 'node' in version 'version' of 'db'.
 1187  *
 1188  * Notes:
 1189  *
 1190  * \li  If the database has zone semantics, the #DNS_DBADD_MERGE option is set,
 1191  *  and an rdataset of the same type as 'rdataset' already exists at
 1192  *  'node' then the contents of 'rdataset' will be merged with the existing
 1193  *  rdataset.  If the option is not set, then rdataset will replace any
 1194  *  existing rdataset of the same type.  If not merging and the
 1195  *  #DNS_DBADD_FORCE option is set, then the data will update the database
 1196  *  without regard to trust levels.  If not forcing the data, then the
 1197  *  rdataset will only be added if its trust level is >= the trust level of
 1198  *  any existing rdataset.  Forcing is only meaningful for cache databases.
 1199  *  If #DNS_DBADD_EXACT is set then there must be no rdata in common between
 1200  *  the old and new rdata sets.  If #DNS_DBADD_EXACTTTL is set then both
 1201  *  the old and new rdata sets must have the same ttl.
 1202  *
 1203  * \li  The 'now' field is ignored if 'db' is a zone database.  If 'db' is
 1204  *  a cache database, then the added rdataset will expire no later than
 1205  *  now + rdataset->ttl.
 1206  *
 1207  * \li  If 'addedrdataset' is not NULL, then it will be attached to the
 1208  *  resulting new rdataset in the database, or to the existing data if
 1209  *  the existing data was better.
 1210  *
 1211  * Requires:
 1212  *
 1213  * \li  'db' is a valid database.
 1214  *
 1215  * \li  'node' is a valid node.
 1216  *
 1217  * \li  'rdataset' is a valid, associated rdataset with the same class
 1218  *  as 'db'.
 1219  *
 1220  * \li  'addedrdataset' is NULL, or a valid, unassociated rdataset.
 1221  *
 1222  * \li  The database has zone semantics and 'version' is a valid
 1223  *  read-write version, or the database has cache semantics
 1224  *  and version is NULL.
 1225  *
 1226  * \li  If the database has cache semantics, the #DNS_DBADD_MERGE option must
 1227  *  not be set.
 1228  *
 1229  * Returns:
 1230  *
 1231  * \li  #ISC_R_SUCCESS
 1232  * \li  #DNS_R_UNCHANGED            The operation did not change
 1233  * anything. \li    #ISC_R_NOMEMORY \li #DNS_R_NOTEXACT
 1234  *
 1235  * \li  Other results are possible, depending upon the database
 1236  *  implementation used.
 1237  */
 1238 
 1239 isc_result_t
 1240 dns_db_subtractrdataset(dns_db_t *db, dns_dbnode_t *node,
 1241             dns_dbversion_t *version, dns_rdataset_t *rdataset,
 1242             unsigned int options, dns_rdataset_t *newrdataset);
 1243 /*%<
 1244  * Remove any rdata in 'rdataset' from 'node' in version 'version' of
 1245  * 'db'.
 1246  *
 1247  * Notes:
 1248  *
 1249  * \li  If 'newrdataset' is not NULL, then it will be attached to the
 1250  *  resulting new rdataset in the database, unless the rdataset has
 1251  *  become nonexistent.  If DNS_DBSUB_EXACT is set then all elements
 1252  *  of 'rdataset' must exist at 'node'.
 1253  *
 1254  *\li   If DNS_DBSUB_WANTOLD is set and the entire rdataset was deleted
 1255  *  then return the original rdatatset in newrdataset if that existed.
 1256  *
 1257  * Requires:
 1258  *
 1259  * \li  'db' is a valid database.
 1260  *
 1261  * \li  'node' is a valid node.
 1262  *
 1263  * \li  'rdataset' is a valid, associated rdataset with the same class
 1264  *  as 'db'.
 1265  *
 1266  * \li  'newrdataset' is NULL, or a valid, unassociated rdataset.
 1267  *
 1268  * \li  The database has zone semantics and 'version' is a valid
 1269  *  read-write version.
 1270  *
 1271  * Returns:
 1272  *
 1273  * \li  #ISC_R_SUCCESS
 1274  * \li  #DNS_R_UNCHANGED            The operation did not change
 1275  * anything. \li    #DNS_R_NXRRSET          All rdata of the same
 1276  *type as
 1277  * those in 'rdataset' have been deleted. \li   #DNS_R_NOTEXACT
 1278  * Some part of 'rdataset' did not exist and DNS_DBSUB_EXACT was set.
 1279  *
 1280  * \li  Other results are possible, depending upon the database
 1281  *  implementation used.
 1282  */
 1283 
 1284 isc_result_t
 1285 dns_db_deleterdataset(dns_db_t *db, dns_dbnode_t *node,
 1286               dns_dbversion_t *version, dns_rdatatype_t type,
 1287               dns_rdatatype_t covers);
 1288 /*%<
 1289  * Make it so that no rdataset of type 'type' exists at 'node' in version
 1290  * version 'version' of 'db'.
 1291  *
 1292  * Notes:
 1293  *
 1294  * \li  If 'type' is dns_rdatatype_any, then no rdatasets will exist in
 1295  *  'version' (provided that the dns_db_deleterdataset() isn't followed
 1296  *  by one or more dns_db_addrdataset() calls).
 1297  *
 1298  * Requires:
 1299  *
 1300  * \li  'db' is a valid database.
 1301  *
 1302  * \li  'node' is a valid node.
 1303  *
 1304  * \li  The database has zone semantics and 'version' is a valid
 1305  *  read-write version, or the database has cache semantics
 1306  *  and version is NULL.
 1307  *
 1308  * \li  'type' is not a meta-RR type, except for dns_rdatatype_any, which is
 1309  *  allowed.
 1310  *
 1311  * \li  If 'covers' != 0, 'type' must be SIG.
 1312  *
 1313  * Returns:
 1314  *
 1315  * \li  #ISC_R_SUCCESS
 1316  * \li  #DNS_R_UNCHANGED            No rdatasets of 'type' existed
 1317  * before the operation was attempted.
 1318  *
 1319  * \li  Other results are possible, depending upon the database
 1320  *  implementation used.
 1321  */
 1322 
 1323 isc_result_t
 1324 dns_db_getsoaserial(dns_db_t *db, dns_dbversion_t *ver, uint32_t *serialp);
 1325 /*%<
 1326  * Get the current SOA serial number from a zone database.
 1327  *
 1328  * Requires:
 1329  * \li  'db' is a valid database with zone semantics.
 1330  * \li  'ver' is a valid version.
 1331  */
 1332 
 1333 void
 1334 dns_db_overmem(dns_db_t *db, bool overmem);
 1335 /*%<
 1336  * Enable / disable aggressive cache cleaning.
 1337  */
 1338 
 1339 unsigned int
 1340 dns_db_nodecount(dns_db_t *db);
 1341 /*%<
 1342  * Count the number of nodes in 'db'.
 1343  *
 1344  * Requires:
 1345  *
 1346  * \li  'db' is a valid database.
 1347  *
 1348  * Returns:
 1349  * \li  The number of nodes in the database
 1350  */
 1351 
 1352 size_t
 1353 dns_db_hashsize(dns_db_t *db);
 1354 /*%<
 1355  * For database implementations using a hash table, report the
 1356  * current number of buckets.
 1357  *
 1358  * Requires:
 1359  *
 1360  * \li  'db' is a valid database.
 1361  *
 1362  * Returns:
 1363  * \li  The number of buckets in the database's hash table, or
 1364  *      0 if not implemented.
 1365  */
 1366 
 1367 isc_result_t
 1368 dns_db_adjusthashsize(dns_db_t *db, size_t size);
 1369 /*%<
 1370  * For database implementations using a hash table, adjust
 1371  * the size of the hash table to store objects with size
 1372  * memory footprint.
 1373  *
 1374  * Requires:
 1375  *
 1376  * \li  'db' is a valid database.
 1377  * \li  'size' is maximum memory footprint of the database
 1378  *
 1379  * Returns:
 1380  * \li  #ISC_R_SUCCESS  The registration succeeded
 1381  * \li  #ISC_R_NOMEMORY Out of memory
 1382  */
 1383 
 1384 void
 1385 dns_db_settask(dns_db_t *db, isc_task_t *task);
 1386 /*%<
 1387  * If task is set then the final detach maybe performed asynchronously.
 1388  *
 1389  * Requires:
 1390  * \li  'db' is a valid database.
 1391  * \li  'task' to be valid or NULL.
 1392  */
 1393 
 1394 bool
 1395 dns_db_ispersistent(dns_db_t *db);
 1396 /*%<
 1397  * Is 'db' persistent?  A persistent database does not need to be loaded
 1398  * from disk or written to disk.
 1399  *
 1400  * Requires:
 1401  *
 1402  * \li  'db' is a valid database.
 1403  *
 1404  * Returns:
 1405  * \li  #true   'db' is persistent.
 1406  * \li  #false  'db' is not persistent.
 1407  */
 1408 
 1409 isc_result_t
 1410 dns_db_register(const char *name, dns_dbcreatefunc_t create, void *driverarg,
 1411         isc_mem_t *mctx, dns_dbimplementation_t **dbimp);
 1412 
 1413 /*%<
 1414  * Register a new database implementation and add it to the list of
 1415  * supported implementations.
 1416  *
 1417  * Requires:
 1418  *
 1419  * \li  'name' is not NULL
 1420  * \li  'order' is a valid function pointer
 1421  * \li  'mctx' is a valid memory context
 1422  * \li  dbimp != NULL && *dbimp == NULL
 1423  *
 1424  * Returns:
 1425  * \li  #ISC_R_SUCCESS  The registration succeeded
 1426  * \li  #ISC_R_NOMEMORY Out of memory
 1427  * \li  #ISC_R_EXISTS   A database implementation with the same name exists
 1428  *
 1429  * Ensures:
 1430  *
 1431  * \li  *dbimp points to an opaque structure which must be passed to
 1432  *  dns_db_unregister().
 1433  */
 1434 
 1435 void
 1436 dns_db_unregister(dns_dbimplementation_t **dbimp);
 1437 /*%<
 1438  * Remove a database implementation from the list of supported
 1439  * implementations.  No databases of this type can be active when this
 1440  * is called.
 1441  *
 1442  * Requires:
 1443  * \li  dbimp != NULL && *dbimp == NULL
 1444  *
 1445  * Ensures:
 1446  *
 1447  * \li  Any memory allocated in *dbimp will be freed.
 1448  */
 1449 
 1450 isc_result_t
 1451 dns_db_getoriginnode(dns_db_t *db, dns_dbnode_t **nodep);
 1452 /*%<
 1453  * Get the origin DB node corresponding to the DB's zone.  This function
 1454  * should typically succeed unless the underlying DB implementation doesn't
 1455  * support the feature.
 1456  *
 1457  * Requires:
 1458  *
 1459  * \li  'db' is a valid zone database.
 1460  * \li  'nodep' != NULL && '*nodep' == NULL
 1461  *
 1462  * Ensures:
 1463  * \li  On success, '*nodep' will point to the DB node of the zone's origin.
 1464  *
 1465  * Returns:
 1466  * \li  #ISC_R_SUCCESS
 1467  * \li  #ISC_R_NOTFOUND - the DB implementation does not support this feature.
 1468  */
 1469 
 1470 isc_result_t
 1471 dns_db_getnsec3parameters(dns_db_t *db, dns_dbversion_t *version,
 1472               dns_hash_t *hash, uint8_t *flags,
 1473               uint16_t *iterations, unsigned char *salt,
 1474               size_t *salt_length);
 1475 /*%<
 1476  * Get the NSEC3 parameters that are associated with this zone.
 1477  *
 1478  * Requires:
 1479  * \li  'db' is a valid zone database.
 1480  *
 1481  * Returns:
 1482  * \li  #ISC_R_SUCCESS
 1483  * \li  #ISC_R_NOTFOUND - the DB implementation does not support this feature
 1484  *            or this zone does not have NSEC3 records.
 1485  */
 1486 
 1487 isc_result_t
 1488 dns_db_getsize(dns_db_t *db, dns_dbversion_t *version, uint64_t *records,
 1489            uint64_t *bytes);
 1490 /*%<
 1491  * On success if 'records' is not NULL, it is set to the number of records
 1492  * in the given version of the database. If 'bytes' is not NULL, it is
 1493  * set to the approximate number of bytes needed to transfer the records,
 1494  * counting name, TTL, type, class, and rdata for each RR.  (This is meant
 1495  * to be a rough approximation of the size of a full zone transfer, though
 1496  * it does not take into account DNS message overhead or name compression.)
 1497  *
 1498  * Requires:
 1499  * \li  'db' is a valid zone database.
 1500  * \li  'version' is NULL or a valid version.
 1501  * \li  'records' is NULL or a pointer to return the record count in.
 1502  * \li  'bytes' is NULL or a pointer to return the byte count in.
 1503  *
 1504  * Returns:
 1505  * \li  #ISC_R_SUCCESS
 1506  * \li  #ISC_R_NOTIMPLEMENTED
 1507  */
 1508 
 1509 isc_result_t
 1510 dns_db_findnsec3node(dns_db_t *db, const dns_name_t *name, bool create,
 1511              dns_dbnode_t **nodep);
 1512 /*%<
 1513  * Find the NSEC3 node with name 'name'.
 1514  *
 1515  * Notes:
 1516  * \li  If 'create' is true and no node with name 'name' exists, then
 1517  *  such a node will be created.
 1518  *
 1519  * Requires:
 1520  *
 1521  * \li  'db' is a valid database.
 1522  *
 1523  * \li  'name' is a valid, non-empty, absolute name.
 1524  *
 1525  * \li  nodep != NULL && *nodep == NULL
 1526  *
 1527  * Ensures:
 1528  *
 1529  * \li  On success, *nodep is attached to the node with name 'name'.
 1530  *
 1531  * Returns:
 1532  *
 1533  * \li  #ISC_R_SUCCESS
 1534  * \li  #ISC_R_NOTFOUND         If !create and name not found.
 1535  * \li  #ISC_R_NOMEMORY         Can only happen if create is true.
 1536  *
 1537  * \li  Other results are possible, depending upon the database
 1538  *  implementation used.
 1539  */
 1540 
 1541 isc_result_t
 1542 dns_db_setsigningtime(dns_db_t *db, dns_rdataset_t *rdataset,
 1543               isc_stdtime_t resign);
 1544 /*%<
 1545  * Sets the re-signing time associated with 'rdataset' to 'resign'.
 1546  *
 1547  * Requires:
 1548  * \li  'db' is a valid zone database.
 1549  * \li  'rdataset' is or is to be associated with 'db'.
 1550  * \li  'rdataset' is not pending removed from the heap via an
 1551  *       uncommitted call to dns_db_resigned().
 1552  *
 1553  * Returns:
 1554  * \li  #ISC_R_SUCCESS
 1555  * \li  #ISC_R_NOMEMORY
 1556  * \li  #ISC_R_NOTIMPLEMENTED - Not supported by this DB implementation.
 1557  */
 1558 
 1559 isc_result_t
 1560 dns_db_getsigningtime(dns_db_t *db, dns_rdataset_t *rdataset, dns_name_t *name);
 1561 /*%<
 1562  * Return the rdataset with the earliest signing time in the zone.
 1563  * Note: the rdataset is version agnostic.
 1564  *
 1565  * Requires:
 1566  * \li  'db' is a valid zone database.
 1567  * \li  'rdataset' to be initialized but not associated.
 1568  * \li  'name' to be NULL or have a buffer associated with it.
 1569  *
 1570  * Returns:
 1571  * \li  #ISC_R_SUCCESS
 1572  * \li  #ISC_R_NOTFOUND - No dataset exists.
 1573  */
 1574 
 1575 void
 1576 dns_db_resigned(dns_db_t *db, dns_rdataset_t *rdataset,
 1577         dns_dbversion_t *version);
 1578 /*%<
 1579  * Mark 'rdataset' as not being available to be returned by
 1580  * dns_db_getsigningtime().  If the changes associated with 'version'
 1581  * are committed this will be permanent.  If the version is not committed
 1582  * this change will be rolled back when the version is closed.  Until
 1583  * 'version' is either committed or rolled back, 'rdataset' can no longer
 1584  * be acted upon by dns_db_setsigningtime().
 1585  *
 1586  * Requires:
 1587  * \li  'db' is a valid zone database.
 1588  * \li  'rdataset' to be associated with 'db'.
 1589  * \li  'version' to be open for writing.
 1590  */
 1591 
 1592 dns_stats_t *
 1593 dns_db_getrrsetstats(dns_db_t *db);
 1594 /*%<
 1595  * Get statistics information counting RRsets stored in the DB, when available.
 1596  * The statistics may not be available depending on the DB implementation.
 1597  *
 1598  * Requires:
 1599  *
 1600  * \li  'db' is a valid database (cache only).
 1601  *
 1602  * Returns:
 1603  * \li  when available, a pointer to a statistics object created by
 1604  *  dns_rdatasetstats_create(); otherwise NULL.
 1605  */
 1606 
 1607 isc_result_t
 1608 dns_db_setcachestats(dns_db_t *db, isc_stats_t *stats);
 1609 /*%<
 1610  * Set the location in which to collect cache statistics.
 1611  * This option may not exist depending on the DB implementation.
 1612  *
 1613  * Requires:
 1614  *
 1615  * \li  'db' is a valid database (cache only).
 1616  *
 1617  * Returns:
 1618  * \li  when available, a pointer to a statistics object created by
 1619  *  dns_rdatasetstats_create(); otherwise NULL.
 1620  */
 1621 
 1622 void
 1623 dns_db_rpz_attach(dns_db_t *db, void *rpzs, uint8_t rpz_num) ISC_DEPRECATED;
 1624 /*%<
 1625  * Attach the response policy information for a view to a database for a
 1626  * zone for the view.
 1627  */
 1628 
 1629 isc_result_t
 1630 dns_db_rpz_ready(dns_db_t *db) ISC_DEPRECATED;
 1631 /*%<
 1632  * Finish loading a response policy zone.
 1633  */
 1634 
 1635 isc_result_t
 1636 dns_db_updatenotify_register(dns_db_t *db, dns_dbupdate_callback_t fn,
 1637                  void *fn_arg);
 1638 /*%<
 1639  * Register a notify-on-update callback function to a database.
 1640  *
 1641  * Requires:
 1642  *
 1643  * \li  'db' is a valid database
 1644  * \li  'db' does not have an update callback registered
 1645  * \li  'fn' is not NULL
 1646  *
 1647  */
 1648 
 1649 isc_result_t
 1650 dns_db_updatenotify_unregister(dns_db_t *db, dns_dbupdate_callback_t fn,
 1651                    void *fn_arg);
 1652 /*%<
 1653  * Unregister a notify-on-update callback.
 1654  *
 1655  * Requires:
 1656  *
 1657  * \li  'db' is a valid database
 1658  * \li  'db' has update callback registered
 1659  *
 1660  */
 1661 
 1662 isc_result_t
 1663 dns_db_nodefullname(dns_db_t *db, dns_dbnode_t *node, dns_name_t *name);
 1664 /*%<
 1665  * Get the name associated with a database node.
 1666  *
 1667  * Requires:
 1668  *
 1669  * \li  'db' is a valid database
 1670  * \li  'node' and 'name' are not NULL
 1671  */
 1672 
 1673 isc_result_t
 1674 dns_db_setservestalettl(dns_db_t *db, dns_ttl_t ttl);
 1675 /*%<
 1676  * Sets the maximum length of time that cached answers may be retained
 1677  * past their normal TTL. Default value for the library is 0, disabling
 1678  * the use of stale data.
 1679  *
 1680  * Requires:
 1681  * \li  'db' is a valid cache database.
 1682  * \li  'ttl' is the number of seconds to retain data past its normal expiry.
 1683  *
 1684  * Returns:
 1685  * \li  #ISC_R_SUCCESS
 1686  * \li  #ISC_R_NOTIMPLEMENTED - Not supported by this DB implementation.
 1687  */
 1688 
 1689 isc_result_t
 1690 dns_db_getservestalettl(dns_db_t *db, dns_ttl_t *ttl);
 1691 /*%<
 1692  * Gets maximum length of time that cached answers may be kept past
 1693  * normal TTL expiration.
 1694  *
 1695  * Requires:
 1696  * \li  'db' is a valid cache database.
 1697  * \li  'ttl' is the number of seconds to retain data past its normal expiry.
 1698  *
 1699  * Returns:
 1700  * \li  #ISC_R_SUCCESS
 1701  * \li  #ISC_R_NOTIMPLEMENTED - Not supported by this DB implementation.
 1702  */
 1703 
 1704 isc_result_t
 1705 dns_db_setgluecachestats(dns_db_t *db, isc_stats_t *stats);
 1706 /*%<
 1707  * Set the location in which to collect glue cache statistics.
 1708  * This option may not exist depending on the DB implementation.
 1709  *
 1710  * Requires:
 1711  *
 1712  * \li  'db' is a valid database (cache only).
 1713  *
 1714  * Returns:
 1715  * \li  when available, a pointer to a statistics object created by
 1716  *  dns_rdatasetstats_create(); otherwise NULL.
 1717  */
 1718 
 1719 ISC_LANG_ENDDECLS
 1720 
 1721 #endif /* DNS_DB_H */