contrib/bind-9.5.2/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 2009/01/19 00:01:11 marka 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               0x01
 191 #define DNS_DBFIND_VALIDATEGLUE         0x02
 192 #define DNS_DBFIND_NOWILD               0x04
 193 #define DNS_DBFIND_PENDINGOK            0x08
 194 #define DNS_DBFIND_NOEXACT              0x10
 195 #define DNS_DBFIND_FORCENSEC            0x20
 196 #define DNS_DBFIND_COVERINGNSEC         0x40
 197 /*@}*/
 198
 199 /*@{*/
 200 /*%
 201  * Options that can be specified for dns_db_addrdataset().
 202  */
 203 #define DNS_DBADD_MERGE                 0x01
 204 #define DNS_DBADD_FORCE                 0x02
 205 #define DNS_DBADD_EXACT                 0x04
 206 #define DNS_DBADD_EXACTTTL              0x08
 207 /*@}*/
 208
 209 /*%
 210  * Options that can be specified for dns_db_subtractrdataset().
 211  */
 212 #define DNS_DBSUB_EXACT                 0x01
 213
 214 /*****
 215  ***** Methods
 216  *****/
 217
 218 /***
 219  *** Basic DB Methods
 220  ***/
 221
 222 isc_result_t
 223 dns_db_create(isc_mem_t *mctx, const char *db_type, dns_name_t *origin,
 224               dns_dbtype_t type, dns_rdataclass_t rdclass,
 225               unsigned int argc, char *argv[], dns_db_t **dbp);
 226 /*%<
 227  * Create a new database using implementation 'db_type'.
 228  *
 229  * Notes:
 230  * \li  All names in the database must be subdomains of 'origin' and in class
 231  *      'rdclass'.  The database makes its own copy of the origin, so the
 232  *      caller may do whatever they like with 'origin' and its storage once the
 233  *      call returns.
 234  *
 235  * \li  DB implementation-specific parameters are passed using argc and argv.
 236  *
 237  * Requires:
 238  *
 239  * \li  dbp != NULL and *dbp == NULL
 240  *
 241  * \li  'origin' is a valid absolute domain name.
 242  *
 243  * \li  mctx is a valid memory context
 244  *
 245  * Ensures:
 246  *
 247  * \li  A copy of 'origin' has been made for the databases use, and the
 248  *      caller is free to do whatever they want with the name and storage
 249  *      associated with 'origin'.
 250  *
 251  * Returns:
 252  *
 253  * \li  #ISC_R_SUCCESS
 254  * \li  #ISC_R_NOMEMORY
 255  * \li  #ISC_R_NOTFOUND                         db_type not found
 256  *
 257  * \li  Many other errors are possible, depending on what db_type was
 258  *      specified.
 259  */
 260
 261 void
 262 dns_db_attach(dns_db_t *source, dns_db_t **targetp);
 263 /*%<
 264  * Attach *targetp to source.
 265  *
 266  * Requires:
 267  *
 268  * \li  'source' is a valid database.
 269  *
 270  * \li  'targetp' points to a NULL dns_db_t *.
 271  *
 272  * Ensures:
 273  *
 274  * \li  *targetp is attached to source.
 275  */
 276
 277 void
 278 dns_db_detach(dns_db_t **dbp);
 279 /*%<
 280  * Detach *dbp from its database.
 281  *
 282  * Requires:
 283  *
 284  * \li  'dbp' points to a valid database.
 285  *
 286  * Ensures:
 287  *
 288  * \li  *dbp is NULL.
 289  *
 290  * \li  If '*dbp' is the last reference to the database,
 291  *              all resources used by the database will be freed
 292  */
 293
 294 isc_result_t
 295 dns_db_ondestroy(dns_db_t *db, isc_task_t *task, isc_event_t **eventp);
 296 /*%<
 297  * Causes 'eventp' to be sent to be sent to 'task' when the database is
 298  * destroyed.
 299  *
 300  * Note; ownership of the eventp is taken from the caller (and *eventp is
 301  * set to NULL). The sender field of the event is set to 'db' before it is
 302  * sent to the task.
 303  */
 304
 305 isc_boolean_t
 306 dns_db_iscache(dns_db_t *db);
 307 /*%<
 308  * Does 'db' have cache semantics?
 309  *
 310  * Requires:
 311  *
 312  * \li  'db' is a valid database.
 313  *
 314  * Returns:
 315  * \li  #ISC_TRUE       'db' has cache semantics
 316  * \li  #ISC_FALSE      otherwise
 317  */
 318
 319 isc_boolean_t
 320 dns_db_iszone(dns_db_t *db);
 321 /*%<
 322  * Does 'db' have zone semantics?
 323  *
 324  * Requires:
 325  *
 326  * \li  'db' is a valid database.
 327  *
 328  * Returns:
 329  * \li  #ISC_TRUE       'db' has zone semantics
 330  * \li  #ISC_FALSE      otherwise
 331  */
 332
 333 isc_boolean_t
 334 dns_db_isstub(dns_db_t *db);
 335 /*%<
 336  * Does 'db' have stub semantics?
 337  *
 338  * Requires:
 339  *
 340  * \li  'db' is a valid database.
 341  *
 342  * Returns:
 343  * \li  #ISC_TRUE       'db' has zone semantics
 344  * \li  #ISC_FALSE      otherwise
 345  */
 346
 347 isc_boolean_t
 348 dns_db_issecure(dns_db_t *db);
 349 /*%<
 350  * Is 'db' secure?
 351  *
 352  * Requires:
 353  *
 354  * \li  'db' is a valid database with zone semantics.
 355  *
 356  * Returns:
 357  * \li  #ISC_TRUE       'db' is secure.
 358  * \li  #ISC_FALSE      'db' is not secure.
 359  */
 360
 361 dns_name_t *
 362 dns_db_origin(dns_db_t *db);
 363 /*%<
 364  * The origin of the database.
 365  *
 366  * Note: caller must not try to change this name.
 367  *
 368  * Requires:
 369  *
 370  * \li  'db' is a valid database.
 371  *
 372  * Returns:
 373  *
 374  * \li  The origin of the database.
 375  */
 376
 377 dns_rdataclass_t
 378 dns_db_class(dns_db_t *db);
 379 /*%<
 380  * The class of the database.
 381  *
 382  * Requires:
 383  *
 384  * \li  'db' is a valid database.
 385  *
 386  * Returns:
 387  *
 388  * \li  The class of the database.
 389  */
 390
 391 isc_result_t
 392 dns_db_beginload(dns_db_t *db, dns_addrdatasetfunc_t *addp,
 393                  dns_dbload_t **dbloadp);
 394 /*%<
 395  * Begin loading 'db'.
 396  *
 397  * Requires:
 398  *
 399  * \li  'db' is a valid database.
 400  *
 401  * \li  This is the first attempt to load 'db'.
 402  *
 403  * \li  addp != NULL && *addp == NULL
 404  *
 405  * \li  dbloadp != NULL && *dbloadp == NULL
 406  *
 407  * Ensures:
 408  *
 409  * \li  On success, *addp will be a valid dns_addrdatasetfunc_t suitable
 410  *      for loading 'db'.  *dbloadp will be a valid DB load context which
 411  *      should be used as 'arg' when *addp is called.
 412  *
 413  * Returns:
 414  *
 415  * \li  #ISC_R_SUCCESS
 416  * \li  #ISC_R_NOMEMORY
 417  *
 418  * \li  Other results are possible, depending upon the database
 419  *      implementation used, syntax errors in the master file, etc.
 420  */
 421
 422 isc_result_t
 423 dns_db_endload(dns_db_t *db, dns_dbload_t **dbloadp);
 424 /*%<
 425  * Finish loading 'db'.
 426  *
 427  * Requires:
 428  *
 429  * \li  'db' is a valid database that is being loaded.
 430  *
 431  * \li  dbloadp != NULL and *dbloadp is a valid database load context.
 432  *
 433  * Ensures:
 434  *
 435  * \li  *dbloadp == NULL
 436  *
 437  * Returns:
 438  *
 439  * \li  #ISC_R_SUCCESS
 440  * \li  #ISC_R_NOMEMORY
 441  *
 442  * \li  Other results are possible, depending upon the database
 443  *      implementation used, syntax errors in the master file, etc.
 444  */
 445
 446 isc_result_t
 447 dns_db_load(dns_db_t *db, const char *filename);
 448
 449 isc_result_t
 450 dns_db_load2(dns_db_t *db, const char *filename, dns_masterformat_t format);
 451 /*%<
 452  * Load master file 'filename' into 'db'.
 453  *
 454  * Notes:
 455  * \li  This routine is equivalent to calling
 456  *
 457  *\code
 458  *              dns_db_beginload();
 459  *              dns_master_loadfile();
 460  *              dns_db_endload();
 461  *\endcode
 462  *
 463  * Requires:
 464  *
 465  * \li  'db' is a valid database.
 466  *
 467  * \li  This is the first attempt to load 'db'.
 468  *
 469  * Returns:
 470  *
 471  * \li  #ISC_R_SUCCESS
 472  * \li  #ISC_R_NOMEMORY
 473  *
 474  * \li  Other results are possible, depending upon the database
 475  *      implementation used, syntax errors in the master file, etc.
 476  */
 477
 478 isc_result_t
 479 dns_db_dump(dns_db_t *db, dns_dbversion_t *version, const char *filename);
 480
 481 isc_result_t
 482 dns_db_dump2(dns_db_t *db, dns_dbversion_t *version, const char *filename,
 483              dns_masterformat_t masterformat);
 484 /*%<
 485  * Dump version 'version' of 'db' to master file 'filename'.
 486  *
 487  * Requires:
 488  *
 489  * \li  'db' is a valid database.
 490  *
 491  * \li  'version' is a valid version.
 492  *
 493  * Returns:
 494  *
 495  * \li  #ISC_R_SUCCESS
 496  * \li  #ISC_R_NOMEMORY
 497  *
 498  * \li  Other results are possible, depending upon the database
 499  *      implementation used, OS file errors, etc.
 500  */
 501
 502 /***
 503  *** Version Methods
 504  ***/
 505
 506 void
 507 dns_db_currentversion(dns_db_t *db, dns_dbversion_t **versionp);
 508 /*%<
 509  * Open the current version for reading.
 510  *
 511  * Requires:
 512  *
 513  * \li  'db' is a valid database with zone semantics.
 514  *
 515  * \li  versionp != NULL && *verisonp == NULL
 516  *
 517  * Ensures:
 518  *
 519  * \li  On success, '*versionp' is attached to the current version.
 520  *
 521  */
 522
 523 isc_result_t
 524 dns_db_newversion(dns_db_t *db, dns_dbversion_t **versionp);
 525 /*%<
 526  * Open a new version for reading and writing.
 527  *
 528  * Requires:
 529  *
 530  * \li  'db' is a valid database with zone semantics.
 531  *
 532  * \li  versionp != NULL && *verisonp == NULL
 533  *
 534  * Ensures:
 535  *
 536  * \li  On success, '*versionp' is attached to the current version.
 537  *
 538  * Returns:
 539  *
 540  * \li  #ISC_R_SUCCESS
 541  * \li  #ISC_R_NOMEMORY
 542  *
 543  * \li  Other results are possible, depending upon the database
 544  *      implementation used.
 545  */
 546
 547 void
 548 dns_db_attachversion(dns_db_t *db, dns_dbversion_t *source,
 549                      dns_dbversion_t **targetp);
 550 /*%<
 551  * Attach '*targetp' to 'source'.
 552  *
 553  * Requires:
 554  *
 555  * \li  'db' is a valid database with zone semantics.
 556  *
 557  * \li  source is a valid open version
 558  *
 559  * \li  targetp != NULL && *targetp == NULL
 560  *
 561  * Ensures:
 562  *
 563  * \li  '*targetp' is attached to source.
 564  */
 565
 566 void
 567 dns_db_closeversion(dns_db_t *db, dns_dbversion_t **versionp,
 568                     isc_boolean_t commit);
 569 /*%<
 570  * Close version '*versionp'.
 571  *
 572  * Note: if '*versionp' is a read-write version and 'commit' is ISC_TRUE,
 573  * then all changes made in the version will take effect, otherwise they
 574  * will be rolled back.  The value if 'commit' is ignored for read-only
 575  * versions.
 576  *
 577  * Requires:
 578  *
 579  * \li  'db' is a valid database with zone semantics.
 580  *
 581  * \li  '*versionp' refers to a valid version.
 582  *
 583  * \li  If committing a writable version, then there must be no other
 584  *      outstanding references to the version (e.g. an active rdataset
 585  *      iterator).
 586  *
 587  * Ensures:
 588  *
 589  * \li  *versionp == NULL
 590  *
 591  * \li  If *versionp is a read-write version, and commit is ISC_TRUE, then
 592  *      the version will become the current version.  If !commit, then all
 593  *      changes made in the version will be undone, and the version will
 594  *      not become the current version.
 595  */
 596
 597 /***
 598  *** Node Methods
 599  ***/
 600
 601 isc_result_t
 602 dns_db_findnode(dns_db_t *db, dns_name_t *name, isc_boolean_t create,
 603                 dns_dbnode_t **nodep);
 604 /*%<
 605  * Find the node with name 'name'.
 606  *
 607  * Notes:
 608  * \li  If 'create' is ISC_TRUE and no node with name 'name' exists, then
 609  *      such a node will be created.
 610  *
 611  * \li  This routine is for finding or creating a node with the specified
 612  *      name.  There are no partial matches.  It is not suitable for use
 613  *      in building responses to ordinary DNS queries; clients which wish
 614  *      to do that should use dns_db_find() instead.
 615  *
 616  * Requires:
 617  *
 618  * \li  'db' is a valid database.
 619  *
 620  * \li  'name' is a valid, non-empty, absolute name.
 621  *
 622  * \li  nodep != NULL && *nodep == NULL
 623  *
 624  * Ensures:
 625  *
 626  * \li  On success, *nodep is attached to the node with name 'name'.
 627  *
 628  * Returns:
 629  *
 630  * \li  #ISC_R_SUCCESS
 631  * \li  #ISC_R_NOTFOUND                 If !create and name not found.
 632  * \li  #ISC_R_NOMEMORY                 Can only happen if create is ISC_TRUE.
 633  *
 634  * \li  Other results are possible, depending upon the database
 635  *      implementation used.
 636  */
 637
 638 isc_result_t
 639 dns_db_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version,
 640             dns_rdatatype_t type, unsigned int options, isc_stdtime_t now,
 641             dns_dbnode_t **nodep, dns_name_t *foundname,
 642             dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
 643 /*%<
 644  * Find the best match for 'name' and 'type' in version 'version' of 'db'.
 645  *
 646  * Notes:
 647  *
 648  * \li  If type == dns_rdataset_any, then rdataset will not be bound.
 649  *
 650  * \li  If 'options' does not have #DNS_DBFIND_GLUEOK set, then no glue will
 651  *      be returned.  For zone databases, glue is as defined in RFC2181.
 652  *      For cache databases, glue is any rdataset with a trust of
 653  *      dns_trust_glue.
 654  *
 655  * \li  If 'options' does not have #DNS_DBFIND_PENDINGOK set, then no
 656  *      pending data will be returned.  This option is only meaningful for
 657  *      cache databases.
 658  *
 659  * \li  If the #DNS_DBFIND_NOWILD option is set, then wildcard matching will
 660  *      be disabled.  This option is only meaningful for zone databases.
 661  *
 662  * \li  If the #DNS_DBFIND_FORCENSEC option is set, the database is assumed to
 663  *      have NSEC records, and these will be returned when appropriate.  This
 664  *      is only necessary when querying a database that was not secure
 665  *      when created.
 666  *
 667  * \li  If the DNS_DBFIND_COVERINGNSEC option is set, then look for a
 668  *      NSEC record that potentially covers 'name' if a answer cannot
 669  *      be found.  Note the returned NSEC needs to be checked to ensure
 670  *      that it is correct.  This only affects answers returned from the
 671  *      cache.
 672  *
 673  * \li  To respond to a query for SIG records, the caller should create a
 674  *      rdataset iterator and extract the signatures from each rdataset.
 675  *
 676  * \li  Making queries of type ANY with #DNS_DBFIND_GLUEOK is not recommended,
 677  *      because the burden of determining whether a given rdataset is valid
 678  *      glue or not falls upon the caller.
 679  *
 680  * \li  The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
 681  *      cache database, an rdataset will not be found unless it expires after
 682  *      'now'.  Any ANY query will not match unless at least one rdataset at
 683  *      the node expires after 'now'.  If 'now' is zero, then the current time
 684  *      will be used.
 685  *
 686  * Requires:
 687  *
 688  * \li  'db' is a valid database.
 689  *
 690  * \li  'type' is not SIG, or a meta-RR type other than 'ANY' (e.g. 'OPT').
 691  *
 692  * \li  'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
 693  *
 694  * \li  'foundname' is a valid name with a dedicated buffer.
 695  *
 696  * \li  'rdataset' is NULL, or is a valid unassociated rdataset.
 697  *
 698  * Ensures,
 699  *      on a non-error completion:
 700  *
 701  *      \li     If nodep != NULL, then it is bound to the found node.
 702  *
 703  *      \li     If foundname != NULL, then it contains the full name of the
 704  *              found node.
 705  *
 706  *      \li     If rdataset != NULL and type != dns_rdatatype_any, then
 707  *              rdataset is bound to the found rdataset.
 708  *
 709  *      Non-error results are:
 710  *
 711  *      \li     #ISC_R_SUCCESS                  The desired node and type were
 712  *                                              found.
 713  *
 714  *      \li     #DNS_R_WILDCARD                 The desired node and type were
 715  *                                              found after performing
 716  *                                              wildcard matching.  This is
 717  *                                              only returned if the
 718  *                                              #DNS_DBFIND_INDICATEWILD
 719  *                                              option is set; otherwise
 720  *                                              #ISC_R_SUCCESS is returned.
 721  *
 722  *      \li     #DNS_R_GLUE                     The desired node and type were
 723  *                                              found, but are glue.  This
 724  *                                              result can only occur if
 725  *                                              the DNS_DBFIND_GLUEOK option
 726  *                                              is set.  This result can only
 727  *                                              occur if 'db' is a zone
 728  *                                              database.  If type ==
 729  *                                              dns_rdatatype_any, then the
 730  *                                              node returned may contain, or
 731  *                                              consist entirely of invalid
 732  *                                              glue (i.e. data occluded by a
 733  *                                              zone cut).  The caller must
 734  *                                              take care not to return invalid
 735  *                                              glue to a client.
 736  *
 737  *      \li     #DNS_R_DELEGATION               The data requested is beneath
 738  *                                              a zone cut.  node, foundname,
 739  *                                              and rdataset reference the
 740  *                                              NS RRset of the zone cut.
 741  *                                              If 'db' is a cache database,
 742  *                                              then this is the deepest known
 743  *                                              delegation.
 744  *
 745  *      \li     #DNS_R_ZONECUT                  type == dns_rdatatype_any, and
 746  *                                              the desired node is a zonecut.
 747  *                                              The caller must take care not
 748  *                                              to return inappropriate glue
 749  *                                              to a client.  This result can
 750  *                                              only occur if 'db' is a zone
 751  *                                              database and DNS_DBFIND_GLUEOK
 752  *                                              is set.
 753  *
 754  *      \li     #DNS_R_DNAME                    The data requested is beneath
 755  *                                              a DNAME.  node, foundname,
 756  *                                              and rdataset reference the
 757  *                                              DNAME RRset.
 758  *
 759  *      \li     #DNS_R_CNAME                    The rdataset requested was not
 760  *                                              found, but there is a CNAME
 761  *                                              at the desired name.  node,
 762  *                                              foundname, and rdataset
 763  *                                              reference the CNAME RRset.
 764  *
 765  *      \li     #DNS_R_NXDOMAIN                 The desired name does not
 766  *                                              exist.
 767  *
 768  *      \li     #DNS_R_NXRRSET                  The desired name exists, but
 769  *                                              the desired type does not.
 770  *
 771  *      \li     #ISC_R_NOTFOUND                 The desired name does not
 772  *                                              exist, and no delegation could
 773  *                                              be found.  This result can only
 774  *                                              occur if 'db' is a cache
 775  *                                              database.  The caller should
 776  *                                              use its nameserver(s) of last
 777  *                                              resort (e.g. root hints).
 778  *
 779  *      \li     #DNS_R_NCACHENXDOMAIN           The desired name does not
 780  *                                              exist.  'node' is bound to the
 781  *                                              cache node with the desired
 782  *                                              name, and 'rdataset' contains
 783  *                                              the negative caching proof.
 784  *
 785  *      \li     #DNS_R_NCACHENXRRSET            The desired type does not
 786  *                                              exist.  'node' is bound to the
 787  *                                              cache node with the desired
 788  *                                              name, and 'rdataset' contains
 789  *                                              the negative caching proof.
 790  *
 791  *      \li     #DNS_R_EMPTYNAME                        The name exists but there is
 792  *                                              no data at the name.
 793  *
 794  *      \li     #DNS_R_COVERINGNSEC             The returned data is a NSEC
 795  *                                              that potentially covers 'name'.
 796  *
 797  *      Error results:
 798  *
 799  *      \li     #ISC_R_NOMEMORY
 800  *
 801  *      \li     #DNS_R_BADDB                    Data that is required to be
 802  *                                              present in the DB, e.g. an NSEC
 803  *                                              record in a secure zone, is not
 804  *                                              present.
 805  *
 806  *      \li     Other results are possible, and should all be treated as
 807  *              errors.
 808  */
 809
 810 isc_result_t
 811 dns_db_findzonecut(dns_db_t *db, dns_name_t *name,
 812                    unsigned int options, isc_stdtime_t now,
 813                    dns_dbnode_t **nodep, dns_name_t *foundname,
 814                    dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset);
 815 /*%<
 816  * Find the deepest known zonecut which encloses 'name' in 'db'.
 817  *
 818  * Notes:
 819  *
 820  * \li  If the #DNS_DBFIND_NOEXACT option is set, then the zonecut returned
 821  *      (if any) will be the deepest known ancestor of 'name'.
 822  *
 823  * \li  If 'now' is zero, then the current time will be used.
 824  *
 825  * Requires:
 826  *
 827  * \li  'db' is a valid database with cache semantics.
 828  *
 829  * \li  'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL.
 830  *
 831  * \li  'foundname' is a valid name with a dedicated buffer.
 832  *
 833  * \li  'rdataset' is NULL, or is a valid unassociated rdataset.
 834  *
 835  * Ensures, on a non-error completion:
 836  *
 837  * \li  If nodep != NULL, then it is bound to the found node.
 838  *
 839  * \li  If foundname != NULL, then it contains the full name of the
 840  *      found node.
 841  *
 842  * \li  If rdataset != NULL and type != dns_rdatatype_any, then
 843  *      rdataset is bound to the found rdataset.
 844  *
 845  * Non-error results are:
 846  *
 847  * \li  #ISC_R_SUCCESS
 848  *
 849  * \li  #ISC_R_NOTFOUND
 850  *
 851  * \li  Other results are possible, and should all be treated as
 852  *      errors.
 853  */
 854
 855 void
 856 dns_db_attachnode(dns_db_t *db, dns_dbnode_t *source, dns_dbnode_t **targetp);
 857 /*%<
 858  * Attach *targetp to source.
 859  *
 860  * Requires:
 861  *
 862  * \li  'db' is a valid database.
 863  *
 864  * \li  'source' is a valid node.
 865  *
 866  * \li  'targetp' points to a NULL dns_dbnode_t *.
 867  *
 868  * Ensures:
 869  *
 870  * \li  *targetp is attached to source.
 871  */
 872
 873 void
 874 dns_db_detachnode(dns_db_t *db, dns_dbnode_t **nodep);
 875 /*%<
 876  * Detach *nodep from its node.
 877  *
 878  * Requires:
 879  *
 880  * \li  'db' is a valid database.
 881  *
 882  * \li  'nodep' points to a valid node.
 883  *
 884  * Ensures:
 885  *
 886  * \li  *nodep is NULL.
 887  */
 888
 889 void
 890 dns_db_transfernode(dns_db_t *db, dns_dbnode_t **sourcep,
 891                     dns_dbnode_t **targetp);
 892 /*%<
 893  * Transfer a node between pointer.
 894  *
 895  * This is equivalent to calling dns_db_attachnode() then dns_db_detachnode().
 896  *
 897  * Requires:
 898  *
 899  * \li  'db' is a valid database.
 900  *
 901  * \li  '*sourcep' is a valid node.
 902  *
 903  * \li  'targetp' points to a NULL dns_dbnode_t *.
 904  *
 905  * Ensures:
 906  *
 907  * \li  '*sourcep' is NULL.
 908  */
 909
 910 isc_result_t
 911 dns_db_expirenode(dns_db_t *db, dns_dbnode_t *node, isc_stdtime_t now);
 912 /*%<
 913  * Mark as stale all records at 'node' which expire at or before 'now'.
 914  *
 915  * Note: if 'now' is zero, then the current time will be used.
 916  *
 917  * Requires:
 918  *
 919  * \li  'db' is a valid cache database.
 920  *
 921  * \li  'node' is a valid node.
 922  */
 923
 924 void
 925 dns_db_printnode(dns_db_t *db, dns_dbnode_t *node, FILE *out);
 926 /*%<
 927  * Print a textual representation of the contents of the node to
 928  * 'out'.
 929  *
 930  * Note: this function is intended for debugging, not general use.
 931  *
 932  * Requires:
 933  *
 934  * \li  'db' is a valid database.
 935  *
 936  * \li  'node' is a valid node.
 937  */
 938
 939 /***
 940  *** DB Iterator Creation
 941  ***/
 942
 943 isc_result_t
 944 dns_db_createiterator(dns_db_t *db, isc_boolean_t relative_names,
 945                       dns_dbiterator_t **iteratorp);
 946 /*%<
 947  * Create an iterator for version 'version' of 'db'.
 948  *
 949  * Notes:
 950  *
 951  * \li  If 'relative_names' is ISC_TRUE, then node names returned by the
 952  *      iterator will be relative to the iterator's current origin.  If
 953  *      #ISC_FALSE, then the node names will be absolute.
 954  *
 955  * Requires:
 956  *
 957  * \li  'db' is a valid database.
 958  *
 959  * \li  iteratorp != NULL && *iteratorp == NULL
 960  *
 961  * Ensures:
 962  *
 963  * \li  On success, *iteratorp will be a valid database iterator.
 964  *
 965  * Returns:
 966  *
 967  * \li  #ISC_R_SUCCESS
 968  * \li  #ISC_R_NOMEMORY
 969  */
 970
 971 /***
 972  *** Rdataset Methods
 973  ***/
 974
 975 /*
 976  * XXXRTH  Should we check for glue and pending data in dns_db_findrdataset()?
 977  */
 978
 979 isc_result_t
 980 dns_db_findrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
 981                     dns_rdatatype_t type, dns_rdatatype_t covers,
 982                     isc_stdtime_t now, dns_rdataset_t *rdataset,
 983                     dns_rdataset_t *sigrdataset);
 984 /*%<
 985  * Search for an rdataset of type 'type' at 'node' that are in version
 986  * 'version' of 'db'.  If found, make 'rdataset' refer to it.
 987  *
 988  * Notes:
 989  *
 990  * \li  If 'version' is NULL, then the current version will be used.
 991  *
 992  * \li  Care must be used when using this routine to build a DNS response:
 993  *      'node' should have been found with dns_db_find(), not
 994  *      dns_db_findnode().  No glue checking is done.  No checking for
 995  *      pending data is done.
 996  *
 997  * \li  The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
 998  *      cache database, an rdataset will not be found unless it expires after
 999  *      'now'.  If 'now' is zero, then the current time will be used.
1000  *
1001  * Requires:
1002  *
1003  * \li  'db' is a valid database.
1004  *
1005  * \li  'node' is a valid node.
1006  *
1007  * \li  'rdataset' is a valid, disassociated rdataset.
1008  *
1009  * \li  'sigrdataset' is a valid, disassociated rdataset, or it is NULL.
1010  *
1011  * \li  If 'covers' != 0, 'type' must be SIG.
1012  *
1013  * \li  'type' is not a meta-RR type such as 'ANY' or 'OPT'.
1014  *
1015  * Ensures:
1016  *
1017  * \li  On success, 'rdataset' is associated with the found rdataset.
1018  *
1019  * Returns:
1020  *
1021  * \li  #ISC_R_SUCCESS
1022  * \li  #ISC_R_NOTFOUND
1023  *
1024  * \li  Other results are possible, depending upon the database
1025  *      implementation used.
1026  */
1027
1028 isc_result_t
1029 dns_db_allrdatasets(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
1030                     isc_stdtime_t now, dns_rdatasetiter_t **iteratorp);
1031 /*%<
1032  * Make '*iteratorp' an rdataset iterator for all rdatasets at 'node' in
1033  * version 'version' of 'db'.
1034  *
1035  * Notes:
1036  *
1037  * \li  If 'version' is NULL, then the current version will be used.
1038  *
1039  * \li  The 'now' field is ignored if 'db' is a zone database.  If 'db' is a
1040  *      cache database, an rdataset will not be found unless it expires after
1041  *      'now'.  Any ANY query will not match unless at least one rdataset at
1042  *      the node expires after 'now'.  If 'now' is zero, then the current time
1043  *      will be used.
1044  *
1045  * Requires:
1046  *
1047  * \li  'db' is a valid database.
1048  *
1049  * \li  'node' is a valid node.
1050  *
1051  * \li  iteratorp != NULL && *iteratorp == NULL
1052  *
1053  * Ensures:
1054  *
1055  * \li  On success, '*iteratorp' is a valid rdataset iterator.
1056  *
1057  * Returns:
1058  *
1059  * \li  #ISC_R_SUCCESS
1060  * \li  #ISC_R_NOTFOUND
1061  *
1062  * \li  Other results are possible, depending upon the database
1063  *      implementation used.
1064  */
1065
1066 isc_result_t
1067 dns_db_addrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version,
1068                    isc_stdtime_t now, dns_rdataset_t *rdataset,
1069                    unsigned int options, dns_rdataset_t *addedrdataset);
1070 /*%<
1071  * Add 'rdataset' to 'node' in version 'version' of 'db'.
1072  *
1073  * Notes:
1074  *
1075  * \li  If the database has zone semantics, the #DNS_DBADD_MERGE option is set,
1076  *      and an rdataset of the same type as 'rdataset' already exists at
1077  *      'node' then the contents of 'rdataset' will be merged with the existing
1078  *      rdataset.  If the option is not set, then rdataset will replace any
1079  *      existing rdataset of the same type.  If not merging and the
1080  *      #DNS_DBADD_FORCE option is set, then the data will update the database
1081  *      without regard to trust levels.  If not forcing the data, then the
1082  *      rdataset will only be added if its trust level is >= the trust level of
1083  *      any existing rdataset.  Forcing is only meaningful for cache databases.
1084  *      If #DNS_DBADD_EXACT is set then there must be no rdata in common between
1085  *      the old and new rdata sets.  If #DNS_DBADD_EXACTTTL is set then both
1086  *      the old and new rdata sets must have the same ttl.
1087  *
1088  * \li  The 'now' field is ignored if 'db' is a zone database.  If 'db' is
1089  *      a cache database, then the added rdataset will expire no later than
1090  *      now + rdataset->ttl.
1091  *
1092  * \li  If 'addedrdataset' is not NULL, then it will be attached to the
1093  *      resulting new rdataset in the database, or to the existing data if
1094  *      the existing data was better.
1095  *
1096  * Requires:
1097  *
1098  * \li  'db' is a valid database.
1099  *
1100  * \li  'node' is a valid node.
1101  *
1102  * \li  'rdataset' is a valid, associated rdataset with the same class
1103  *      as 'db'.
1104  *
1105  * \li  'addedrdataset' is NULL, or a valid, unassociated rdataset.
1106  *
1107  * \li  The database has zone semantics and 'version' is a valid
1108  *      read-write version, or the database has cache semantics
1109  *      and version is NULL.
1110  *
1111  * \li  If the database has cache semantics, the #DNS_DBADD_MERGE option must
1112  *      not be set.
1113  *
1114  * Returns:
1115  *
1116  * \li  #ISC_R_SUCCESS
1117  * \li  #DNS_R_UNCHANGED                        The operation did not change anything.
1118  * \li  #ISC_R_NOMEMORY
1119  * \li  #DNS_R_NOTEXACT
1120  *
1121  * \li  Other results are possible, depending upon the database
1122  *      implementation used.
1123  */
1124
1125 isc_result_t
1126 dns_db_subtractrdataset(dns_db_t *db, dns_dbnode_t *node,
1127                         dns_dbversion_t *version, dns_rdataset_t *rdataset,
1128                         unsigned int options, dns_rdataset_t *newrdataset);
1129 /*%<
1130  * Remove any rdata in 'rdataset' from 'node' in version 'version' of
1131  * 'db'.
1132  *
1133  * Notes:
1134  *
1135  * \li  If 'newrdataset' is not NULL, then it will be attached to the
1136  *      resulting new rdataset in the database, unless the rdataset has
1137  *      become nonexistent.  If DNS_DBSUB_EXACT is set then all elements
1138  *      of 'rdataset' must exist at 'node'.
1139  *
1140  * Requires:
1141  *
1142  * \li  'db' is a valid database.
1143  *
1144  * \li  'node' is a valid node.
1145  *
1146  * \li  'rdataset' is a valid, associated rdataset with the same class
1147  *      as 'db'.
1148  *
1149  * \li  'newrdataset' is NULL, or a valid, unassociated rdataset.
1150  *
1151  * \li  The database has zone semantics and 'version' is a valid
1152  *      read-write version.
1153  *
1154  * Returns:
1155  *
1156  * \li  #ISC_R_SUCCESS
1157  * \li  #DNS_R_UNCHANGED                        The operation did not change anything.
1158  * \li  #DNS_R_NXRRSET                  All rdata of the same type as those
1159  *                                      in 'rdataset' have been deleted.
1160  * \li  #DNS_R_NOTEXACT                 Some part of 'rdataset' did not
1161  *                                      exist and DNS_DBSUB_EXACT was set.
1162  *
1163  * \li  Other results are possible, depending upon the database
1164  *      implementation used.
1165  */
1166
1167 isc_result_t
1168 dns_db_deleterdataset(dns_db_t *db, dns_dbnode_t *node,
1169                       dns_dbversion_t *version, dns_rdatatype_t type,
1170                       dns_rdatatype_t covers);
1171 /*%<
1172  * Make it so that no rdataset of type 'type' exists at 'node' in version
1173  * version 'version' of 'db'.
1174  *
1175  * Notes:
1176  *
1177  * \li  If 'type' is dns_rdatatype_any, then no rdatasets will exist in
1178  *      'version' (provided that the dns_db_deleterdataset() isn't followed
1179  *      by one or more dns_db_addrdataset() calls).
1180  *
1181  * Requires:
1182  *
1183  * \li  'db' is a valid database.
1184  *
1185  * \li  'node' is a valid node.
1186  *
1187  * \li  The database has zone semantics and 'version' is a valid
1188  *      read-write version, or the database has cache semantics
1189  *      and version is NULL.
1190  *
1191  * \li  'type' is not a meta-RR type, except for dns_rdatatype_any, which is
1192  *      allowed.
1193  *
1194  * \li  If 'covers' != 0, 'type' must be SIG.
1195  *
1196  * Returns:
1197  *
1198  * \li  #ISC_R_SUCCESS
1199  * \li  #DNS_R_UNCHANGED                        No rdatasets of 'type' existed before
1200  *                                      the operation was attempted.
1201  *
1202  * \li  Other results are possible, depending upon the database
1203  *      implementation used.
1204  */
1205
1206 isc_result_t
1207 dns_db_getsoaserial(dns_db_t *db, dns_dbversion_t *ver, isc_uint32_t *serialp);
1208 /*%<
1209  * Get the current SOA serial number from a zone database.
1210  *
1211  * Requires:
1212  * \li  'db' is a valid database with zone semantics.
1213  * \li  'ver' is a valid version.
1214  */
1215
1216 void
1217 dns_db_overmem(dns_db_t *db, isc_boolean_t overmem);
1218 /*%<
1219  * Enable / disable aggressive cache cleaning.
1220  */
1221
1222 unsigned int
1223 dns_db_nodecount(dns_db_t *db);
1224 /*%<
1225  * Count the number of nodes in 'db'.
1226  *
1227  * Requires:
1228  *
1229  * \li  'db' is a valid database.
1230  *
1231  * Returns:
1232  * \li  The number of nodes in the database
1233  */
1234
1235 void
1236 dns_db_settask(dns_db_t *db, isc_task_t *task);
1237 /*%<
1238  * If task is set then the final detach maybe performed asynchronously.
1239  *
1240  * Requires:
1241  * \li  'db' is a valid database.
1242  * \li  'task' to be valid or NULL.
1243  */
1244
1245 isc_boolean_t
1246 dns_db_ispersistent(dns_db_t *db);
1247 /*%<
1248  * Is 'db' persistent?  A persistent database does not need to be loaded
1249  * from disk or written to disk.
1250  *
1251  * Requires:
1252  *
1253  * \li  'db' is a valid database.
1254  *
1255  * Returns:
1256  * \li  #ISC_TRUE       'db' is persistent.
1257  * \li  #ISC_FALSE      'db' is not persistent.
1258  */
1259
1260 isc_result_t
1261 dns_db_register(const char *name, dns_dbcreatefunc_t create, void *driverarg,
1262                 isc_mem_t *mctx, dns_dbimplementation_t **dbimp);
1263
1264 /*%<
1265  * Register a new database implementation and add it to the list of
1266  * supported implementations.
1267  *
1268  * Requires:
1269  *
1270  * \li  'name' is not NULL
1271  * \li  'order' is a valid function pointer
1272  * \li  'mctx' is a valid memory context
1273  * \li  dbimp != NULL && *dbimp == NULL
1274  *
1275  * Returns:
1276  * \li  #ISC_R_SUCCESS  The registration succeeded
1277  * \li  #ISC_R_NOMEMORY Out of memory
1278  * \li  #ISC_R_EXISTS   A database implementation with the same name exists
1279  *
1280  * Ensures:
1281  *
1282  * \li  *dbimp points to an opaque structure which must be passed to
1283  *      dns_db_unregister().
1284  */
1285
1286 void
1287 dns_db_unregister(dns_dbimplementation_t **dbimp);
1288 /*%<
1289  * Remove a database implementation from the list of supported
1290  * implementations.  No databases of this type can be active when this
1291  * is called.
1292  *
1293  * Requires:
1294  * \li  dbimp != NULL && *dbimp == NULL
1295  *
1296  * Ensures:
1297  *
1298  * \li  Any memory allocated in *dbimp will be freed.
1299  */
1300
1301 isc_result_t
1302 dns_db_getoriginnode(dns_db_t *db, dns_dbnode_t **nodep);
1303 /*%<
1304  * Get the origin DB node corresponding to the DB's zone.  This function
1305  * should typically succeed unless the underlying DB implementation doesn't
1306  * support the feature.
1307  *
1308  * Requires:
1309  *
1310  * \li  'db' is a valid zone database.
1311  * \li  'nodep' != NULL && '*nodep' == NULL
1312  *
1313  * Ensures:
1314  * \li  On success, '*nodep' will point to the DB node of the zone's origin.
1315  *
1316  * Returns:
1317  * \li  #ISC_R_SUCCESS
1318  * \li  #ISC_R_NOTFOUND - the DB implementation does not support this feature.
1319  */
1320
1321 dns_stats_t *
1322 dns_db_getrrsetstats(dns_db_t *db);
1323 /*%<
1324  * Get statistics information counting RRsets stored in the DB, when available.
1325  * The statistics may not be available depending on the DB implementation.
1326  *
1327  * Requires:
1328  *
1329  * \li  'db' is a valid database (zone or cache).
1330  *
1331  * Returns:
1332  * \li  when available, a pointer to a statistics object created by
1333  *      dns_rdatasetstats_create(); otherwise NULL.
1334  */
1335
1336 ISC_LANG_ENDDECLS
1337
1338 #endif /* DNS_DB_H */