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

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