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