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

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