contrib/bind/lib/dns/include/dns/db.h

   1 /*
   2  * Copyright (C) 2004-2009  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2003  Internet Software Consortium.
   4  *
   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.
   8  *
   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.
  16  */
  17
  18 /* $Id: db.h,v 1.89.128.5.2.1 2009/12/31 21:45:53 each Exp $ */
  19
  20 #ifndef DNS_DB_H
  21 #define DNS_DB_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file dns/db.h
  28  * \brief
  29  * The DNS DB interface allows named rdatasets to be stored and retrieved.
  30  *
  31  * The dns_db_t type is like a "virtual class".  To actually use
  32  * DBs, an implementation of the class is required.
  33  *
  34  * XXX more XXX
  35  *
  36  * MP:
  37  * \li  The module ensures appropriate synchronization of data structures it
  38  *      creates and manipulates.
  39  *
  40  * Reliability:
  41  * \li  No anticipated impact.
  42  *
  43  * Resources:
  44  * \li  TBS
  45  *
  46  * Security:
  47  * \li  No anticipated impact.
  48  *
  49  * Standards:
  50  * \li  None.
  51  */
  52
  53 /*****
  54  ***** Imports
  55  *****/
  56
  57 #include <isc/lang.h>
  58 #include <isc/magic.h>
  59 #include <isc/ondestroy.h>
  60 #include <isc/stdtime.h>
  61
  62 #include <dns/name.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, 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,
  78                                 const char *filename,
  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,
  90                                     isc_boolean_t create,
  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,
  95                                 isc_stdtime_t now,
  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,
 111                                       isc_stdtime_t now);
 112         void            (*printnode)(dns_db_t *db, dns_dbnode_t *node,
 113                                      FILE *out);
 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,
 121                                         isc_stdtime_t now,
 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,
 126                                         isc_stdtime_t now,
 127                                         dns_rdatasetiter_t **iteratorp);
 128         isc_result_t    (*addrdataset)(dns_db_t *db, dns_dbnode_t *node,
 129                                        dns_dbversion_t *version,
 130                                        isc_stdtime_t now,
 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);
 152 } dns_dbmethods_t;
 153
 154 typedef isc_result_t
 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,
 158                       dns_db_t **dbp);
 159
 160 #define DNS_DB_MAGIC            ISC_MAGIC('D','N','S','D')
 161 #define DNS_DB_VALID(db)        ISC_MAGIC_VALID(db, DNS_DB_MAGIC)
 162
 163 /*%
 164  * This structure is actually just the common prefix of a DNS db
 165  * implementation's version of a dns_db_t.
 166  * \brief
 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
 170  * invariants.
 171  */
 172 struct dns_db {
 173         unsigned int                    magic;
 174         unsigned int                    impmagic;
 175         dns_dbmethods_t *               methods;
 176         isc_uint16_t                    attributes;
 177         dns_rdataclass_t                rdclass;
 178         dns_name_t                      origin;
 179         isc_ondestroy_t                 ondest;
 180         isc_mem_t *                     mctx;
 181 };
 182
 183 #define DNS_DBATTR_CACHE                0x01
 184 #define DNS_DBATTR_STUB                 0x02
 185
 186 /*@{*/
 187 /*%
 188  * Options that can be specified for dns_db_find().
 189  */
 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
 198 /*@}*/
 199
 200 /*@{*/
 201 /*%
 202  * Options that can be specified for dns_db_addrdataset().
 203  */
 204 #define DNS_DBADD_MERGE                 0x01
 205 #define DNS_DBADD_FORCE                 0x02
 206 #define DNS_DBADD_EXACT                 0x04
 207 #define DNS_DBADD_EXACTTTL              0x08
 208 /*@}*/
 209
 210 /*%
 211  * Options that can be specified for dns_db_subtractrdataset().
 212  */
 213 #define DNS_DBSUB_EXACT                 0x01
 214
 215 /*****
 216  ***** Methods
 217  *****/
 218
 219 /***
 220  *** Basic DB Methods
 221  ***/
 222
 223 isc_result_t
 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);
 227 /*%<
 228  * Create a new database using implementation 'db_type'.
 229  *
 230  * Notes:
 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
 234  *      call returns.
 235  *
 236  * \li  DB implementation-specific parameters are passed using argc and argv.
 237  *
 238  * Requires:
 239  *
 240  * \li  dbp != NULL and *dbp == NULL
 241  *
 242  * \li  'origin' is a valid absolute domain name.
 243  *
 244  * \li  mctx is a valid memory context
 245  *
 246  * Ensures:
 247  *
 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'.
 251  *
 252  * Returns:
 253  *
 254  * \li  #ISC_R_SUCCESS
 255  * \li  #ISC_R_NOMEMORY
 256  * \li  #ISC_R_NOTFOUND                         db_type not found
 257  *
 258  * \li  Many other errors are possible, depending on what db_type was
 259  *      specified.
 260  */
 261
 262 void
 263 dns_db_attach(dns_db_t *source, dns_db_t **targetp);
 264 /*%<
 265  * Attach *targetp to source.
 266  *
 267  * Requires:
 268  *
 269  * \li  'source' is a valid database.
 270  *
 271  * \li  'targetp' points to a NULL dns_db_t *.
 272  *
 273  * Ensures:
 274  *
 275  * \li  *targetp is attached to source.
 276  */
 277
 278 void
 279 dns_db_detach(dns_db_t **dbp);
 280 /*%<
 281  * Detach *dbp from its database.
 282  *
 283  * Requires:
 284  *
 285  * \li  'dbp' points to a valid database.
 286  *
 287  * Ensures:
 288  *
 289  * \li  *dbp is NULL.
 290  *
 291  * \li  If '*dbp' is the last reference to the database,
 292  *              all resources used by the database will be freed
 293  */
 294
 295 isc_result_t
 296 dns_db_ondestroy(dns_db_t *db, isc_task_t *task, isc_event_t **eventp);
 297 /*%<
 298  * Causes 'eventp' to be sent to be sent to 'task' when the database is
 299  * destroyed.
 300  *
 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
 303  * sent to the task.
 304  */
 305
 306 isc_boolean_t
 307 dns_db_iscache(dns_db_t *db);
 308 /*%<
 309  * Does 'db' have cache semantics?
 310  *
 311  * Requires:
 312  *
 313  * \li  'db' is a valid database.
 314  *
 315  * Returns:
 316  * \li  #ISC_TRUE       'db' has cache semantics
 317  * \li  #ISC_FALSE      otherwise
 318  */
 319
 320 isc_boolean_t
 321 dns_db_iszone(dns_db_t *db);
 322 /*%<
 323  * Does 'db' have zone semantics?
 324  *
 325  * Requires:
 326  *
 327  * \li  'db' is a valid database.
 328  *
 329  * Returns:
 330  * \li  #ISC_TRUE       'db' has zone semantics
 331  * \li  #ISC_FALSE      otherwise
 332  */
 333
 334 isc_boolean_t
 335 dns_db_isstub(dns_db_t *db);
 336 /*%<
 337  * Does 'db' have stub semantics?
 338  *
 339  * Requires:
 340  *
 341  * \li  'db' is a valid database.
 342  *
 343  * Returns:
 344  * \li  #ISC_TRUE       'db' has zone semantics
 345  * \li  #ISC_FALSE      otherwise
 346  */
 347
 348 isc_boolean_t
 349 dns_db_issecure(dns_db_t *db);
 350 /*%<
 351  * Is 'db' secure?
 352  *
 353  * Requires:
 354  *
 355  * \li  'db' is a valid database with zone semantics.
 356  *
 357  * Returns:
 358  * \li  #ISC_TRUE       'db' is secure.
 359  * \li  #ISC_FALSE      'db' is not secure.
 360  */
 361
 362 dns_name_t *
 363 dns_db_origin(dns_db_t *db);
 364 /*%<
 365  * The origin of the database.
 366  *
 367  * Note: caller must not try to change this name.
 368  *
 369  * Requires:
 370  *
 371  * \li  'db' is a valid database.
 372  *
 373  * Returns:
 374  *
 375  * \li  The origin of the database.
 376  */
 377
 378 dns_rdataclass_t
 379 dns_db_class(dns_db_t *db);
 380 /*%<
 381  * The class of the database.
 382  *
 383  * Requires:
 384  *
 385  * \li  'db' is a valid database.
 386  *
 387  * Returns:
 388  *
 389  * \li  The class of the database.
 390  */
 391
 392 isc_result_t
 393 dns_db_beginload(dns_db_t *db, dns_addrdatasetfunc_t *addp,
 394                  dns_dbload_t **dbloadp);
 395 /*%<
 396  * Begin loading 'db'.
 397  *
 398  * Requires:
 399  *
 400  * \li  'db' is a valid database.
 401  *
 402  * \li  This is the first attempt to load 'db'.
 403  *
 404  * \li  addp != NULL && *addp == NULL
 405  *
 406  * \li  dbloadp != NULL && *dbloadp == NULL
 407  *
 408  * Ensures:
 409  *
 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.
 413  *
 414  * Returns:
 415  *
 416  * \li  #ISC_R_SUCCESS
 417  * \li  #ISC_R_NOMEMORY
 418  *
 419  * \li  Other results are possible, depending upon the database
 420  *      implementation used, syntax errors in the master file, etc.
 421  */
 422
 423 isc_result_t
 424 dns_db_endload(dns_db_t *db, dns_dbload_t **dbloadp);
 425 /*%<
 426  * Finish loading 'db'.
 427  *
 428  * Requires:
 429  *
 430  * \li  'db' is a valid database that is being loaded.
 431  *
 432  * \li  dbloadp != NULL and *dbloadp is a valid database load context.
 433  *
 434  * Ensures:
 435  *
 436  * \li  *dbloadp == NULL
 437  *
 438  * Returns:
 439  *
 440  * \li  #ISC_R_SUCCESS
 441  * \li  #ISC_R_NOMEMORY
 442  *
 443  * \li  Other results are possible, depending upon the database
 444  *      implementation used, syntax errors in the master file, etc.
 445  */
 446
 447 isc_result_t
 448 dns_db_load(dns_db_t *db, const char *filename);
 449
 450 isc_result_t
 451 dns_db_load2(dns_db_t *db, const char *filename, dns_masterformat_t format);
 452 /*%<
 453  * Load master file 'filename' into 'db'.
 454  *
 455  * Notes:
 456  * \li  This routine is equivalent to calling
 457  *
 458  *\code
 459  *              dns_db_beginload();
 460  *              dns_master_loadfile();
 461  *              dns_db_endload();
 462  *\endcode
 463  *
 464  * Requires:
 465  *
 466  * \li  'db' is a valid database.
 467  *
 468  * \li  This is the first attempt to load 'db'.
 469  *
 470  * Returns:
 471  *
 472  * \li  #ISC_R_SUCCESS
 473  * \li  #ISC_R_NOMEMORY
 474  *
 475  * \li  Other results are possible, depending upon the database
 476  *      implementation used, syntax errors in the master file, etc.
 477  */
 478
 479 isc_result_t
 480 dns_db_dump(dns_db_t *db, dns_dbversion_t *version, const char *filename);
 481
 482 isc_result_t
 483 dns_db_dump2(dns_db_t *db, dns_dbversion_t *version, const char *filename,
 484              dns_masterformat_t masterformat);
 485 /*%<
 486  * Dump version 'version' of 'db' to master file 'filename'.
 487  *
 488  * Requires:
 489  *
 490  * \li  'db' is a valid database.
 491  *
 492  * \li  'version' is a valid version.
 493  *
 494  * Returns:
 495  *
 496  * \li  #ISC_R_SUCCESS
 497  * \li  #ISC_R_NOMEMORY
 498  *
 499  * \li  Other results are possible, depending upon the database
 500  *      implementation used, OS file errors, etc.
 501  */
 502
 503 /***
 504  *** Version Methods
 505  ***/
 506
 507 void
 508 dns_db_currentversion(dns_db_t *db, dns_dbversion_t **versionp);
 509 /*%<
 510  * Open the current version for reading.
 511  *
 512  * Requires:
 513  *
 514  * \li  'db' is a valid database with zone semantics.
 515  *
 516  * \li  versionp != NULL && *verisonp == NULL
 517  *
 518  * Ensures:
 519  *
 520  * \li  On success, '*versionp' is attached to the current version.
 521  *
 522  */
 523
 524 isc_result_t
 525 dns_db_newversion(dns_db_t *db, dns_dbversion_t **versionp);
 526 /*%<
 527  * Open a new version for reading and writing.
 528  *
 529  * Requires:
 530  *
 531  * \li  'db' is a valid database with zone semantics.
 532  *
 533  * \li  versionp != NULL && *verisonp == NULL
 534  *
 535  * Ensures:
 536  *
 537  * \li  On success, '*versionp' is attached to the current version.
 538  *
 539  * Returns:
 540  *
 541  * \li  #ISC_R_SUCCESS
 542  * \li  #ISC_R_NOMEMORY
 543  *
 544  * \li  Other results are possible, depending upon the database
 545  *      implementation used.
 546  */
 547
 548 void
 549 dns_db_attachversion(dns_db_t *db, dns_dbversion_t *source,
 550                      dns_dbversion_t **targetp);
 551 /*%<
 552  * Attach '*targetp' to 'source'.
 553  *
 554  * Requires:
 555  *
 556  * \li  'db' is a valid database with zone semantics.
 557  *
 558  * \li  source is a valid open version
 559  *
 560  * \li  targetp != NULL && *targetp == NULL
 561  *
 562  * Ensures:
 563  *
 564  * \li  '*targetp' is attached to source.
 565  */
 566
 567 void
 568 dns_db_closeversion(dns_db_t *db, dns_dbversion_t **versionp,
 569                     isc_boolean_t commit);
 570 /*%<
 571  * Close version '*versionp'.
 572  *
 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
 576  * versions.
 577  *
 578  * Requires:
 579  *
 580  * \li  'db' is a valid database with zone semantics.
 581  *
 582  * \li  '*versionp' refers to a valid version.
 583  *
 584  * \li  If committing a writable version, then there must be no other
 585  *      outstanding references to the version (e.g. an active rdataset
 586  *      iterator).
 587  *
 588  * Ensures:
 589  *
 590  * \li  *versionp == NULL
 591  *
 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.
 596  */
 597
 598 /***
 599  *** Node Methods
 600  ***/
 601
 602 isc_result_t
 603 dns_db_findnode(dns_db_t *db, dns_name_t *name, isc_boolean_t create,
 604                 dns_dbnode_t **nodep);
 605 /*%<
 606  * Find the node with name 'name'.
 607  *
 608  * Notes:
 609  * \li  If 'create' is ISC_TRUE and no node with name 'name' exists, then
 610  *      such a node will be created.
 611  *
 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.
 616  *
 617  * Requires:
 618  *
 619  * \li  'db' is a valid database.
 620  *
 621  * \li  'name' is a valid, non-empty, absolute name.
 622  *
 623  * \li  nodep != NULL && *nodep == NULL
 624  *
 625  * Ensures:
 626  *
 627  * \li  On success, *nodep is attached to the node with name 'name'.
 628  *
 629  * Returns:
 630  *
 631  * \li  #ISC_R_SUCCESS
 632  * \li  #ISC_R_NOTFOUND                 If !create and name not found.
 633  * \li  #ISC_R_NOMEMORY                 Can only happen if create is ISC_TRUE.
 634  *
 635  * \li  Other results are possible, depending upon the database
 636  *      implementation used.
 637  */
 638
 639 isc_result_t
 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);
 644 /*%<
 645  * Find the best match for 'name' and 'type' in version 'version' of 'db'.
 646  *
 647  * Notes:
 648  *
 649  * \li  If type == dns_rdataset_any, then rdataset will not be bound.
 650  *
 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
 654  *      dns_trust_glue.
 655  *
 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
 658  *      cache databases.
 659  *
 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.
 662  *
 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
 666  *      when created.
 667  *
 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
 672  *      cache.
 673  *
 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.
 676  *
 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.
 680  *
 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
 685  *      will be used.
 686  *
 687  * Requires:
 688  *
 689  * \li  'db' is a valid database.
 690  *
 691  * \li  'type' is not SIG, or a meta-RR type other than 'ANY' (e.g. 'OPT').
 692  *
 693  * \li  'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
 694  *
 695  * \li  'foundname' is a valid name with a dedicated buffer.
 696  *
 697  * \li  'rdataset' is NULL, or is a valid unassociated rdataset.
 698  *
 699  * Ensures,
 700  *      on a non-error completion:
 701  *
 702  *      \li     If nodep != NULL, then it is bound to the found node.
 703  *
 704  *      \li     If foundname != NULL, then it contains the full name of the
 705  *              found node.
 706  *
 707  *      \li     If rdataset != NULL and type != dns_rdatatype_any, then
 708  *              rdataset is bound to the found rdataset.
 709  *
 710  *      Non-error results are:
 711  *
 712  *      \li     #ISC_R_SUCCESS                  The desired node and type were
 713  *                                              found.
 714  *
 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.
 722  *
 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
 736  *                                              glue to a client.
 737  *
 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
 744  *                                              delegation.
 745  *
 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
 753  *                                              is set.
 754  *
 755  *      \li     #DNS_R_DNAME                    The data requested is beneath
 756  *                                              a DNAME.  node, foundname,
 757  *                                              and rdataset reference the
 758  *                                              DNAME RRset.
 759  *
 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.
 765  *
 766  *      \li     #DNS_R_NXDOMAIN                 The desired name does not
 767  *                                              exist.
 768  *
 769  *      \li     #DNS_R_NXRRSET                  The desired name exists, but
 770  *                                              the desired type does not.
 771  *
 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).
 779  *
 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.
 785  *
 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.
 791  *
 792  *      \li     #DNS_R_EMPTYNAME                        The name exists but there is
 793  *                                              no data at the name.
 794  *
 795  *      \li     #DNS_R_COVERINGNSEC             The returned data is a NSEC
 796  *                                              that potentially covers 'name'.
 797  *
 798  *      Error results:
 799  *
 800  *      \li     #ISC_R_NOMEMORY
 801  *
 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
 805  *                                              present.
 806  *
 807  *      \li     Other results are possible, and should all be treated as
 808  *              errors.
 809  */
 810
 811 isc_result_t
 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);
 816 /*%<
 817  * Find the deepest known zonecut which encloses 'name' in 'db'.
 818  *
 819  * Notes:
 820  *
 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'.
 823  *
 824  * \li  If 'now' is zero, then the current time will be used.
 825  *
 826  * Requires:
 827  *
 828  * \li  'db' is a valid database with cache semantics.
 829  *
 830  * \li  'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
 831  *
 832  * \li  'foundname' is a valid name with a dedicated buffer.
 833  *
 834  * \li  'rdataset' is NULL, or is a valid unassociated rdataset.
 835  *
 836  * Ensures, on a non-error completion:
 837  *
 838  * \li  If nodep != NULL, then it is bound to the found node.
 839  *
 840  * \li  If foundname != NULL, then it contains the full name of the
 841  *      found node.
 842  *
 843  * \li  If rdataset != NULL and type != dns_rdatatype_any, then
 844  *      rdataset is bound to the found rdataset.
 845  *
 846  * Non-error results are:
 847  *
 848  * \li  #ISC_R_SUCCESS
 849  *
 850  * \li  #ISC_R_NOTFOUND
 851  *
 852  * \li  Other results are possible, and should all be treated as
 853  *      errors.
 854  */
 855
 856 void
 857 dns_db_attachnode(dns_db_t *db, dns_dbnode_t *source, dns_dbnode_t **targetp);
 858 /*%<
 859  * Attach *targetp to source.
 860  *
 861  * Requires:
 862  *
 863  * \li  'db' is a valid database.
 864  *
 865  * \li  'source' is a valid node.
 866  *
 867  * \li  'targetp' points to a NULL dns_dbnode_t *.
 868  *
 869  * Ensures:
 870  *
 871  * \li  *targetp is attached to source.
 872  */
 873
 874 void
 875 dns_db_detachnode(dns_db_t *db, dns_dbnode_t **nodep);
 876 /*%<
 877  * Detach *nodep from its node.
 878  *
 879  * Requires:
 880  *
 881  * \li  'db' is a valid database.
 882  *
 883  * \li  'nodep' points to a valid node.
 884  *
 885  * Ensures:
 886  *
 887  * \li  *nodep is NULL.
 888  */
 889
 890 void
 891 dns_db_transfernode(dns_db_t *db, dns_dbnode_t **sourcep,
 892                     dns_dbnode_t **targetp);
 893 /*%<
 894  * Transfer a node between pointer.
 895  *
 896  * This is equivalent to calling dns_db_attachnode() then dns_db_detachnode().
 897  *
 898  * Requires:
 899  *
 900  * \li  'db' is a valid database.
 901  *
 902  * \li  '*sourcep' is a valid node.
 903  *
 904  * \li  'targetp' points to a NULL dns_dbnode_t *.
 905  *
 906  * Ensures:
 907  *
 908  * \li  '*sourcep' is NULL.
 909  */
 910
 911 isc_result_t
 912 dns_db_expirenode(dns_db_t *db, dns_dbnode_t *node, isc_stdtime_t now);
 913 /*%<
 914  * Mark as stale all records at 'node' which expire at or before 'now'.
 915  *
 916  * Note: if 'now' is zero, then the current time will be used.
 917  *
 918  * Requires:
 919  *
 920  * \li  'db' is a valid cache database.
 921  *
 922  * \li  'node' is a valid node.
 923  */
 924
 925 void
 926 dns_db_printnode(dns_db_t *db, dns_dbnode_t *node, FILE *out);
 927 /*%<
 928  * Print a textual representation of the contents of the node to
 929  * 'out'.
 930  *
 931  * Note: this function is intended for debugging, not general use.
 932  *
 933  * Requires:
 934  *
 935  * \li  'db' is a valid database.
 936  *
 937  * \li  'node' is a valid node.
 938  */
 939
 940 /***
 941  *** DB Iterator Creation
 942  ***/
 943
 944 isc_result_t
 945 dns_db_createiterator(dns_db_t *db, isc_boolean_t relative_names,
 946                       dns_dbiterator_t **iteratorp);
 947 /*%<
 948  * Create an iterator for version 'version' of 'db'.
 949  *
 950  * Notes:
 951  *
 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.
 955  *
 956  * Requires:
 957  *
 958  * \li  'db' is a valid database.
 959  *
 960  * \li  iteratorp != NULL && *iteratorp == NULL
 961  *
 962  * Ensures:
 963  *
 964  * \li  On success, *iteratorp will be a valid database iterator.
 965  *
 966  * Returns:
 967  *
 968  * \li  #ISC_R_SUCCESS
 969  * \li  #ISC_R_NOMEMORY
 970  */
 971
 972 /***
 973  *** Rdataset Methods
 974  ***/
 975
 976 /*
 977  * XXXRTH  Should we check for glue and pending data in dns_db_findrdataset()?
 978  */
 979
 980 isc_result_t
 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);
 985 /*%<
 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.
 988  *
 989  * Notes:
 990  *
 991  * \li  If 'version' is NULL, then the current version will be used.
 992  *
 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.
 997  *
 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.
1001  *
1002  * Requires:
1003  *
1004  * \li  'db' is a valid database.
1005  *
1006  * \li  'node' is a valid node.
1007  *
1008  * \li  'rdataset' is a valid, disassociated rdataset.
1009  *
1010  * \li  'sigrdataset' is a valid, disassociated rdataset, or it is NULL.
1011  *
1012  * \li  If 'covers' != 0, 'type' must be SIG.
1013  *
1014  * \li  'type' is not a meta-RR type such as 'ANY' or 'OPT'.
1015  *
1016  * Ensures:
1017  *
1018  * \li  On success, 'rdataset' is associated with the found rdataset.
1019  *
1020  * Returns:
1021  *
1022  * \li  #ISC_R_SUCCESS
1023  * \li  #ISC_R_NOTFOUND
1024  *
1025  * \li  Other results are possible, depending upon the database
1026  *      implementation used.
1027  */
1028
1029 isc_result_t
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);
1032 /*%<
1033  * Make '*iteratorp' an rdataset iterator for all rdatasets at 'node' in
1034  * version 'version' of 'db'.
1035  *
1036  * Notes:
1037  *
1038  * \li  If 'version' is NULL, then the current version will be used.
1039  *
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
1044  *      will be used.
1045  *
1046  * Requires:
1047  *
1048  * \li  'db' is a valid database.
1049  *
1050  * \li  'node' is a valid node.
1051  *
1052  * \li  iteratorp != NULL && *iteratorp == NULL
1053  *
1054  * Ensures:
1055  *
1056  * \li  On success, '*iteratorp' is a valid rdataset iterator.
1057  *
1058  * Returns:
1059  *
1060  * \li  #ISC_R_SUCCESS
1061  * \li  #ISC_R_NOTFOUND
1062  *
1063  * \li  Other results are possible, depending upon the database
1064  *      implementation used.
1065  */
1066
1067 isc_result_t
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);
1071 /*%<
1072  * Add 'rdataset' to 'node' in version 'version' of 'db'.
1073  *
1074  * Notes:
1075  *
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.
1088  *
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.
1092  *
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.
1096  *
1097  * Requires:
1098  *
1099  * \li  'db' is a valid database.
1100  *
1101  * \li  'node' is a valid node.
1102  *
1103  * \li  'rdataset' is a valid, associated rdataset with the same class
1104  *      as 'db'.
1105  *
1106  * \li  'addedrdataset' is NULL, or a valid, unassociated rdataset.
1107  *
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.
1111  *
1112  * \li  If the database has cache semantics, the #DNS_DBADD_MERGE option must
1113  *      not be set.
1114  *
1115  * Returns:
1116  *
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
1121  *
1122  * \li  Other results are possible, depending upon the database
1123  *      implementation used.
1124  */
1125
1126 isc_result_t
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);
1130 /*%<
1131  * Remove any rdata in 'rdataset' from 'node' in version 'version' of
1132  * 'db'.
1133  *
1134  * Notes:
1135  *
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'.
1140  *
1141  * Requires:
1142  *
1143  * \li  'db' is a valid database.
1144  *
1145  * \li  'node' is a valid node.
1146  *
1147  * \li  'rdataset' is a valid, associated rdataset with the same class
1148  *      as 'db'.
1149  *
1150  * \li  'newrdataset' is NULL, or a valid, unassociated rdataset.
1151  *
1152  * \li  The database has zone semantics and 'version' is a valid
1153  *      read-write version.
1154  *
1155  * Returns:
1156  *
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.
1163  *
1164  * \li  Other results are possible, depending upon the database
1165  *      implementation used.
1166  */
1167
1168 isc_result_t
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);
1172 /*%<
1173  * Make it so that no rdataset of type 'type' exists at 'node' in version
1174  * version 'version' of 'db'.
1175  *
1176  * Notes:
1177  *
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).
1181  *
1182  * Requires:
1183  *
1184  * \li  'db' is a valid database.
1185  *
1186  * \li  'node' is a valid node.
1187  *
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.
1191  *
1192  * \li  'type' is not a meta-RR type, except for dns_rdatatype_any, which is
1193  *      allowed.
1194  *
1195  * \li  If 'covers' != 0, 'type' must be SIG.
1196  *
1197  * Returns:
1198  *
1199  * \li  #ISC_R_SUCCESS
1200  * \li  #DNS_R_UNCHANGED                        No rdatasets of 'type' existed before
1201  *                                      the operation was attempted.
1202  *
1203  * \li  Other results are possible, depending upon the database
1204  *      implementation used.
1205  */
1206
1207 isc_result_t
1208 dns_db_getsoaserial(dns_db_t *db, dns_dbversion_t *ver, isc_uint32_t *serialp);
1209 /*%<
1210  * Get the current SOA serial number from a zone database.
1211  *
1212  * Requires:
1213  * \li  'db' is a valid database with zone semantics.
1214  * \li  'ver' is a valid version.
1215  */
1216
1217 void
1218 dns_db_overmem(dns_db_t *db, isc_boolean_t overmem);
1219 /*%<
1220  * Enable / disable aggressive cache cleaning.
1221  */
1222
1223 unsigned int
1224 dns_db_nodecount(dns_db_t *db);
1225 /*%<
1226  * Count the number of nodes in 'db'.
1227  *
1228  * Requires:
1229  *
1230  * \li  'db' is a valid database.
1231  *
1232  * Returns:
1233  * \li  The number of nodes in the database
1234  */
1235
1236 void
1237 dns_db_settask(dns_db_t *db, isc_task_t *task);
1238 /*%<
1239  * If task is set then the final detach maybe performed asynchronously.
1240  *
1241  * Requires:
1242  * \li  'db' is a valid database.
1243  * \li  'task' to be valid or NULL.
1244  */
1245
1246 isc_boolean_t
1247 dns_db_ispersistent(dns_db_t *db);
1248 /*%<
1249  * Is 'db' persistent?  A persistent database does not need to be loaded
1250  * from disk or written to disk.
1251  *
1252  * Requires:
1253  *
1254  * \li  'db' is a valid database.
1255  *
1256  * Returns:
1257  * \li  #ISC_TRUE       'db' is persistent.
1258  * \li  #ISC_FALSE      'db' is not persistent.
1259  */
1260
1261 isc_result_t
1262 dns_db_register(const char *name, dns_dbcreatefunc_t create, void *driverarg,
1263                 isc_mem_t *mctx, dns_dbimplementation_t **dbimp);
1264
1265 /*%<
1266  * Register a new database implementation and add it to the list of
1267  * supported implementations.
1268  *
1269  * Requires:
1270  *
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
1275  *
1276  * Returns:
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
1280  *
1281  * Ensures:
1282  *
1283  * \li  *dbimp points to an opaque structure which must be passed to
1284  *      dns_db_unregister().
1285  */
1286
1287 void
1288 dns_db_unregister(dns_dbimplementation_t **dbimp);
1289 /*%<
1290  * Remove a database implementation from the list of supported
1291  * implementations.  No databases of this type can be active when this
1292  * is called.
1293  *
1294  * Requires:
1295  * \li  dbimp != NULL && *dbimp == NULL
1296  *
1297  * Ensures:
1298  *
1299  * \li  Any memory allocated in *dbimp will be freed.
1300  */
1301
1302 isc_result_t
1303 dns_db_getoriginnode(dns_db_t *db, dns_dbnode_t **nodep);
1304 /*%<
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.
1308  *
1309  * Requires:
1310  *
1311  * \li  'db' is a valid zone database.
1312  * \li  'nodep' != NULL && '*nodep' == NULL
1313  *
1314  * Ensures:
1315  * \li  On success, '*nodep' will point to the DB node of the zone's origin.
1316  *
1317  * Returns:
1318  * \li  #ISC_R_SUCCESS
1319  * \li  #ISC_R_NOTFOUND - the DB implementation does not support this feature.
1320  */
1321
1322 dns_stats_t *
1323 dns_db_getrrsetstats(dns_db_t *db);
1324 /*%<
1325  * Get statistics information counting RRsets stored in the DB, when available.
1326  * The statistics may not be available depending on the DB implementation.
1327  *
1328  * Requires:
1329  *
1330  * \li  'db' is a valid database (zone or cache).
1331  *
1332  * Returns:
1333  * \li  when available, a pointer to a statistics object created by
1334  *      dns_rdatasetstats_create(); otherwise NULL.
1335  */
1336
1337 ISC_LANG_ENDDECLS
1338
1339 #endif /* DNS_DB_H */