Import bind 9.5.2 vendor sources.
[dragonfly.git] / 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 */