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

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