contrib/bind-9.5.2/lib/isccfg/include/isccfg/grammar.h

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