contrib/bind-9.5.2/lib/dns/include/dns/masterdump.h

   1 /*
   2  * Copyright (C) 2004-2007  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.39 2007/06/19 23:47:17 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 ISC_LANG_BEGINDECLS
 101
 102 /***
 103  ***    Constants
 104  ***/
 105
 106 /*%
 107  * The default master file style.
 108  *
 109  * This uses $TTL directives to avoid the need to dedicate a
 110  * tab stop for the TTL.  The class is only printed for the first
 111  * rrset in the file and shares a tab stop with the RR type.
 112  */
 113 LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_default;
 114
 115 /*%
 116  * A master file style that dumps zones to a very generic format easily
 117  * imported/checked with external tools.
 118  */
 119 LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_full;
 120
 121 /*%
 122  * A master file style that prints explicit TTL values on each
 123  * record line, never using $TTL statements.  The TTL has a tab
 124  * stop of its own, but the class and type share one.
 125  */
 126 LIBDNS_EXTERNAL_DATA extern const dns_master_style_t
 127                                         dns_master_style_explicitttl;
 128
 129 /*%
 130  * A master style format designed for cache files.  It prints explicit TTL
 131  * values on each record line and never uses $ORIGIN or relative names.
 132  */
 133 LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_cache;
 134
 135 /*%
 136  * A master style that prints name, ttl, class, type, and value on
 137  * every line.  Similar to explicitttl above, but more verbose.
 138  * Intended for generating master files which can be easily parsed
 139  * by perl scripts and similar applications.
 140  */
 141 LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_simple;
 142
 143 /*%
 144  * The style used for debugging, "dig" output, etc.
 145  */
 146 LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_debug;
 147
 148 /***
 149  ***    Functions
 150  ***/
 151
 152 void
 153 dns_dumpctx_attach(dns_dumpctx_t *source, dns_dumpctx_t **target);
 154 /*%<
 155  * Attach to a dump context.
 156  *
 157  * Require:
 158  *\li   'source' to be valid.
 159  *\li   'target' to be non NULL and '*target' to be NULL.
 160  */
 161
 162 void
 163 dns_dumpctx_detach(dns_dumpctx_t **dctxp);
 164 /*%<
 165  * Detach from a dump context.
 166  *
 167  * Require:
 168  *\li   'dctxp' to point to a valid dump context.
 169  *
 170  * Ensures:
 171  *\li   '*dctxp' is NULL.
 172  */
 173
 174 void
 175 dns_dumpctx_cancel(dns_dumpctx_t *dctx);
 176 /*%<
 177  * Cancel a in progress dump.
 178  *
 179  * Require:
 180  *\li   'dctx' to be valid.
 181  */
 182
 183 dns_dbversion_t *
 184 dns_dumpctx_version(dns_dumpctx_t *dctx);
 185 /*%<
 186  * Return the version handle (if any) of the database being dumped.
 187  *
 188  * Require:
 189  *\li   'dctx' to be valid.
 190  */
 191
 192 dns_db_t *
 193 dns_dumpctx_db(dns_dumpctx_t *dctx);
 194 /*%<
 195  * Return the database being dumped.
 196  *
 197  * Require:
 198  *\li   'dctx' to be valid.
 199  */
 200
 201
 202 /*@{*/
 203 isc_result_t
 204 dns_master_dumptostreaminc(isc_mem_t *mctx, dns_db_t *db,
 205                            dns_dbversion_t *version,
 206                            const dns_master_style_t *style, FILE *f,
 207                            isc_task_t *task, dns_dumpdonefunc_t done,
 208                            void *done_arg, dns_dumpctx_t **dctxp);
 209
 210 isc_result_t
 211 dns_master_dumptostream(isc_mem_t *mctx, dns_db_t *db,
 212                         dns_dbversion_t *version,
 213                         const dns_master_style_t *style, FILE *f);
 214
 215 isc_result_t
 216 dns_master_dumptostream2(isc_mem_t *mctx, dns_db_t *db,
 217                          dns_dbversion_t *version,
 218                          const dns_master_style_t *style,
 219                          dns_masterformat_t format, FILE *f);
 220 /*%<
 221  * Dump the database 'db' to the steam 'f' in the specified format by
 222  * 'format'.  If the format is dns_masterformat_text (the RFC1035 format),
 223  * 'style' specifies the file style (e.g., &dns_master_style_default).
 224  *
 225  * dns_master_dumptostream() is an old form of dns_master_dumptostream2(),
 226  * which always specifies the dns_masterformat_text format.
 227  *
 228  * Temporary dynamic memory may be allocated from 'mctx'.
 229  *
 230  * Require:
 231  *\li   'task' to be valid.
 232  *\li   'done' to be non NULL.
 233  *\li   'dctxp' to be non NULL && '*dctxp' to be NULL.
 234  *
 235  * Returns:
 236  *\li   ISC_R_SUCCESS
 237  *\li   ISC_R_CONTINUE  dns_master_dumptostreaminc() only.
 238  *\li   ISC_R_NOMEMORY
 239  *\li   Any database or rrset iterator error.
 240  *\li   Any dns_rdata_totext() error code.
 241  */
 242 /*@}*/
 243
 244 /*@{*/
 245 isc_result_t
 246 dns_master_dumpinc(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version,
 247                    const dns_master_style_t *style, const char *filename,
 248                    isc_task_t *task, dns_dumpdonefunc_t done, void *done_arg,
 249                    dns_dumpctx_t **dctxp);
 250
 251 isc_result_t
 252 dns_master_dumpinc2(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version,
 253                     const dns_master_style_t *style, const char *filename,
 254                     isc_task_t *task, dns_dumpdonefunc_t done, void *done_arg,                      dns_dumpctx_t **dctxp, dns_masterformat_t format);
 255
 256 isc_result_t
 257 dns_master_dump(isc_mem_t *mctx, dns_db_t *db,
 258                 dns_dbversion_t *version,
 259                 const dns_master_style_t *style, const char *filename);
 260
 261 isc_result_t
 262 dns_master_dump2(isc_mem_t *mctx, dns_db_t *db,
 263                  dns_dbversion_t *version,
 264                  const dns_master_style_t *style, const char *filename,
 265                  dns_masterformat_t format);
 266
 267 /*%<
 268  * Dump the database 'db' to the file 'filename' in the specified format by
 269  * 'format'.  If the format is dns_masterformat_text (the RFC1035 format),
 270  * 'style' specifies the file style (e.g., &dns_master_style_default).
 271  *
 272  * dns_master_dumpinc() and dns_master_dump() are old forms of _dumpinc2()
 273  * and _dump2(), respectively, which always specify the dns_masterformat_text
 274  * format.
 275  *
 276  * Temporary dynamic memory may be allocated from 'mctx'.
 277  *
 278  * Returns:
 279  *\li   ISC_R_SUCCESS
 280  *\li   ISC_R_CONTINUE  dns_master_dumpinc() only.
 281  *\li   ISC_R_NOMEMORY
 282  *\li   Any database or rrset iterator error.
 283  *\li   Any dns_rdata_totext() error code.
 284  */
 285 /*@}*/
 286
 287 isc_result_t
 288 dns_master_rdatasettotext(dns_name_t *owner_name,
 289                           dns_rdataset_t *rdataset,
 290                           const dns_master_style_t *style,
 291                           isc_buffer_t *target);
 292 /*%<
 293  * Convert 'rdataset' to text format, storing the result in 'target'.
 294  *
 295  * Notes:
 296  *\li   The rdata cursor position will be changed.
 297  *
 298  * Requires:
 299  *\li   'rdataset' is a valid non-question rdataset.
 300  *
 301  *\li   'rdataset' is not empty.
 302  */
 303
 304 isc_result_t
 305 dns_master_questiontotext(dns_name_t *owner_name,
 306                           dns_rdataset_t *rdataset,
 307                           const dns_master_style_t *style,
 308                           isc_buffer_t *target);
 309
 310 isc_result_t
 311 dns_master_dumpnodetostream(isc_mem_t *mctx, dns_db_t *db,
 312                             dns_dbversion_t *version,
 313                             dns_dbnode_t *node, dns_name_t *name,
 314                             const dns_master_style_t *style,
 315                             FILE *f);
 316
 317 isc_result_t
 318 dns_master_dumpnode(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version,
 319                     dns_dbnode_t *node, dns_name_t *name,
 320                     const dns_master_style_t *style, const char *filename);
 321
 322 isc_result_t
 323 dns_master_stylecreate(dns_master_style_t **style, unsigned int flags,
 324                        unsigned int ttl_column, unsigned int class_column,
 325                        unsigned int type_column, unsigned int rdata_column,
 326                        unsigned int line_length, unsigned int tab_width,
 327                        isc_mem_t *mctx);
 328
 329 void
 330 dns_master_styledestroy(dns_master_style_t **style, isc_mem_t *mctx);
 331
 332 ISC_LANG_ENDDECLS
 333
 334 #endif /* DNS_MASTERDUMP_H */