BIND9 Internals: lib/dns/include/dns/master.h Source File

00001 /*
00002  * Copyright (C) 2004-2009, 2011-2014  Internet Systems Consortium, Inc. ("ISC")
00003  * Copyright (C) 1999-2002  Internet Software Consortium.
00004  *
00005  * Permission to use, copy, modify, and/or distribute this software for any
00006  * purpose with or without fee is hereby granted, provided that the above
00007  * copyright notice and this permission notice appear in all copies.
00008  *
00009  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
00010  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
00011  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
00012  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
00013  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
00014  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
00015  * PERFORMANCE OF THIS SOFTWARE.
00016  */
00017 
00018 /* $Id: master.h,v 1.57.8.1 2012/02/07 00:44:16 each Exp $ */
00019 
00020 #ifndef DNS_MASTER_H
00021 #define DNS_MASTER_H 1
00022 
00023 /*! \file dns/master.h */
00024 
00025 /***
00026  ***    Imports
00027  ***/
00028 
00029 #include <stdio.h>
00030 
00031 #include <isc/lang.h>
00032 
00033 #include <dns/types.h>
00034 
00035 /*
00036  * Flags to be passed in the 'options' argument in the functions below.
00037  */
00038 #define DNS_MASTER_AGETTL       0x00000001      /*%< Age the ttl based on $DATE. */
00039 #define DNS_MASTER_MANYERRORS   0x00000002      /*%< Continue processing on errors. */
00040 #define DNS_MASTER_NOINCLUDE    0x00000004      /*%< Disallow $INCLUDE directives. */
00041 #define DNS_MASTER_ZONE         0x00000008      /*%< Loading a zone master file. */
00042 #define DNS_MASTER_HINT         0x00000010      /*%< Loading a hint master file. */
00043 #define DNS_MASTER_SLAVE        0x00000020      /*%< Loading a slave master file. */
00044 #define DNS_MASTER_CHECKNS      0x00000040      /*%<
00045                                                  * Check NS records to see
00046                                                  * if they are an address
00047                                                  */
00048 #define DNS_MASTER_FATALNS      0x00000080      /*%<
00049                                                  * Treat DNS_MASTER_CHECKNS
00050                                                  * matches as fatal
00051                                                  */
00052 #define DNS_MASTER_CHECKNAMES   0x00000100
00053 #define DNS_MASTER_CHECKNAMESFAIL 0x00000200
00054 #define DNS_MASTER_CHECKWILDCARD 0x00000400     /* Check for internal wildcards. */
00055 #define DNS_MASTER_CHECKMX      0x00000800
00056 #define DNS_MASTER_CHECKMXFAIL  0x00001000
00057 
00058 #define DNS_MASTER_RESIGN       0x00002000
00059 #define DNS_MASTER_KEY          0x00004000      /*%< Loading a key zone master file. */
00060 #define DNS_MASTER_NOTTL        0x00008000      /*%< Don't require ttl. */
00061 #define DNS_MASTER_CHECKTTL     0x00010000      /*%< Check max-zone-ttl */
00062 
00063 ISC_LANG_BEGINDECLS
00064 
00065 /*
00066  * Structures that implement the "raw" format for master dump.
00067  * These are provided for a reference purpose only; in the actual
00068  * encoding, we directly read/write each field so that the encoded data
00069  * is always "packed", regardless of the hardware architecture.
00070  */
00071 #define DNS_RAWFORMAT_VERSION 1
00072 
00073 /*
00074  * Flags to indicate the status of the data in the raw file header
00075  */
00076 #define DNS_MASTERRAW_COMPAT            0x01
00077 #define DNS_MASTERRAW_SOURCESERIALSET   0x02
00078 #define DNS_MASTERRAW_LASTXFRINSET      0x04
00079 
00080 /* Common header */
00081 struct dns_masterrawheader {
00082         isc_uint32_t            format;         /* must be
00083                                                  * dns_masterformat_raw
00084                                                  * or
00085                                                  * dns_masterformat_map */
00086         isc_uint32_t            version;        /* compatibility for future
00087                                                  * extensions */
00088         isc_uint32_t            dumptime;       /* timestamp on creation
00089                                                  * (currently unused) */
00090         isc_uint32_t            flags;          /* Flags */
00091         isc_uint32_t            sourceserial;   /* Source serial number (used
00092                                                  * by inline-signing zones) */
00093         isc_uint32_t            lastxfrin;      /* timestamp of last transfer
00094                                                  * (used by slave zones) */
00095 };
00096 
00097 /* The structure for each RRset */
00098 typedef struct {
00099         isc_uint32_t            totallen;       /* length of the data for this
00100                                                  * RRset, including the
00101                                                  * "header" part */
00102         dns_rdataclass_t        rdclass;        /* 16-bit class */
00103         dns_rdatatype_t         type;           /* 16-bit type */
00104         dns_rdatatype_t         covers;         /* same as type */
00105         dns_ttl_t               ttl;            /* 32-bit TTL */
00106         isc_uint32_t            nrdata;         /* number of RRs in this set */
00107         /* followed by encoded owner name, and then rdata */
00108 } dns_masterrawrdataset_t;
00109 
00110 /*
00111  * Method prototype: a callback to register each include file as
00112  * it is encountered.
00113  */
00114 typedef void
00115 (*dns_masterincludecb_t)(const char *file, void *arg);
00116 
00117 /***
00118  ***    Function
00119  ***/
00120 
00121 isc_result_t
00122 dns_master_loadfile(const char *master_file,
00123                     dns_name_t *top,
00124                     dns_name_t *origin,
00125                     dns_rdataclass_t zclass,
00126                     unsigned int options,
00127                     dns_rdatacallbacks_t *callbacks,
00128                     isc_mem_t *mctx);
00129 
00130 isc_result_t
00131 dns_master_loadfile2(const char *master_file,
00132                      dns_name_t *top,
00133                      dns_name_t *origin,
00134                      dns_rdataclass_t zclass,
00135                      unsigned int options,
00136                      dns_rdatacallbacks_t *callbacks,
00137                      isc_mem_t *mctx,
00138                      dns_masterformat_t format);
00139 
00140 isc_result_t
00141 dns_master_loadfile3(const char *master_file,
00142                      dns_name_t *top,
00143                      dns_name_t *origin,
00144                      dns_rdataclass_t zclass,
00145                      unsigned int options,
00146                      isc_uint32_t resign,
00147                      dns_rdatacallbacks_t *callbacks,
00148                      isc_mem_t *mctx,
00149                      dns_masterformat_t format);
00150 
00151 isc_result_t
00152 dns_master_loadfile4(const char *master_file,
00153                      dns_name_t *top,
00154                      dns_name_t *origin,
00155                      dns_rdataclass_t zclass,
00156                      unsigned int options,
00157                      isc_uint32_t resign,
00158                      dns_rdatacallbacks_t *callbacks,
00159                      dns_masterincludecb_t include_cb,
00160                      void *include_arg, isc_mem_t *mctx,
00161                      dns_masterformat_t format);
00162 
00163 isc_result_t
00164 dns_master_loadfile5(const char *master_file,
00165                      dns_name_t *top,
00166                      dns_name_t *origin,
00167                      dns_rdataclass_t zclass,
00168                      unsigned int options,
00169                      isc_uint32_t resign,
00170                      dns_rdatacallbacks_t *callbacks,
00171                      dns_masterincludecb_t include_cb,
00172                      void *include_arg, isc_mem_t *mctx,
00173                      dns_masterformat_t format,
00174                      dns_ttl_t maxttl);
00175 
00176 isc_result_t
00177 dns_master_loadstream(FILE *stream,
00178                       dns_name_t *top,
00179                       dns_name_t *origin,
00180                       dns_rdataclass_t zclass,
00181                       unsigned int options,
00182                       dns_rdatacallbacks_t *callbacks,
00183                       isc_mem_t *mctx);
00184 
00185 isc_result_t
00186 dns_master_loadbuffer(isc_buffer_t *buffer,
00187                       dns_name_t *top,
00188                       dns_name_t *origin,
00189                       dns_rdataclass_t zclass,
00190                       unsigned int options,
00191                       dns_rdatacallbacks_t *callbacks,
00192                       isc_mem_t *mctx);
00193 
00194 isc_result_t
00195 dns_master_loadlexer(isc_lex_t *lex,
00196                      dns_name_t *top,
00197                      dns_name_t *origin,
00198                      dns_rdataclass_t zclass,
00199                      unsigned int options,
00200                      dns_rdatacallbacks_t *callbacks,
00201                      isc_mem_t *mctx);
00202 
00203 isc_result_t
00204 dns_master_loadfileinc(const char *master_file,
00205                        dns_name_t *top,
00206                        dns_name_t *origin,
00207                        dns_rdataclass_t zclass,
00208                        unsigned int options,
00209                        dns_rdatacallbacks_t *callbacks,
00210                        isc_task_t *task,
00211                        dns_loaddonefunc_t done, void *done_arg,
00212                        dns_loadctx_t **ctxp, isc_mem_t *mctx);
00213 
00214 isc_result_t
00215 dns_master_loadfileinc2(const char *master_file,
00216                         dns_name_t *top,
00217                         dns_name_t *origin,
00218                         dns_rdataclass_t zclass,
00219                         unsigned int options,
00220                         dns_rdatacallbacks_t *callbacks,
00221                         isc_task_t *task,
00222                         dns_loaddonefunc_t done, void *done_arg,
00223                         dns_loadctx_t **ctxp, isc_mem_t *mctx,
00224                         dns_masterformat_t format);
00225 
00226 isc_result_t
00227 dns_master_loadfileinc3(const char *master_file,
00228                         dns_name_t *top,
00229                         dns_name_t *origin,
00230                         dns_rdataclass_t zclass,
00231                         unsigned int options,
00232                         isc_uint32_t resign,
00233                         dns_rdatacallbacks_t *callbacks,
00234                         isc_task_t *task,
00235                         dns_loaddonefunc_t done, void *done_arg,
00236                         dns_loadctx_t **ctxp, isc_mem_t *mctx,
00237                         dns_masterformat_t format);
00238 
00239 isc_result_t
00240 dns_master_loadfileinc4(const char *master_file,
00241                         dns_name_t *top,
00242                         dns_name_t *origin,
00243                         dns_rdataclass_t zclass,
00244                         unsigned int options,
00245                         isc_uint32_t resign,
00246                         dns_rdatacallbacks_t *callbacks,
00247                         isc_task_t *task,
00248                         dns_loaddonefunc_t done, void *done_arg,
00249                         dns_loadctx_t **ctxp,
00250                         dns_masterincludecb_t include_cb, void *include_arg,
00251                         isc_mem_t *mctx, dns_masterformat_t format);
00252 
00253 isc_result_t
00254 dns_master_loadfileinc5(const char *master_file,
00255                         dns_name_t *top,
00256                         dns_name_t *origin,
00257                         dns_rdataclass_t zclass,
00258                         unsigned int options,
00259                         isc_uint32_t resign,
00260                         dns_rdatacallbacks_t *callbacks,
00261                         isc_task_t *task,
00262                         dns_loaddonefunc_t done, void *done_arg,
00263                         dns_loadctx_t **ctxp,
00264                         dns_masterincludecb_t include_cb, void *include_arg,
00265                         isc_mem_t *mctx, dns_masterformat_t format,
00266                         isc_uint32_t maxttl);
00267 
00268 isc_result_t
00269 dns_master_loadstreaminc(FILE *stream,
00270                          dns_name_t *top,
00271                          dns_name_t *origin,
00272                          dns_rdataclass_t zclass,
00273                          unsigned int options,
00274                          dns_rdatacallbacks_t *callbacks,
00275                          isc_task_t *task,
00276                          dns_loaddonefunc_t done, void *done_arg,
00277                          dns_loadctx_t **ctxp, isc_mem_t *mctx);
00278 
00279 isc_result_t
00280 dns_master_loadbufferinc(isc_buffer_t *buffer,
00281                          dns_name_t *top,
00282                          dns_name_t *origin,
00283                          dns_rdataclass_t zclass,
00284                          unsigned int options,
00285                          dns_rdatacallbacks_t *callbacks,
00286                          isc_task_t *task,
00287                          dns_loaddonefunc_t done, void *done_arg,
00288                          dns_loadctx_t **ctxp, isc_mem_t *mctx);
00289 
00290 isc_result_t
00291 dns_master_loadlexerinc(isc_lex_t *lex,
00292                         dns_name_t *top,
00293                         dns_name_t *origin,
00294                         dns_rdataclass_t zclass,
00295                         unsigned int options,
00296                         dns_rdatacallbacks_t *callbacks,
00297                         isc_task_t *task,
00298                         dns_loaddonefunc_t done, void *done_arg,
00299                         dns_loadctx_t **ctxp, isc_mem_t *mctx);
00300 
00301 /*%<
00302  * Loads a RFC1305 master file from a file, stream, buffer, or existing
00303  * lexer into rdatasets and then calls 'callbacks->commit' to commit the
00304  * rdatasets.  Rdata memory belongs to dns_master_load and will be
00305  * reused / released when the callback completes.  dns_load_master will
00306  * abort if callbacks->commit returns any value other than ISC_R_SUCCESS.
00307  *
00308  * If 'DNS_MASTER_AGETTL' is set and the master file contains one or more
00309  * $DATE directives, the TTLs of the data will be aged accordingly.
00310  *
00311  * 'callbacks->commit' is assumed to call 'callbacks->error' or
00312  * 'callbacks->warn' to generate any error messages required.
00313  *
00314  * 'done' is called with 'done_arg' and a result code when the loading
00315  * is completed or has failed.  If the initial setup fails 'done' is
00316  * not called.
00317  *
00318  * 'resign' the number of seconds before a RRSIG expires that it should
00319  * be re-signed.  0 is used if not provided.
00320  *
00321  * Requires:
00322  *\li   'master_file' points to a valid string.
00323  *\li   'lexer' points to a valid lexer.
00324  *\li   'top' points to a valid name.
00325  *\li   'origin' points to a valid name.
00326  *\li   'callbacks->commit' points to a valid function.
00327  *\li   'callbacks->error' points to a valid function.
00328  *\li   'callbacks->warn' points to a valid function.
00329  *\li   'mctx' points to a valid memory context.
00330  *\li   'task' and 'done' to be valid.
00331  *\li   'lmgr' to be valid.
00332  *\li   'ctxp != NULL && ctxp == NULL'.
00333  *
00334  * Returns:
00335  *\li   ISC_R_SUCCESS upon successfully loading the master file.
00336  *\li   ISC_R_SEENINCLUDE upon successfully loading the master file with
00337  *              a $INCLUDE statement.
00338  *\li   ISC_R_NOMEMORY out of memory.
00339  *\li   ISC_R_UNEXPECTEDEND expected to be able to read a input token and
00340  *              there was not one.
00341  *\li   ISC_R_UNEXPECTED
00342  *\li   DNS_R_NOOWNER failed to specify a ownername.
00343  *\li   DNS_R_NOTTL failed to specify a ttl.
00344  *\li   DNS_R_BADCLASS record class did not match zone class.
00345  *\li   DNS_R_CONTINUE load still in progress (dns_master_load*inc() only).
00346  *\li   Any dns_rdata_fromtext() error code.
00347  *\li   Any error code from callbacks->commit().
00348  */
00349 
00350 void
00351 dns_loadctx_detach(dns_loadctx_t **ctxp);
00352 /*%<
00353  * Detach from the load context.
00354  *
00355  * Requires:
00356  *\li   '*ctxp' to be valid.
00357  *
00358  * Ensures:
00359  *\li   '*ctxp == NULL'
00360  */
00361 
00362 void
00363 dns_loadctx_attach(dns_loadctx_t *source, dns_loadctx_t **target);
00364 /*%<
00365  * Attach to the load context.
00366  *
00367  * Requires:
00368  *\li   'source' to be valid.
00369  *\li   'target != NULL && *target == NULL'.
00370  */
00371 
00372 void
00373 dns_loadctx_cancel(dns_loadctx_t *ctx);
00374 /*%<
00375  * Cancel loading the zone file associated with this load context.
00376  *
00377  * Requires:
00378  *\li   'ctx' to be valid
00379  */
00380 
00381 void
00382 dns_master_initrawheader(dns_masterrawheader_t *header);
00383 /*%<
00384  * Initializes the header for a raw master file, setting all
00385  * values to zero.
00386  */
00387 ISC_LANG_ENDDECLS
00388 
00389 #endif /* DNS_MASTER_H */