/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
 39typedef 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
103ISC_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 */
116LIBDNS_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 */
122LIBDNS_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 */
129LIBDNS_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 */
136LIBDNS_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 */
144LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_simple;
145
146/*%
147 * The style used for debugging, "dig" output, etc.
148 */
149LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_debug;
150
151/***
152 ***	Functions
153 ***/
154
155void
156dns_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
165void
166dns_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
177void
178dns_dumpctx_cancel(dns_dumpctx_t *dctx);
179/*%<
180 * Cancel a in progress dump.
181 *
182 * Require:
183 *\li	'dctx' to be valid.
184 */
185
186dns_dbversion_t *
187dns_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
195dns_db_t *
196dns_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/*@{*/
206isc_result_t
207dns_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
213isc_result_t
214dns_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
218isc_result_t
219dns_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/*@{*/
248isc_result_t
249dns_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
254isc_result_t
255dns_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
259isc_result_t
260dns_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
264isc_result_t
265dns_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
290isc_result_t
291dns_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
307isc_result_t
308dns_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
313isc_result_t
314dns_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
320isc_result_t
321dns_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
325isc_result_t
326dns_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
332void
333dns_master_styledestroy(dns_master_style_t **style, isc_mem_t *mctx);
334
335ISC_LANG_ENDDECLS
336
337#endif /* DNS_MASTERDUMP_H */