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

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