contrib/bind9/lib/isccfg/include/isccfg/grammar.h

   1 /*
   2  * Copyright (C) 2004-2011  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2002, 2003  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: grammar.h,v 1.24 2011/01/04 23:47:14 tbox Exp $ */
  19
  20 #ifndef ISCCFG_GRAMMAR_H
  21 #define ISCCFG_GRAMMAR_H 1
  22
  23 /*! \file isccfg/grammar.h */
  24
  25 #include <isc/lex.h>
  26 #include <isc/netaddr.h>
  27 #include <isc/sockaddr.h>
  28 #include <isc/region.h>
  29 #include <isc/types.h>
  30
  31 #include <isccfg/cfg.h>
  32
  33 /*
  34  * Definitions shared between the configuration parser
  35  * and the grammars; not visible to users of the parser.
  36  */
  37
  38 /*% Clause may occur multiple times (e.g., "zone") */
  39 #define CFG_CLAUSEFLAG_MULTI            0x00000001
  40 /*% Clause is obsolete */
  41 #define CFG_CLAUSEFLAG_OBSOLETE         0x00000002
  42 /*% Clause is not implemented, and may never be */
  43 #define CFG_CLAUSEFLAG_NOTIMP           0x00000004
  44 /*% Clause is not implemented yet */
  45 #define CFG_CLAUSEFLAG_NYI              0x00000008
  46 /*% Default value has changed since earlier release */
  47 #define CFG_CLAUSEFLAG_NEWDEFAULT       0x00000010
  48 /*%
  49  * Clause needs to be interpreted during parsing
  50  * by calling a callback function, like the
  51  * "directory" option.
  52  */
  53 #define CFG_CLAUSEFLAG_CALLBACK         0x00000020
  54 /*% A option that is only used in testing. */
  55 #define CFG_CLAUSEFLAG_TESTONLY         0x00000040
  56 /*% A configuration option that was not configured at compile time. */
  57 #define CFG_CLAUSEFLAG_NOTCONFIGURED    0x00000080
  58
  59 typedef struct cfg_clausedef cfg_clausedef_t;
  60 typedef struct cfg_tuplefielddef cfg_tuplefielddef_t;
  61 typedef struct cfg_printer cfg_printer_t;
  62 typedef ISC_LIST(cfg_listelt_t) cfg_list_t;
  63 typedef struct cfg_map cfg_map_t;
  64 typedef struct cfg_rep cfg_rep_t;
  65
  66 /*
  67  * Function types for configuration object methods
  68  */
  69
  70 typedef isc_result_t (*cfg_parsefunc_t)(cfg_parser_t *, const cfg_type_t *type,
  71                                         cfg_obj_t **);
  72 typedef void         (*cfg_printfunc_t)(cfg_printer_t *, const cfg_obj_t *);
  73 typedef void         (*cfg_docfunc_t)(cfg_printer_t *, const cfg_type_t *);
  74 typedef void         (*cfg_freefunc_t)(cfg_parser_t *, cfg_obj_t *);
  75
  76 /*
  77  * Structure definitions
  78  */
  79
  80 /*%
  81  * A configuration printer object.  This is an abstract
  82  * interface to a destination to which text can be printed
  83  * by calling the function 'f'.
  84  */
  85 struct cfg_printer {
  86         void (*f)(void *closure, const char *text, int textlen);
  87         void *closure;
  88         int indent;
  89 };
  90
  91 /*% A clause definition. */
  92 struct cfg_clausedef {
  93         const char      *name;
  94         cfg_type_t      *type;
  95         unsigned int    flags;
  96 };
  97
  98 /*% A tuple field definition. */
  99 struct cfg_tuplefielddef {
 100         const char      *name;
 101         cfg_type_t      *type;
 102         unsigned int    flags;
 103 };
 104
 105 /*% A configuration object type definition. */
 106 struct cfg_type {
 107         const char *name;       /*%< For debugging purposes only */
 108         cfg_parsefunc_t parse;
 109         cfg_printfunc_t print;
 110         cfg_docfunc_t   doc;    /*%< Print grammar description */
 111         cfg_rep_t *     rep;    /*%< Data representation */
 112         const void *    of;     /*%< Additional data for meta-types */
 113 };
 114
 115 /*% A keyword-type definition, for things like "port <integer>". */
 116 typedef struct {
 117         const char *name;
 118         const cfg_type_t *type;
 119 } keyword_type_t;
 120
 121 struct cfg_map {
 122         cfg_obj_t        *id; /*%< Used for 'named maps' like keys, zones, &c */
 123         const cfg_clausedef_t * const *clausesets; /*%< The clauses that
 124                                                       can occur in this map;
 125                                                       used for printing */
 126         isc_symtab_t     *symtab;
 127 };
 128
 129 typedef struct cfg_netprefix cfg_netprefix_t;
 130
 131 struct cfg_netprefix {
 132         isc_netaddr_t address; /* IP4/IP6 */
 133         unsigned int prefixlen;
 134 };
 135
 136 /*%
 137  * A configuration data representation.
 138  */
 139 struct cfg_rep {
 140         const char *    name;   /*%< For debugging only */
 141         cfg_freefunc_t  free;   /*%< How to free this kind of data. */
 142 };
 143
 144 /*%
 145  * A configuration object.  This is the main building block
 146  * of the configuration parse tree.
 147  */
 148
 149 struct cfg_obj {
 150         const cfg_type_t *type;
 151         union {
 152                 isc_uint32_t    uint32;
 153                 isc_uint64_t    uint64;
 154                 isc_textregion_t string; /*%< null terminated, too */
 155                 isc_boolean_t   boolean;
 156                 cfg_map_t       map;
 157                 cfg_list_t      list;
 158                 cfg_obj_t **    tuple;
 159                 isc_sockaddr_t  sockaddr;
 160                 cfg_netprefix_t netprefix;
 161         }               value;
 162         isc_refcount_t  references;     /*%< reference counter */
 163         const char *    file;
 164         unsigned int    line;
 165 };
 166
 167
 168 /*% A list element. */
 169 struct cfg_listelt {
 170         cfg_obj_t               *obj;
 171         ISC_LINK(cfg_listelt_t)  link;
 172 };
 173
 174 /*% The parser object. */
 175 struct cfg_parser {
 176         isc_mem_t *     mctx;
 177         isc_log_t *     lctx;
 178         isc_lex_t *     lexer;
 179         unsigned int    errors;
 180         unsigned int    warnings;
 181         isc_token_t     token;
 182
 183         /*% We are at the end of all input. */
 184         isc_boolean_t   seen_eof;
 185
 186         /*% The current token has been pushed back. */
 187         isc_boolean_t   ungotten;
 188
 189         /*%
 190          * The stack of currently active files, represented
 191          * as a configuration list of configuration strings.
 192          * The head is the top-level file, subsequent elements
 193          * (if any) are the nested include files, and the
 194          * last element is the file currently being parsed.
 195          */
 196         cfg_obj_t *     open_files;
 197
 198         /*%
 199          * Names of files that we have parsed and closed
 200          * and were previously on the open_file list.
 201          * We keep these objects around after closing
 202          * the files because the file names may still be
 203          * referenced from other configuration objects
 204          * for use in reporting semantic errors after
 205          * parsing is complete.
 206          */
 207         cfg_obj_t *     closed_files;
 208
 209         /*%
 210          * Current line number.  We maintain our own
 211          * copy of this so that it is available even
 212          * when a file has just been closed.
 213          */
 214         unsigned int    line;
 215
 216         /*%
 217          * Parser context flags, used for maintaining state
 218          * from one token to the next.
 219          */
 220         unsigned int flags;
 221
 222         /*%< Reference counter */
 223         isc_refcount_t  references;
 224
 225         cfg_parsecallback_t callback;
 226         void *callbackarg;
 227 };
 228
 229 /* Parser context flags */
 230 #define CFG_PCTX_SKIP           0x1
 231
 232 /*@{*/
 233 /*%
 234  * Flags defining whether to accept certain types of network addresses.
 235  */
 236 #define CFG_ADDR_V4OK           0x00000001
 237 #define CFG_ADDR_V4PREFIXOK     0x00000002
 238 #define CFG_ADDR_V6OK           0x00000004
 239 #define CFG_ADDR_WILDOK         0x00000008
 240 #define CFG_ADDR_MASK           (CFG_ADDR_V6OK|CFG_ADDR_V4OK)
 241 /*@}*/
 242
 243 /*@{*/
 244 /*%
 245  * Predefined data representation types.
 246  */
 247 LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_uint32;
 248 LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_uint64;
 249 LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_string;
 250 LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_boolean;
 251 LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_map;
 252 LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_list;
 253 LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_tuple;
 254 LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_sockaddr;
 255 LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_netprefix;
 256 LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_void;
 257 /*@}*/
 258
 259 /*@{*/
 260 /*%
 261  * Predefined configuration object types.
 262  */
 263 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_boolean;
 264 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_uint32;
 265 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_uint64;
 266 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_qstring;
 267 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_astring;
 268 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_ustring;
 269 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_sockaddr;
 270 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_netaddr;
 271 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_netaddr4;
 272 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_netaddr4wild;
 273 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_netaddr6;
 274 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_netaddr6wild;
 275 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_netprefix;
 276 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_void;
 277 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_token;
 278 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_unsupported;
 279 /*@}*/
 280
 281 isc_result_t
 282 cfg_gettoken(cfg_parser_t *pctx, int options);
 283
 284 isc_result_t
 285 cfg_peektoken(cfg_parser_t *pctx, int options);
 286
 287 void
 288 cfg_ungettoken(cfg_parser_t *pctx);
 289
 290 #define CFG_LEXOPT_QSTRING (ISC_LEXOPT_QSTRING | ISC_LEXOPT_QSTRINGMULTILINE)
 291
 292 isc_result_t
 293 cfg_create_obj(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **objp);
 294
 295 void
 296 cfg_print_rawuint(cfg_printer_t *pctx, unsigned int u);
 297
 298 isc_result_t
 299 cfg_parse_uint32(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 300
 301 void
 302 cfg_print_uint32(cfg_printer_t *pctx, const cfg_obj_t *obj);
 303
 304 void
 305 cfg_print_uint64(cfg_printer_t *pctx, const cfg_obj_t *obj);
 306
 307 isc_result_t
 308 cfg_parse_qstring(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 309
 310 void
 311 cfg_print_ustring(cfg_printer_t *pctx, const cfg_obj_t *obj);
 312
 313 isc_result_t
 314 cfg_parse_astring(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 315
 316 isc_result_t
 317 cfg_parse_rawaddr(cfg_parser_t *pctx, unsigned int flags, isc_netaddr_t *na);
 318
 319 void
 320 cfg_print_rawaddr(cfg_printer_t *pctx, const isc_netaddr_t *na);
 321
 322 isc_boolean_t
 323 cfg_lookingat_netaddr(cfg_parser_t *pctx, unsigned int flags);
 324
 325 isc_result_t
 326 cfg_parse_rawport(cfg_parser_t *pctx, unsigned int flags, in_port_t *port);
 327
 328 isc_result_t
 329 cfg_parse_sockaddr(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 330
 331 isc_result_t
 332 cfg_parse_boolean(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 333
 334 void
 335 cfg_print_sockaddr(cfg_printer_t *pctx, const cfg_obj_t *obj);
 336
 337 void
 338 cfg_print_boolean(cfg_printer_t *pctx, const cfg_obj_t *obj);
 339
 340 void
 341 cfg_doc_sockaddr(cfg_printer_t *pctx, const cfg_type_t *type);
 342
 343 isc_result_t
 344 cfg_parse_netprefix(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 345
 346 isc_result_t
 347 cfg_parse_special(cfg_parser_t *pctx, int special);
 348 /*%< Parse a required special character 'special'. */
 349
 350 isc_result_t
 351 cfg_create_tuple(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **objp);
 352
 353 isc_result_t
 354 cfg_parse_tuple(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 355
 356 void
 357 cfg_print_tuple(cfg_printer_t *pctx, const cfg_obj_t *obj);
 358
 359 void
 360 cfg_doc_tuple(cfg_printer_t *pctx, const cfg_type_t *type);
 361
 362 isc_result_t
 363 cfg_create_list(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **objp);
 364
 365 isc_result_t
 366 cfg_parse_listelt(cfg_parser_t *pctx, const cfg_type_t *elttype,
 367                   cfg_listelt_t **ret);
 368
 369 isc_result_t
 370 cfg_parse_bracketed_list(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 371
 372 void
 373 cfg_print_bracketed_list(cfg_printer_t *pctx, const cfg_obj_t *obj);
 374
 375 void
 376 cfg_doc_bracketed_list(cfg_printer_t *pctx, const cfg_type_t *type);
 377
 378 isc_result_t
 379 cfg_parse_spacelist(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 380
 381 void
 382 cfg_print_spacelist(cfg_printer_t *pctx, const cfg_obj_t *obj);
 383
 384 isc_result_t
 385 cfg_parse_enum(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 386
 387 void
 388 cfg_doc_enum(cfg_printer_t *pctx, const cfg_type_t *type);
 389
 390 void
 391 cfg_print_chars(cfg_printer_t *pctx, const char *text, int len);
 392 /*%< Print 'len' characters at 'text' */
 393
 394 void
 395 cfg_print_cstr(cfg_printer_t *pctx, const char *s);
 396 /*%< Print the null-terminated string 's' */
 397
 398 isc_result_t
 399 cfg_parse_map(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 400
 401 isc_result_t
 402 cfg_parse_named_map(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 403
 404 isc_result_t
 405 cfg_parse_addressed_map(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 406
 407 isc_result_t
 408 cfg_parse_netprefix_map(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **
 409 ret);
 410
 411 void
 412 cfg_print_map(cfg_printer_t *pctx, const cfg_obj_t *obj);
 413
 414 void
 415 cfg_doc_map(cfg_printer_t *pctx, const cfg_type_t *type);
 416
 417 isc_result_t
 418 cfg_parse_mapbody(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 419
 420 void
 421 cfg_print_mapbody(cfg_printer_t *pctx, const cfg_obj_t *obj);
 422
 423 void
 424 cfg_doc_mapbody(cfg_printer_t *pctx, const cfg_type_t *type);
 425
 426 isc_result_t
 427 cfg_parse_void(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 428
 429 void
 430 cfg_print_void(cfg_printer_t *pctx, const cfg_obj_t *obj);
 431
 432 void
 433 cfg_doc_void(cfg_printer_t *pctx, const cfg_type_t *type);
 434
 435 isc_result_t
 436 cfg_parse_obj(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret);
 437
 438 void
 439 cfg_print_obj(cfg_printer_t *pctx, const cfg_obj_t *obj);
 440
 441 void
 442 cfg_doc_obj(cfg_printer_t *pctx, const cfg_type_t *type);
 443 /*%<
 444  * Print a description of the grammar of an arbitrary configuration
 445  * type 'type'
 446  */
 447
 448 void
 449 cfg_doc_terminal(cfg_printer_t *pctx, const cfg_type_t *type);
 450 /*%<
 451  * Document the type 'type' as a terminal by printing its
 452  * name in angle brackets, e.g., &lt;uint32>.
 453  */
 454
 455 void
 456 cfg_parser_error(cfg_parser_t *pctx, unsigned int flags,
 457                  const char *fmt, ...) ISC_FORMAT_PRINTF(3, 4);
 458 /*!
 459  * Pass one of these flags to cfg_parser_error() to include the
 460  * token text in log message.
 461  */
 462 #define CFG_LOG_NEAR    0x00000001      /*%< Say "near <token>" */
 463 #define CFG_LOG_BEFORE  0x00000002      /*%< Say "before <token>" */
 464 #define CFG_LOG_NOPREP  0x00000004      /*%< Say just "<token>" */
 465
 466 void
 467 cfg_parser_warning(cfg_parser_t *pctx, unsigned int flags,
 468                    const char *fmt, ...) ISC_FORMAT_PRINTF(3, 4);
 469
 470 isc_boolean_t
 471 cfg_is_enum(const char *s, const char *const *enums);
 472 /*%< Return true iff the string 's' is one of the strings in 'enums' */
 473
 474 #endif /* ISCCFG_GRAMMAR_H */