contrib/bind9/lib/dns/include/dns/masterdump.h

   1 /*
   2  * Copyright (C) 2004-2008, 2011, 2013  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2002  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: masterdump.h,v 1.47 2011/12/08 23:46:49 tbox Exp $ */
  19
  20 #ifndef DNS_MASTERDUMP_H
  21 #define DNS_MASTERDUMP_H 1
  22
  23 /*! \file dns/masterdump.h */
  24
  25 /***
  26  ***    Imports
  27  ***/
  28
  29 #include <stdio.h>
  30
  31 #include <isc/lang.h>
  32
  33 #include <dns/types.h>
  34
  35 /***
  36  *** Types
  37  ***/
  38
  39 typedef struct dns_master_style dns_master_style_t;
  40
  41 /***
  42  *** Definitions
  43  ***/
  44
  45 /*
  46  * Flags affecting master file formatting.  Flags 0x0000FFFF
  47  * define the formatting of the rdata part and are defined in
  48  * rdata.h.
  49  */
  50
  51 /*% Omit the owner name when possible. */
  52 #define DNS_STYLEFLAG_OMIT_OWNER        0x00010000U
  53
  54 /*%
  55  * Omit the TTL when possible.  If DNS_STYLEFLAG_TTL is
  56  * also set, this means no TTLs are ever printed
  57  * because $TTL directives are generated before every
  58  * change in the TTL.  In this case, no columns need to
  59  * be reserved for the TTL.  Master files generated with
  60  * these options will be rejected by BIND 4.x because it
  61  * does not recognize the $TTL directive.
  62  *
  63  * If DNS_STYLEFLAG_TTL is not also set, the TTL will be
  64  * omitted when it is equal to the previous TTL.
  65  * This is correct according to RFC1035, but the
  66  * TTLs may be silently misinterpreted by older
  67  * versions of BIND which use the SOA MINTTL as a
  68  * default TTL value.
  69  */
  70 #define DNS_STYLEFLAG_OMIT_TTL          0x00020000U
  71
  72 /*% Omit the class when possible. */
  73 #define DNS_STYLEFLAG_OMIT_CLASS        0x00040000U
  74
  75 /*% Output $TTL directives. */
  76 #define DNS_STYLEFLAG_TTL               0x00080000U
  77
  78 /*%
  79  * Output $ORIGIN directives and print owner names relative to
  80  * the origin when possible.
  81  */
  82 #define DNS_STYLEFLAG_REL_OWNER         0x00100000U
  83
  84 /*% Print domain names in RR data in relative form when possible.
  85    For this to take effect, DNS_STYLEFLAG_REL_OWNER must also be set. */
  86 #define DNS_STYLEFLAG_REL_DATA          0x00200000U
  87
  88 /*% Print the trust level of each rdataset. */
  89 #define DNS_STYLEFLAG_TRUST             0x00400000U
  90
  91 /*% Print negative caching entries. */
  92 #define DNS_STYLEFLAG_NCACHE            0x00800000U
  93
  94 /*% Never print the TTL. */
  95 #define DNS_STYLEFLAG_NO_TTL            0x01000000U
  96
  97 /*% Never print the CLASS. */
  98 #define DNS_STYLEFLAG_NO_CLASS          0x02000000U
  99
 100 /*% Report re-signing time. */
 101 #define DNS_STYLEFLAG_RESIGN            0x04000000U
 102
 103 ISC_LANG_BEGINDECLS
 104
 105 /***
 106  ***    Constants
 107  ***/
 108
 109 /*%
 110  * The default master file style.
 111  *
 112  * This uses $TTL directives to avoid the need to dedicate a
 113  * tab stop for the TTL.  The class is only printed for the first
 114  * rrset in the file and shares a tab stop with the RR type.
 115  */
 116 LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_default;
 117
 118 /*%
 119  * A master file style that dumps zones to a very generic format easily
 120  * imported/checked with external tools.
 121  */
 122 LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_full;
 123
 124 /*%
 125  * A master file style that prints explicit TTL values on each
 126  * record line, never using $TTL statements.  The TTL has a tab
 127  * stop of its own, but the class and type share one.
 128  */
 129 LIBDNS_EXTERNAL_DATA extern const dns_master_style_t
 130                                         dns_master_style_explicitttl;
 131
 132 /*%
 133  * A master style format designed for cache files.  It prints explicit TTL
 134  * values on each record line and never uses $ORIGIN or relative names.
 135  */
 136 LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_cache;
 137
 138 /*%
 139  * A master style that prints name, ttl, class, type, and value on
 140  * every line.  Similar to explicitttl above, but more verbose.
 141  * Intended for generating master files which can be easily parsed
 142  * by perl scripts and similar applications.
 143  */
 144 LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_simple;
 145
 146 /*%
 147  * The style used for debugging, "dig" output, etc.
 148  */
 149 LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_debug;
 150
 151 /*%
 152  * The style used for dumping "key" zones.
 153  */
 154 LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_keyzone;
 155
 156 /***
 157  ***    Functions
 158  ***/
 159
 160 void
 161 dns_dumpctx_attach(dns_dumpctx_t *source, dns_dumpctx_t **target);
 162 /*%<
 163  * Attach to a dump context.
 164  *
 165  * Require:
 166  *\li   'source' to be valid.
 167  *\li   'target' to be non NULL and '*target' to be NULL.
 168  */
 169
 170 void
 171 dns_dumpctx_detach(dns_dumpctx_t **dctxp);
 172 /*%<
 173  * Detach from a dump context.
 174  *
 175  * Require:
 176  *\li   'dctxp' to point to a valid dump context.
 177  *
 178  * Ensures:
 179  *\li   '*dctxp' is NULL.
 180  */
 181
 182 void
 183 dns_dumpctx_cancel(dns_dumpctx_t *dctx);
 184 /*%<
 185  * Cancel a in progress dump.
 186  *
 187  * Require:
 188  *\li   'dctx' to be valid.
 189  */
 190
 191 dns_dbversion_t *
 192 dns_dumpctx_version(dns_dumpctx_t *dctx);
 193 /*%<
 194  * Return the version handle (if any) of the database being dumped.
 195  *
 196  * Require:
 197  *\li   'dctx' to be valid.
 198  */
 199
 200 dns_db_t *
 201 dns_dumpctx_db(dns_dumpctx_t *dctx);
 202 /*%<
 203  * Return the database being dumped.
 204  *
 205  * Require:
 206  *\li   'dctx' to be valid.
 207  */
 208
 209
 210 /*@{*/
 211 isc_result_t
 212 dns_master_dumptostreaminc(isc_mem_t *mctx, dns_db_t *db,
 213                            dns_dbversion_t *version,
 214                            const dns_master_style_t *style, FILE *f,
 215                            isc_task_t *task, dns_dumpdonefunc_t done,
 216                            void *done_arg, dns_dumpctx_t **dctxp);
 217
 218 isc_result_t
 219 dns_master_dumptostream(isc_mem_t *mctx, dns_db_t *db,
 220                         dns_dbversion_t *version,
 221                         const dns_master_style_t *style, FILE *f);
 222
 223 isc_result_t
 224 dns_master_dumptostream2(isc_mem_t *mctx, dns_db_t *db,
 225                          dns_dbversion_t *version,
 226                          const dns_master_style_t *style,
 227                          dns_masterformat_t format, FILE *f);
 228
 229 isc_result_t
 230 dns_master_dumptostream3(isc_mem_t *mctx, dns_db_t *db,
 231                          dns_dbversion_t *version,
 232                          const dns_master_style_t *style,
 233                          dns_masterformat_t format,
 234                          dns_masterrawheader_t *header, FILE *f);
 235 /*%<
 236  * Dump the database 'db' to the steam 'f' in the specified format by
 237  * 'format'.  If the format is dns_masterformat_text (the RFC1035 format),
 238  * 'style' specifies the file style (e.g., &dns_master_style_default).
 239  *
 240  * dns_master_dumptostream() is an old form of dns_master_dumptostream3(),
 241  * which always specifies the dns_masterformat_text format.
 242  * dns_master_dumptostream2() is an old form which always specifies
 243  * a NULL header.
 244  *
 245  * If 'format' is dns_masterformat_raw, then 'header' can contain
 246  * information to be written to the file header.
 247  *
 248  * Temporary dynamic memory may be allocated from 'mctx'.
 249  *
 250  * Require:
 251  *\li   'task' to be valid.
 252  *\li   'done' to be non NULL.
 253  *\li   'dctxp' to be non NULL && '*dctxp' to be NULL.
 254  *
 255  * Returns:
 256  *\li   ISC_R_SUCCESS
 257  *\li   ISC_R_CONTINUE  dns_master_dumptostreaminc() only.
 258  *\li   ISC_R_NOMEMORY
 259  *\li   Any database or rrset iterator error.
 260  *\li   Any dns_rdata_totext() error code.
 261  */
 262 /*@}*/
 263
 264 /*@{*/
 265 isc_result_t
 266 dns_master_dumpinc(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version,
 267                    const dns_master_style_t *style, const char *filename,
 268                    isc_task_t *task, dns_dumpdonefunc_t done, void *done_arg,
 269                    dns_dumpctx_t **dctxp);
 270
 271 isc_result_t
 272 dns_master_dumpinc2(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version,
 273                     const dns_master_style_t *style, const char *filename,
 274                     isc_task_t *task, dns_dumpdonefunc_t done, void *done_arg,                      dns_dumpctx_t **dctxp, dns_masterformat_t format);
 275
 276 isc_result_t
 277 dns_master_dumpinc3(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version,
 278                     const dns_master_style_t *style, const char *filename,
 279                     isc_task_t *task, dns_dumpdonefunc_t done, void
 280                     *done_arg, dns_dumpctx_t **dctxp,
 281                     dns_masterformat_t format, dns_masterrawheader_t *header);
 282
 283 isc_result_t
 284 dns_master_dump(isc_mem_t *mctx, dns_db_t *db,
 285                 dns_dbversion_t *version,
 286                 const dns_master_style_t *style, const char *filename);
 287
 288 isc_result_t
 289 dns_master_dump2(isc_mem_t *mctx, dns_db_t *db,
 290                  dns_dbversion_t *version,
 291                  const dns_master_style_t *style, const char *filename,
 292                  dns_masterformat_t format);
 293
 294 isc_result_t
 295 dns_master_dump3(isc_mem_t *mctx, dns_db_t *db,
 296                  dns_dbversion_t *version,
 297                  const dns_master_style_t *style, const char *filename,
 298                  dns_masterformat_t format, dns_masterrawheader_t *header);
 299
 300 /*%<
 301  * Dump the database 'db' to the file 'filename' in the specified format by
 302  * 'format'.  If the format is dns_masterformat_text (the RFC1035 format),
 303  * 'style' specifies the file style (e.g., &dns_master_style_default).
 304  *
 305  * dns_master_dumpinc() and dns_master_dump() are old forms of _dumpinc3()
 306  * and _dump3(), respectively, which always specify the dns_masterformat_text
 307  * format.  dns_master_dumpinc2() and dns_master_dump2() are old forms which
 308  * always specify a NULL header.
 309  *
 310  * If 'format' is dns_masterformat_raw, then 'header' can contain
 311  * information to be written to the file header.
 312  *
 313  * Temporary dynamic memory may be allocated from 'mctx'.
 314  *
 315  * Returns:
 316  *\li   ISC_R_SUCCESS
 317  *\li   ISC_R_CONTINUE  dns_master_dumpinc() only.
 318  *\li   ISC_R_NOMEMORY
 319  *\li   Any database or rrset iterator error.
 320  *\li   Any dns_rdata_totext() error code.
 321  */
 322 /*@}*/
 323
 324 isc_result_t
 325 dns_master_rdatasettotext(dns_name_t *owner_name,
 326                           dns_rdataset_t *rdataset,
 327                           const dns_master_style_t *style,
 328                           isc_buffer_t *target);
 329 /*%<
 330  * Convert 'rdataset' to text format, storing the result in 'target'.
 331  *
 332  * Notes:
 333  *\li   The rdata cursor position will be changed.
 334  *
 335  * Requires:
 336  *\li   'rdataset' is a valid non-question rdataset.
 337  *
 338  *\li   'rdataset' is not empty.
 339  */
 340
 341 isc_result_t
 342 dns_master_questiontotext(dns_name_t *owner_name,
 343                           dns_rdataset_t *rdataset,
 344                           const dns_master_style_t *style,
 345                           isc_buffer_t *target);
 346
 347 isc_result_t
 348 dns_master_dumpnodetostream(isc_mem_t *mctx, dns_db_t *db,
 349                             dns_dbversion_t *version,
 350                             dns_dbnode_t *node, dns_name_t *name,
 351                             const dns_master_style_t *style,
 352                             FILE *f);
 353
 354 isc_result_t
 355 dns_master_dumpnode(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version,
 356                     dns_dbnode_t *node, dns_name_t *name,
 357                     const dns_master_style_t *style, const char *filename);
 358
 359 isc_result_t
 360 dns_master_stylecreate(dns_master_style_t **style, unsigned int flags,
 361                        unsigned int ttl_column, unsigned int class_column,
 362                        unsigned int type_column, unsigned int rdata_column,
 363                        unsigned int line_length, unsigned int tab_width,
 364                        isc_mem_t *mctx);
 365
 366 isc_result_t
 367 dns_master_stylecreate2(dns_master_style_t **style, unsigned int flags,
 368                        unsigned int ttl_column, unsigned int class_column,
 369                        unsigned int type_column, unsigned int rdata_column,
 370                        unsigned int line_length, unsigned int tab_width,
 371                        unsigned int split_width, isc_mem_t *mctx);
 372 void
 373 dns_master_styledestroy(dns_master_style_t **style, isc_mem_t *mctx);
 374
 375 ISC_LANG_ENDDECLS
 376
 377 #endif /* DNS_MASTERDUMP_H */