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

   1 /*
   2  * Copyright (C) 2004-2008, 2011, 2012  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$ */
  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  ***    Functions
 153  ***/
 154
 155 void
 156 dns_dumpctx_attach(dns_dumpctx_t *source, dns_dumpctx_t **target);
 157 /*%<
 158  * Attach to a dump context.
 159  *
 160  * Require:
 161  *\li   'source' to be valid.
 162  *\li   'target' to be non NULL and '*target' to be NULL.
 163  */
 164
 165 void
 166 dns_dumpctx_detach(dns_dumpctx_t **dctxp);
 167 /*%<
 168  * Detach from a dump context.
 169  *
 170  * Require:
 171  *\li   'dctxp' to point to a valid dump context.
 172  *
 173  * Ensures:
 174  *\li   '*dctxp' is NULL.
 175  */
 176
 177 void
 178 dns_dumpctx_cancel(dns_dumpctx_t *dctx);
 179 /*%<
 180  * Cancel a in progress dump.
 181  *
 182  * Require:
 183  *\li   'dctx' to be valid.
 184  */
 185
 186 dns_dbversion_t *
 187 dns_dumpctx_version(dns_dumpctx_t *dctx);
 188 /*%<
 189  * Return the version handle (if any) of the database being dumped.
 190  *
 191  * Require:
 192  *\li   'dctx' to be valid.
 193  */
 194
 195 dns_db_t *
 196 dns_dumpctx_db(dns_dumpctx_t *dctx);
 197 /*%<
 198  * Return the database being dumped.
 199  *
 200  * Require:
 201  *\li   'dctx' to be valid.
 202  */
 203
 204
 205 /*@{*/
 206 isc_result_t
 207 dns_master_dumptostreaminc(isc_mem_t *mctx, dns_db_t *db,
 208                            dns_dbversion_t *version,
 209                            const dns_master_style_t *style, FILE *f,
 210                            isc_task_t *task, dns_dumpdonefunc_t done,
 211                            void *done_arg, dns_dumpctx_t **dctxp);
 212
 213 isc_result_t
 214 dns_master_dumptostream(isc_mem_t *mctx, dns_db_t *db,
 215                         dns_dbversion_t *version,
 216                         const dns_master_style_t *style, FILE *f);
 217
 218 isc_result_t
 219 dns_master_dumptostream2(isc_mem_t *mctx, dns_db_t *db,
 220                          dns_dbversion_t *version,
 221                          const dns_master_style_t *style,
 222                          dns_masterformat_t format, FILE *f);
 223 /*%<
 224  * Dump the database 'db' to the steam 'f' in the specified format by
 225  * 'format'.  If the format is dns_masterformat_text (the RFC1035 format),
 226  * 'style' specifies the file style (e.g., &dns_master_style_default).
 227  *
 228  * dns_master_dumptostream() is an old form of dns_master_dumptostream2(),
 229  * which always specifies the dns_masterformat_text format.
 230  *
 231  * Temporary dynamic memory may be allocated from 'mctx'.
 232  *
 233  * Require:
 234  *\li   'task' to be valid.
 235  *\li   'done' to be non NULL.
 236  *\li   'dctxp' to be non NULL && '*dctxp' to be NULL.
 237  *
 238  * Returns:
 239  *\li   ISC_R_SUCCESS
 240  *\li   ISC_R_CONTINUE  dns_master_dumptostreaminc() only.
 241  *\li   ISC_R_NOMEMORY
 242  *\li   Any database or rrset iterator error.
 243  *\li   Any dns_rdata_totext() error code.
 244  */
 245 /*@}*/
 246
 247 /*@{*/
 248 isc_result_t
 249 dns_master_dumpinc(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version,
 250                    const dns_master_style_t *style, const char *filename,
 251                    isc_task_t *task, dns_dumpdonefunc_t done, void *done_arg,
 252                    dns_dumpctx_t **dctxp);
 253
 254 isc_result_t
 255 dns_master_dumpinc2(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version,
 256                     const dns_master_style_t *style, const char *filename,
 257                     isc_task_t *task, dns_dumpdonefunc_t done, void *done_arg,                      dns_dumpctx_t **dctxp, dns_masterformat_t format);
 258
 259 isc_result_t
 260 dns_master_dump(isc_mem_t *mctx, dns_db_t *db,
 261                 dns_dbversion_t *version,
 262                 const dns_master_style_t *style, const char *filename);
 263
 264 isc_result_t
 265 dns_master_dump2(isc_mem_t *mctx, dns_db_t *db,
 266                  dns_dbversion_t *version,
 267                  const dns_master_style_t *style, const char *filename,
 268                  dns_masterformat_t format);
 269
 270 /*%<
 271  * Dump the database 'db' to the file 'filename' in the specified format by
 272  * 'format'.  If the format is dns_masterformat_text (the RFC1035 format),
 273  * 'style' specifies the file style (e.g., &dns_master_style_default).
 274  *
 275  * dns_master_dumpinc() and dns_master_dump() are old forms of _dumpinc2()
 276  * and _dump2(), respectively, which always specify the dns_masterformat_text
 277  * format.
 278  *
 279  * Temporary dynamic memory may be allocated from 'mctx'.
 280  *
 281  * Returns:
 282  *\li   ISC_R_SUCCESS
 283  *\li   ISC_R_CONTINUE  dns_master_dumpinc() only.
 284  *\li   ISC_R_NOMEMORY
 285  *\li   Any database or rrset iterator error.
 286  *\li   Any dns_rdata_totext() error code.
 287  */
 288 /*@}*/
 289
 290 isc_result_t
 291 dns_master_rdatasettotext(dns_name_t *owner_name,
 292                           dns_rdataset_t *rdataset,
 293                           const dns_master_style_t *style,
 294                           isc_buffer_t *target);
 295 /*%<
 296  * Convert 'rdataset' to text format, storing the result in 'target'.
 297  *
 298  * Notes:
 299  *\li   The rdata cursor position will be changed.
 300  *
 301  * Requires:
 302  *\li   'rdataset' is a valid non-question rdataset.
 303  *
 304  *\li   'rdataset' is not empty.
 305  */
 306
 307 isc_result_t
 308 dns_master_questiontotext(dns_name_t *owner_name,
 309                           dns_rdataset_t *rdataset,
 310                           const dns_master_style_t *style,
 311                           isc_buffer_t *target);
 312
 313 isc_result_t
 314 dns_master_dumpnodetostream(isc_mem_t *mctx, dns_db_t *db,
 315                             dns_dbversion_t *version,
 316                             dns_dbnode_t *node, dns_name_t *name,
 317                             const dns_master_style_t *style,
 318                             FILE *f);
 319
 320 isc_result_t
 321 dns_master_dumpnode(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version,
 322                     dns_dbnode_t *node, dns_name_t *name,
 323                     const dns_master_style_t *style, const char *filename);
 324
 325 isc_result_t
 326 dns_master_stylecreate(dns_master_style_t **style, unsigned int flags,
 327                        unsigned int ttl_column, unsigned int class_column,
 328                        unsigned int type_column, unsigned int rdata_column,
 329                        unsigned int line_length, unsigned int tab_width,
 330                        isc_mem_t *mctx);
 331
 332 void
 333 dns_master_styledestroy(dns_master_style_t **style, isc_mem_t *mctx);
 334
 335 ISC_LANG_ENDDECLS
 336
 337 #endif /* DNS_MASTERDUMP_H */