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