contrib/bind9/lib/dns/include/dns/master.h

   1 /*
   2  * Copyright (C) 2004-2009, 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$ */
  19
  20 #ifndef DNS_MASTER_H
  21 #define DNS_MASTER_H 1
  22
  23 /*! \file dns/master.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  * Flags to be passed in the 'options' argument in the functions below.
  37  */
  38 #define DNS_MASTER_AGETTL       0x00000001      /*%< Age the ttl based on $DATE. */
  39 #define DNS_MASTER_MANYERRORS   0x00000002      /*%< Continue processing on errors. */
  40 #define DNS_MASTER_NOINCLUDE    0x00000004      /*%< Disallow $INCLUDE directives. */
  41 #define DNS_MASTER_ZONE         0x00000008      /*%< Loading a zone master file. */
  42 #define DNS_MASTER_HINT         0x00000010      /*%< Loading a hint master file. */
  43 #define DNS_MASTER_SLAVE        0x00000020      /*%< Loading a slave master file. */
  44 #define DNS_MASTER_CHECKNS      0x00000040      /*%<
  45                                                  * Check NS records to see
  46                                                  * if they are an address
  47                                                  */
  48 #define DNS_MASTER_FATALNS      0x00000080      /*%<
  49                                                  * Treat DNS_MASTER_CHECKNS
  50                                                  * matches as fatal
  51                                                  */
  52 #define DNS_MASTER_CHECKNAMES   0x00000100
  53 #define DNS_MASTER_CHECKNAMESFAIL 0x00000200
  54 #define DNS_MASTER_CHECKWILDCARD 0x00000400     /* Check for internal wildcards. */
  55 #define DNS_MASTER_CHECKMX      0x00000800
  56 #define DNS_MASTER_CHECKMXFAIL  0x00001000
  57
  58 #define DNS_MASTER_RESIGN       0x00002000
  59 #define DNS_MASTER_KEY          0x00004000      /*%< Loading a key zone master file. */
  60 #define DNS_MASTER_NOTTL        0x00008000      /*%< Don't require ttl. */
  61
  62 ISC_LANG_BEGINDECLS
  63
  64 /*
  65  * Structures that implement the "raw" format for master dump.
  66  * These are provided for a reference purpose only; in the actual
  67  * encoding, we directly read/write each field so that the encoded data
  68  * is always "packed", regardless of the hardware architecture.
  69  */
  70 #define DNS_RAWFORMAT_VERSION 1
  71
  72 /*
  73  * Flags to indicate the status of the data in the raw file header
  74  */
  75 #define DNS_MASTERRAW_COMPAT            0x01
  76 #define DNS_MASTERRAW_SOURCESERIALSET   0x02
  77 #define DNS_MASTERRAW_LASTXFRINSET      0x04
  78
  79 /* Common header */
  80 struct dns_masterrawheader {
  81         isc_uint32_t            format;         /* must be
  82                                                  * dns_masterformat_raw */
  83         isc_uint32_t            version;        /* compatibility for future
  84                                                  * extensions */
  85         isc_uint32_t            dumptime;       /* timestamp on creation
  86                                                  * (currently unused) */
  87         isc_uint32_t            flags;          /* Flags */
  88         isc_uint32_t            sourceserial;   /* Source serial number (used
  89                                                  * by inline-signing zones) */
  90         isc_uint32_t            lastxfrin;      /* timestamp of last transfer
  91                                                  * (used by slave zones) */
  92 };
  93
  94 /* The structure for each RRset */
  95 typedef struct {
  96         isc_uint32_t            totallen;       /* length of the data for this
  97                                                  * RRset, including the
  98                                                  * "header" part */
  99         dns_rdataclass_t        rdclass;        /* 16-bit class */
 100         dns_rdatatype_t         type;           /* 16-bit type */
 101         dns_rdatatype_t         covers;         /* same as type */
 102         dns_ttl_t               ttl;            /* 32-bit TTL */
 103         isc_uint32_t            nrdata;         /* number of RRs in this set */
 104         /* followed by encoded owner name, and then rdata */
 105 } dns_masterrawrdataset_t;
 106
 107 /***
 108  ***    Function
 109  ***/
 110
 111 isc_result_t
 112 dns_master_loadfile(const char *master_file,
 113                     dns_name_t *top,
 114                     dns_name_t *origin,
 115                     dns_rdataclass_t zclass,
 116                     unsigned int options,
 117                     dns_rdatacallbacks_t *callbacks,
 118                     isc_mem_t *mctx);
 119
 120 isc_result_t
 121 dns_master_loadfile2(const char *master_file,
 122                      dns_name_t *top,
 123                      dns_name_t *origin,
 124                      dns_rdataclass_t zclass,
 125                      unsigned int options,
 126                      dns_rdatacallbacks_t *callbacks,
 127                      isc_mem_t *mctx,
 128                      dns_masterformat_t format);
 129
 130 isc_result_t
 131 dns_master_loadfile3(const char *master_file,
 132                      dns_name_t *top,
 133                      dns_name_t *origin,
 134                      dns_rdataclass_t zclass,
 135                      unsigned int options,
 136                      isc_uint32_t resign,
 137                      dns_rdatacallbacks_t *callbacks,
 138                      isc_mem_t *mctx,
 139                      dns_masterformat_t format);
 140
 141 isc_result_t
 142 dns_master_loadstream(FILE *stream,
 143                       dns_name_t *top,
 144                       dns_name_t *origin,
 145                       dns_rdataclass_t zclass,
 146                       unsigned int options,
 147                       dns_rdatacallbacks_t *callbacks,
 148                       isc_mem_t *mctx);
 149
 150 isc_result_t
 151 dns_master_loadbuffer(isc_buffer_t *buffer,
 152                       dns_name_t *top,
 153                       dns_name_t *origin,
 154                       dns_rdataclass_t zclass,
 155                       unsigned int options,
 156                       dns_rdatacallbacks_t *callbacks,
 157                       isc_mem_t *mctx);
 158
 159 isc_result_t
 160 dns_master_loadlexer(isc_lex_t *lex,
 161                      dns_name_t *top,
 162                      dns_name_t *origin,
 163                      dns_rdataclass_t zclass,
 164                      unsigned int options,
 165                      dns_rdatacallbacks_t *callbacks,
 166                      isc_mem_t *mctx);
 167
 168 isc_result_t
 169 dns_master_loadfileinc(const char *master_file,
 170                        dns_name_t *top,
 171                        dns_name_t *origin,
 172                        dns_rdataclass_t zclass,
 173                        unsigned int options,
 174                        dns_rdatacallbacks_t *callbacks,
 175                        isc_task_t *task,
 176                        dns_loaddonefunc_t done, void *done_arg,
 177                        dns_loadctx_t **ctxp, isc_mem_t *mctx);
 178
 179 isc_result_t
 180 dns_master_loadfileinc2(const char *master_file,
 181                         dns_name_t *top,
 182                         dns_name_t *origin,
 183                         dns_rdataclass_t zclass,
 184                         unsigned int options,
 185                         dns_rdatacallbacks_t *callbacks,
 186                         isc_task_t *task,
 187                         dns_loaddonefunc_t done, void *done_arg,
 188                         dns_loadctx_t **ctxp, isc_mem_t *mctx,
 189                         dns_masterformat_t format);
 190
 191 isc_result_t
 192 dns_master_loadfileinc3(const char *master_file,
 193                         dns_name_t *top,
 194                         dns_name_t *origin,
 195                         dns_rdataclass_t zclass,
 196                         unsigned int options,
 197                         isc_uint32_t resign,
 198                         dns_rdatacallbacks_t *callbacks,
 199                         isc_task_t *task,
 200                         dns_loaddonefunc_t done, void *done_arg,
 201                         dns_loadctx_t **ctxp, isc_mem_t *mctx,
 202                         dns_masterformat_t format);
 203
 204 isc_result_t
 205 dns_master_loadstreaminc(FILE *stream,
 206                          dns_name_t *top,
 207                          dns_name_t *origin,
 208                          dns_rdataclass_t zclass,
 209                          unsigned int options,
 210                          dns_rdatacallbacks_t *callbacks,
 211                          isc_task_t *task,
 212                          dns_loaddonefunc_t done, void *done_arg,
 213                          dns_loadctx_t **ctxp, isc_mem_t *mctx);
 214
 215 isc_result_t
 216 dns_master_loadbufferinc(isc_buffer_t *buffer,
 217                          dns_name_t *top,
 218                          dns_name_t *origin,
 219                          dns_rdataclass_t zclass,
 220                          unsigned int options,
 221                          dns_rdatacallbacks_t *callbacks,
 222                          isc_task_t *task,
 223                          dns_loaddonefunc_t done, void *done_arg,
 224                          dns_loadctx_t **ctxp, isc_mem_t *mctx);
 225
 226 isc_result_t
 227 dns_master_loadlexerinc(isc_lex_t *lex,
 228                         dns_name_t *top,
 229                         dns_name_t *origin,
 230                         dns_rdataclass_t zclass,
 231                         unsigned int options,
 232                         dns_rdatacallbacks_t *callbacks,
 233                         isc_task_t *task,
 234                         dns_loaddonefunc_t done, void *done_arg,
 235                         dns_loadctx_t **ctxp, isc_mem_t *mctx);
 236
 237 /*%<
 238  * Loads a RFC1305 master file from a file, stream, buffer, or existing
 239  * lexer into rdatasets and then calls 'callbacks->commit' to commit the
 240  * rdatasets.  Rdata memory belongs to dns_master_load and will be
 241  * reused / released when the callback completes.  dns_load_master will
 242  * abort if callbacks->commit returns any value other than ISC_R_SUCCESS.
 243  *
 244  * If 'DNS_MASTER_AGETTL' is set and the master file contains one or more
 245  * $DATE directives, the TTLs of the data will be aged accordingly.
 246  *
 247  * 'callbacks->commit' is assumed to call 'callbacks->error' or
 248  * 'callbacks->warn' to generate any error messages required.
 249  *
 250  * 'done' is called with 'done_arg' and a result code when the loading
 251  * is completed or has failed.  If the initial setup fails 'done' is
 252  * not called.
 253  *
 254  * 'resign' the number of seconds before a RRSIG expires that it should
 255  * be re-signed.  0 is used if not provided.
 256  *
 257  * Requires:
 258  *\li   'master_file' points to a valid string.
 259  *\li   'lexer' points to a valid lexer.
 260  *\li   'top' points to a valid name.
 261  *\li   'origin' points to a valid name.
 262  *\li   'callbacks->commit' points to a valid function.
 263  *\li   'callbacks->error' points to a valid function.
 264  *\li   'callbacks->warn' points to a valid function.
 265  *\li   'mctx' points to a valid memory context.
 266  *\li   'task' and 'done' to be valid.
 267  *\li   'lmgr' to be valid.
 268  *\li   'ctxp != NULL && ctxp == NULL'.
 269  *
 270  * Returns:
 271  *\li   ISC_R_SUCCESS upon successfully loading the master file.
 272  *\li   ISC_R_SEENINCLUDE upon successfully loading the master file with
 273  *              a $INCLUDE statement.
 274  *\li   ISC_R_NOMEMORY out of memory.
 275  *\li   ISC_R_UNEXPECTEDEND expected to be able to read a input token and
 276  *              there was not one.
 277  *\li   ISC_R_UNEXPECTED
 278  *\li   DNS_R_NOOWNER failed to specify a ownername.
 279  *\li   DNS_R_NOTTL failed to specify a ttl.
 280  *\li   DNS_R_BADCLASS record class did not match zone class.
 281  *\li   DNS_R_CONTINUE load still in progress (dns_master_load*inc() only).
 282  *\li   Any dns_rdata_fromtext() error code.
 283  *\li   Any error code from callbacks->commit().
 284  */
 285
 286 void
 287 dns_loadctx_detach(dns_loadctx_t **ctxp);
 288 /*%<
 289  * Detach from the load context.
 290  *
 291  * Requires:
 292  *\li   '*ctxp' to be valid.
 293  *
 294  * Ensures:
 295  *\li   '*ctxp == NULL'
 296  */
 297
 298 void
 299 dns_loadctx_attach(dns_loadctx_t *source, dns_loadctx_t **target);
 300 /*%<
 301  * Attach to the load context.
 302  *
 303  * Requires:
 304  *\li   'source' to be valid.
 305  *\li   'target != NULL && *target == NULL'.
 306  */
 307
 308 void
 309 dns_loadctx_cancel(dns_loadctx_t *ctx);
 310 /*%<
 311  * Cancel loading the zone file associated with this load context.
 312  *
 313  * Requires:
 314  *\li   'ctx' to be valid
 315  */
 316
 317 void
 318 dns_master_initrawheader(dns_masterrawheader_t *header);
 319 /*%<
 320  * Initializes the header for a raw master file, setting all
 321  * values to zero.
 322  */
 323 ISC_LANG_ENDDECLS
 324
 325 #endif /* DNS_MASTER_H */