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

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