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