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

   1 /*
   2  * Copyright (C) 2004, 2006  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000-2002  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: cfg.h,v 1.30.12.6 2006/03/02 00:37:20 marka Exp $ */
  19
  20 #ifndef ISCCFG_CFG_H
  21 #define ISCCFG_CFG_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*
  28  * This is the new, table-driven, YACC-free configuration file parser.
  29  */
  30
  31 /***
  32  *** Imports
  33  ***/
  34
  35 #include <isc/formatcheck.h>
  36 #include <isc/lang.h>
  37 #include <isc/types.h>
  38 #include <isc/list.h>
  39
  40
  41 /***
  42  *** Types
  43  ***/
  44
  45 typedef struct cfg_parser cfg_parser_t;
  46 /*
  47  * A configuration parser.
  48  */
  49
  50 /*
  51  * A configuration type definition object.  There is a single
  52  * static cfg_type_t object for each data type supported by
  53  * the configuration parser.
  54  */
  55 typedef struct cfg_type cfg_type_t;
  56
  57 /*
  58  * A configuration object.  This is the basic building block of the
  59  * configuration parse tree.  It contains a value (which may be
  60  * of one of several types) and information identifying the file
  61  * and line number the value came from, for printing error
  62  * messages.
  63  */
  64 typedef struct cfg_obj cfg_obj_t;
  65
  66 /*
  67  * A configuration object list element.
  68  */
  69 typedef struct cfg_listelt cfg_listelt_t;
  70
  71 /*
  72  * A callback function to be called when parsing an option
  73  * that needs to be interpreted at parsing time, like
  74  * "directory".
  75  */
  76 typedef isc_result_t
  77 (*cfg_parsecallback_t)(const char *clausename, const cfg_obj_t *obj, void *arg);
  78
  79 /***
  80  *** Functions
  81  ***/
  82
  83 ISC_LANG_BEGINDECLS
  84
  85 isc_result_t
  86 cfg_parser_create(isc_mem_t *mctx, isc_log_t *lctx, cfg_parser_t **ret);
  87 /*
  88  * Create a configuration file parser.  Any warning and error
  89  * messages will be logged to 'lctx'.
  90  *
  91  * The parser object returned can be used for a single call
  92  * to cfg_parse_file() or cfg_parse_buffer().  It must not
  93  * be reused for parsing multiple files or buffers.
  94  */
  95
  96 void
  97 cfg_parser_setcallback(cfg_parser_t *pctx,
  98                        cfg_parsecallback_t callback,
  99                        void *arg);
 100 /*
 101  * Make the parser call 'callback' whenever it encounters
 102  * a configuration clause with the callback attribute,
 103  * passing it the clause name, the clause value,
 104  * and 'arg' as arguments.
 105  *
 106  * To restore the default of not invoking callbacks, pass
 107  * callback==NULL and arg==NULL.
 108  */
 109
 110 isc_result_t
 111 cfg_parse_file(cfg_parser_t *pctx, const char *filename,
 112                const cfg_type_t *type, cfg_obj_t **ret);
 113 isc_result_t
 114 cfg_parse_buffer(cfg_parser_t *pctx, isc_buffer_t *buffer,
 115                  const cfg_type_t *type, cfg_obj_t **ret);
 116 /*
 117  * Read a configuration containing data of type 'type'
 118  * and make '*ret' point to its parse tree.
 119  *
 120  * The configuration is read from the file 'filename'
 121  * (isc_parse_file()) or the buffer 'buffer'
 122  * (isc_parse_buffer()).
 123  *
 124  * Returns an error if the file does not parse correctly.
 125  *
 126  * Requires:
 127  *      "filename" is valid.
 128  *      "mem" is valid.
 129  *      "type" is valid.
 130  *      "cfg" is non-NULL and "*cfg" is NULL.
 131  *
 132  * Returns:
 133  *      ISC_R_SUCCESS                 - success
 134  *      ISC_R_NOMEMORY                - no memory available
 135  *      ISC_R_INVALIDFILE             - file doesn't exist or is unreadable
 136  *      others                        - file contains errors
 137  */
 138
 139 void
 140 cfg_parser_destroy(cfg_parser_t **pctxp);
 141 /*
 142  * Destroy a configuration parser.
 143  */
 144
 145 isc_boolean_t
 146 cfg_obj_isvoid(const cfg_obj_t *obj);
 147 /*
 148  * Return true iff 'obj' is of void type (e.g., an optional
 149  * value not specified).
 150  */
 151
 152 isc_boolean_t
 153 cfg_obj_ismap(const cfg_obj_t *obj);
 154 /*
 155  * Return true iff 'obj' is of a map type.
 156  */
 157
 158 isc_result_t
 159 cfg_map_get(const cfg_obj_t *mapobj, const char* name, const cfg_obj_t **obj);
 160 /*
 161  * Extract an element from a configuration object, which
 162  * must be of a map type.
 163  *
 164  * Requires:
 165  *      'mapobj' points to a valid configuration object of a map type.
 166  *      'name' points to a null-terminated string.
 167  *      'obj' is non-NULL and '*obj' is NULL.
 168  *
 169  * Returns:
 170  *      ISC_R_SUCCESS                  - success
 171  *      ISC_R_NOTFOUND                 - name not found in map
 172  */
 173
 174 const cfg_obj_t *
 175 cfg_map_getname(const cfg_obj_t *mapobj);
 176 /*
 177  * Get the name of a named map object, like a server "key" clause.
 178  *
 179  * Requires:
 180  *      'mapobj' points to a valid configuration object of a map type.
 181  *
 182  * Returns:
 183  *      A pointer to a configuration object naming the map object,
 184  *      or NULL if the map object does not have a name.
 185  */
 186
 187 isc_boolean_t
 188 cfg_obj_istuple(const cfg_obj_t *obj);
 189 /*
 190  * Return true iff 'obj' is of a map type.
 191  */
 192
 193 const cfg_obj_t *
 194 cfg_tuple_get(const cfg_obj_t *tupleobj, const char *name);
 195 /*
 196  * Extract an element from a configuration object, which
 197  * must be of a tuple type.
 198  *
 199  * Requires:
 200  *      'tupleobj' points to a valid configuration object of a tuple type.
 201  *      'name' points to a null-terminated string naming one of the
 202  *      fields of said tuple type.
 203  */
 204
 205 isc_boolean_t
 206 cfg_obj_isuint32(const cfg_obj_t *obj);
 207 /*
 208  * Return true iff 'obj' is of integer type.
 209  */
 210
 211 isc_uint32_t
 212 cfg_obj_asuint32(const cfg_obj_t *obj);
 213 /*
 214  * Returns the value of a configuration object of 32-bit integer type.
 215  *
 216  * Requires:
 217  *      'obj' points to a valid configuration object of 32-bit integer type.
 218  *
 219  * Returns:
 220  *      A 32-bit unsigned integer.
 221  */
 222
 223 isc_boolean_t
 224 cfg_obj_isuint64(const cfg_obj_t *obj);
 225 /*
 226  * Return true iff 'obj' is of integer type.
 227  */
 228
 229 isc_uint64_t
 230 cfg_obj_asuint64(const cfg_obj_t *obj);
 231 /*
 232  * Returns the value of a configuration object of 64-bit integer type.
 233  *
 234  * Requires:
 235  *      'obj' points to a valid configuration object of 64-bit integer type.
 236  *
 237  * Returns:
 238  *      A 64-bit unsigned integer.
 239  */
 240
 241 isc_boolean_t
 242 cfg_obj_isstring(const cfg_obj_t *obj);
 243 /*
 244  * Return true iff 'obj' is of string type.
 245  */
 246
 247 const char *
 248 cfg_obj_asstring(const cfg_obj_t *obj);
 249 /*
 250  * Returns the value of a configuration object of a string type
 251  * as a null-terminated string.
 252  *
 253  * Requires:
 254  *      'obj' points to a valid configuration object of a string type.
 255  *
 256  * Returns:
 257  *      A pointer to a null terminated string.
 258  */
 259
 260 isc_boolean_t
 261 cfg_obj_isboolean(const cfg_obj_t *obj);
 262 /*
 263  * Return true iff 'obj' is of a boolean type.
 264  */
 265
 266 isc_boolean_t
 267 cfg_obj_asboolean(const cfg_obj_t *obj);
 268 /*
 269  * Returns the value of a configuration object of a boolean type.
 270  *
 271  * Requires:
 272  *      'obj' points to a valid configuration object of a boolean type.
 273  *
 274  * Returns:
 275  *      A boolean value.
 276  */
 277
 278 isc_boolean_t
 279 cfg_obj_issockaddr(const cfg_obj_t *obj);
 280 /*
 281  * Return true iff 'obj' is a socket address.
 282  */
 283
 284 const isc_sockaddr_t *
 285 cfg_obj_assockaddr(const cfg_obj_t *obj);
 286 /*
 287  * Returns the value of a configuration object representing a socket address.
 288  *
 289  * Requires:
 290  *      'obj' points to a valid configuration object of a socket address type.
 291  *
 292  * Returns:
 293  *      A pointer to a sockaddr.  The sockaddr must be copied by the caller
 294  *      if necessary.
 295  */
 296
 297 isc_boolean_t
 298 cfg_obj_isnetprefix(const cfg_obj_t *obj);
 299 /*
 300  * Return true iff 'obj' is a network prefix.
 301  */
 302
 303 void
 304 cfg_obj_asnetprefix(const cfg_obj_t *obj, isc_netaddr_t *netaddr,
 305                     unsigned int *prefixlen);
 306 /*
 307  * Gets the value of a configuration object representing a network
 308  * prefix.  The network address is returned through 'netaddr' and the
 309  * prefix length in bits through 'prefixlen'.
 310  *
 311  * Requires:
 312  *      'obj' points to a valid configuration object of network prefix type.
 313  *      'netaddr' and 'prefixlen' are non-NULL.
 314  */
 315
 316 isc_boolean_t
 317 cfg_obj_islist(const cfg_obj_t *obj);
 318 /*
 319  * Return true iff 'obj' is of list type.
 320  */
 321
 322 const cfg_listelt_t *
 323 cfg_list_first(const cfg_obj_t *obj);
 324 /*
 325  * Returns the first list element in a configuration object of a list type.
 326  *
 327  * Requires:
 328  *      'obj' points to a valid configuration object of a list type or NULL.
 329  *
 330  * Returns:
 331  *      A pointer to a cfg_listelt_t representing the first list element,
 332  *      or NULL if the list is empty or nonexistent.
 333  */
 334
 335 const cfg_listelt_t *
 336 cfg_list_next(const cfg_listelt_t *elt);
 337 /*
 338  * Returns the next element of a list of configuration objects.
 339  *
 340  * Requires:
 341  *      'elt' points to cfg_listelt_t obtained from cfg_list_first() or
 342  *      a previous call to cfg_list_next().
 343  *
 344  * Returns:
 345  *      A pointer to a cfg_listelt_t representing the next element,
 346  *      or NULL if there are no more elements.
 347  */
 348
 349 const cfg_obj_t *
 350 cfg_listelt_value(const cfg_listelt_t *elt);
 351 /*
 352  * Returns the configuration object associated with cfg_listelt_t.
 353  *
 354  * Requires:
 355  *      'elt' points to cfg_listelt_t obtained from cfg_list_first() or
 356  *      cfg_list_next().
 357  *
 358  * Returns:
 359  *      A non-NULL pointer to a configuration object.
 360  */
 361
 362 void
 363 cfg_print(const cfg_obj_t *obj,
 364           void (*f)(void *closure, const char *text, int textlen),
 365           void *closure);
 366 /*
 367  * Print the configuration object 'obj' by repeatedly calling the
 368  * function 'f', passing 'closure' and a region of text starting
 369  * at 'text' and comprising 'textlen' characters.
 370  */
 371
 372 void
 373 cfg_print_grammar(const cfg_type_t *type,
 374           void (*f)(void *closure, const char *text, int textlen),
 375           void *closure);
 376 /*
 377  * Print a summary of the grammar of the configuration type 'type'.
 378  */
 379
 380 isc_boolean_t
 381 cfg_obj_istype(const cfg_obj_t *obj, const cfg_type_t *type);
 382 /*
 383  * Return true iff 'obj' is of type 'type'.
 384  */
 385
 386 void cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj);
 387 /*
 388  * Destroy a configuration object.
 389  */
 390
 391 void
 392 cfg_obj_log(const cfg_obj_t *obj, isc_log_t *lctx, int level,
 393             const char *fmt, ...)
 394         ISC_FORMAT_PRINTF(4, 5);
 395 /*
 396  * Log a message concerning configuration object 'obj' to the logging
 397  * channel of 'pctx', at log level 'level'.  The message will be prefixed
 398  * with the file name(s) and line number where 'obj' was defined.
 399  */
 400
 401 const char *
 402 cfg_obj_file(const cfg_obj_t *obj);
 403 /*
 404  * Return the file that defined this object.
 405  */
 406
 407 unsigned int
 408 cfg_obj_line(const cfg_obj_t *obj);
 409 /*
 410  * Return the line in file where this object was defined.
 411  */
 412
 413
 414 ISC_LANG_ENDDECLS
 415
 416 #endif /* ISCCFG_CFG_H */