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 */ 50typedef 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 */ 57typedef 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 */ 66typedef struct cfg_obj cfg_obj_t; 67 68/*% 69 * A configuration object list element. 70 */ 71typedef 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 */ 78typedef isc_result_t 79(*cfg_parsecallback_t)(const char *clausename, const cfg_obj_t *obj, void *arg); 80 81/*** 82 *** Functions 83 ***/ 84 85ISC_LANG_BEGINDECLS 86 87void 88cfg_parser_attach(cfg_parser_t *src, cfg_parser_t **dest); 89/*%< 90 * Reference a parser object. 91 */ 92 93isc_result_t 94cfg_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 104void 105cfg_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 118isc_result_t 119cfg_parse_file(cfg_parser_t *pctx, const char *filename, 120 const cfg_type_t *type, cfg_obj_t **ret); 121isc_result_t 122cfg_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 147void 148cfg_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 154isc_boolean_t 155cfg_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 161isc_boolean_t 162cfg_obj_ismap(const cfg_obj_t *obj); 163/*%< 164 * Return true iff 'obj' is of a map type. 165 */ 166 167isc_result_t 168cfg_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 183isc_result_t 184cfg_map_set(cfg_obj_t *mapobj, const char* name, const cfg_obj_t *obj); 185/*%< 186 * Add an element to a configuration object, which 187 * must be of a map type. 188 * 189 * Requires: 190 * \li 'mapobj' points to a valid configuration object of a map type. 191 * \li 'name' points to a null-terminated string. 192 * \li 'obj' is non-NULL. 193 * 194 * Returns: 195 * \li #ISC_R_SUCCESS - success 196 * \li #ISC_R_NOTFOUND - name not found in map 197 */ 198 199isc_result_t 200cfg_map_delete(cfg_obj_t *mapobj, const char* name); 201/*%< 202 * Remove an element from a configuration object, which 203 * must be of a map type. 204 * 205 * Requires: 206 * \li 'mapobj' points to a valid configuration object of a map type. 207 * \li 'name' points to a null-terminated string. 208 * 209 * Returns: 210 * \li #ISC_R_SUCCESS - success 211 * \li #ISC_R_NOTFOUND - name not found in map 212 */ 213 214isc_result_t 215cfg_map_move(cfg_obj_t *mapobjdst, cfg_obj_t *mapobjsrc, const char* name); 216/*%< 217 * Remove an element from one map object and add it another map object. 218 * 219 * Requires: 220 * \li 'mapobjdst' points to a valid configuration object of a map type. 221 * \li 'mapobjsrc' points to a valid configuration object of a map type. 222 * \li 'name' points to a null-terminated string. 223 * \li 'obj' is non-NULL. 224 * 225 * Returns: 226 * \li #ISC_R_SUCCESS - success 227 * \li #ISC_R_NOTFOUND - name not found in map 228 */ 229 230isc_result_t 231cfg_map_moveall(cfg_obj_t *mapobjdst, cfg_obj_t *mapobjsrc); 232/*%< 233 * Remove all elements from one map object and add all to another map object. 234 * 235 * Requires: 236 * \li 'mapobjdst' points to a valid configuration object of a map type. 237 * \li 'mapobjsrc' points to a valid configuration object of a map type. 238 * 239 * Returns: 240 * \li #ISC_R_SUCCESS - success 241 * \li other appropriate error code. 242 */ 243 244const cfg_obj_t * 245cfg_map_getname(const cfg_obj_t *mapobj); 246/*%< 247 * Get the name of a named map object, like a server "key" clause. 248 * 249 * Requires: 250 * \li 'mapobj' points to a valid configuration object of a map type. 251 * 252 * Returns: 253 * \li A pointer to a configuration object naming the map object, 254 * or NULL if the map object does not have a name. 255 */ 256 257isc_boolean_t 258cfg_obj_istuple(const cfg_obj_t *obj); 259/*%< 260 * Return true iff 'obj' is of a map type. 261 */ 262 263const cfg_obj_t * 264cfg_tuple_get(const cfg_obj_t *tupleobj, const char *name); 265/*%< 266 * Extract an element from a configuration object, which 267 * must be of a tuple type. 268 * 269 * Requires: 270 * \li 'tupleobj' points to a valid configuration object of a tuple type. 271 * \li 'name' points to a null-terminated string naming one of the 272 *\li fields of said tuple type. 273 */ 274 275isc_result_t 276cfg_tuple_set(cfg_obj_t *tupleobj, const char *name, const cfg_obj_t *obj); 277/*%< 278 * Set an element in a configuration object tuple. 279 * 280 * Requires: 281 * \li 'tupleobj' points to a valid configuration object of a tuple type. 282 * \li 'name' points to a null-terminated string naming one of the 283 * \li fields of said tuple type. 284 * \li 'obj' points to a valid configuration object. 285 * Returns: 286 * \li #ISC_R_SUCCESS - success 287 * \li #ISC_R_NOTFOUND - name not found in tuple 288 */ 289 290isc_boolean_t 291cfg_obj_isuint32(const cfg_obj_t *obj); 292/*%< 293 * Return true iff 'obj' is of integer type. 294 */ 295 296isc_uint32_t 297cfg_obj_asuint32(const cfg_obj_t *obj); 298/*%< 299 * Returns the value of a configuration object of 32-bit integer type. 300 * 301 * Requires: 302 * \li 'obj' points to a valid configuration object of 32-bit integer type. 303 * 304 * Returns: 305 * \li A 32-bit unsigned integer. 306 */ 307 308isc_boolean_t 309cfg_obj_isuint64(const cfg_obj_t *obj); 310/*%< 311 * Return true iff 'obj' is of integer type. 312 */ 313 314isc_uint64_t 315cfg_obj_asuint64(const cfg_obj_t *obj); 316/*%< 317 * Returns the value of a configuration object of 64-bit integer type. 318 * 319 * Requires: 320 * \li 'obj' points to a valid configuration object of 64-bit integer type. 321 * 322 * Returns: 323 * \li A 64-bit unsigned integer. 324 */ 325 326isc_boolean_t 327cfg_obj_isstring(const cfg_obj_t *obj); 328/*%< 329 * Return true iff 'obj' is of string type. 330 */ 331 332const char * 333cfg_obj_asstring(const cfg_obj_t *obj); 334/*%< 335 * Returns the value of a configuration object of a string type 336 * as a null-terminated string. 337 * 338 * Requires: 339 * \li 'obj' points to a valid configuration object of a string type. 340 * 341 * Returns: 342 * \li A pointer to a null terminated string. 343 */ 344 345isc_boolean_t 346cfg_obj_isboolean(const cfg_obj_t *obj); 347/*%< 348 * Return true iff 'obj' is of a boolean type. 349 */ 350 351isc_boolean_t 352cfg_obj_asboolean(const cfg_obj_t *obj); 353/*%< 354 * Returns the value of a configuration object of a boolean type. 355 * 356 * Requires: 357 * \li 'obj' points to a valid configuration object of a boolean type. 358 * 359 * Returns: 360 * \li A boolean value. 361 */ 362 363isc_boolean_t 364cfg_obj_issockaddr(const cfg_obj_t *obj); 365/*%< 366 * Return true iff 'obj' is a socket address. 367 */ 368 369const isc_sockaddr_t * 370cfg_obj_assockaddr(const cfg_obj_t *obj); 371/*%< 372 * Returns the value of a configuration object representing a socket address. 373 * 374 * Requires: 375 * \li 'obj' points to a valid configuration object of a socket address type. 376 * 377 * Returns: 378 * \li A pointer to a sockaddr. The sockaddr must be copied by the caller 379 * if necessary. 380 */ 381 382isc_boolean_t 383cfg_obj_isnetprefix(const cfg_obj_t *obj); 384/*%< 385 * Return true iff 'obj' is a network prefix. 386 */ 387 388void 389cfg_obj_asnetprefix(const cfg_obj_t *obj, isc_netaddr_t *netaddr, 390 unsigned int *prefixlen); 391/*%< 392 * Gets the value of a configuration object representing a network 393 * prefix. The network address is returned through 'netaddr' and the 394 * prefix length in bits through 'prefixlen'. 395 * 396 * Requires: 397 * \li 'obj' points to a valid configuration object of network prefix type. 398 *\li 'netaddr' and 'prefixlen' are non-NULL. 399 */ 400 401isc_boolean_t 402cfg_obj_islist(const cfg_obj_t *obj); 403/*%< 404 * Return true iff 'obj' is of list type. 405 */ 406 407const cfg_listelt_t * 408cfg_list_first(const cfg_obj_t *obj); 409/*%< 410 * Returns the first list element in a configuration object of a list type. 411 * 412 * Requires: 413 * \li 'obj' points to a valid configuration object of a list type or NULL. 414 * 415 * Returns: 416 * \li A pointer to a cfg_listelt_t representing the first list element, 417 * or NULL if the list is empty or nonexistent. 418 */ 419 420const cfg_listelt_t * 421cfg_list_next(const cfg_listelt_t *elt); 422/*%< 423 * Returns the next element of a list of configuration objects. 424 * 425 * Requires: 426 * \li 'elt' points to cfg_listelt_t obtained from cfg_list_first() or 427 * a previous call to cfg_list_next(). 428 * 429 * Returns: 430 * \li A pointer to a cfg_listelt_t representing the next element, 431 * or NULL if there are no more elements. 432 */ 433 434unsigned int 435cfg_list_length(const cfg_obj_t *obj, isc_boolean_t recurse); 436/*%< 437 * Returns the length of a list of configure objects. If obj is 438 * not a list, returns 0. If recurse is true, add in the length of 439 * all contained lists. 440 */ 441 442cfg_obj_t * 443cfg_listelt_value(const cfg_listelt_t *elt); 444/*%< 445 * Returns the configuration object associated with cfg_listelt_t. 446 * 447 * Requires: 448 * \li 'elt' points to cfg_listelt_t obtained from cfg_list_first() or 449 * cfg_list_next(). 450 * 451 * Returns: 452 * \li A non-NULL pointer to a configuration object. 453 */ 454 455void 456cfg_listelt_setvalue(cfg_listelt_t *elt, const cfg_obj_t *obj); 457/*%< 458 * Sets the configuration object associated with cfg_listelt_t. 459 * 460 * Requires: 461 * \li 'elt' points to cfg_listelt_t obtained from cfg_list_first() or 462 * \li cfg_list_next(). 463 * \li A non-NULL pointer to a configuration object. 464 */ 465 466void 467cfg_destroy_listelt(cfg_parser_t *pctx, cfg_listelt_t **eltp); 468/*%< 469 * Destroy a configuration list element. 470 */ 471 472void 473cfg_print(const cfg_obj_t *obj, 474 void (*f)(void *closure, const char *text, int textlen), 475 void *closure); 476/*%< 477 * Print the configuration object 'obj' by repeatedly calling the 478 * function 'f', passing 'closure' and a region of text starting 479 * at 'text' and comprising 'textlen' characters. 480 */ 481 482void 483cfg_print_grammar(const cfg_type_t *type, 484 void (*f)(void *closure, const char *text, int textlen), 485 void *closure); 486/*%< 487 * Print a summary of the grammar of the configuration type 'type'. 488 */ 489 490isc_boolean_t 491cfg_obj_istype(const cfg_obj_t *obj, const cfg_type_t *type); 492/*%< 493 * Return true iff 'obj' is of type 'type'. 494 */ 495 496void 497cfg_obj_attach(cfg_obj_t *src, cfg_obj_t **dest); 498/*%< 499 * Reference a configuration object. 500 */ 501 502void 503cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj); 504/*%< 505 * Delete a reference to a configuration object; destroy the object if 506 * there are no more references. 507 */ 508 509void 510cfg_obj_log(const cfg_obj_t *obj, isc_log_t *lctx, int level, 511 const char *fmt, ...) 512 ISC_FORMAT_PRINTF(4, 5); 513/*%< 514 * Log a message concerning configuration object 'obj' to the logging 515 * channel of 'pctx', at log level 'level'. The message will be prefixed 516 * with the file name(s) and line number where 'obj' was defined. 517 */ 518 519const char * 520cfg_obj_file(const cfg_obj_t *obj); 521/*%< 522 * Return the file that defined this object. 523 */ 524 525unsigned int 526cfg_obj_line(const cfg_obj_t *obj); 527/*%< 528 * Return the line in file where this object was defined. 529 */ 530 531 532ISC_LANG_ENDDECLS 533 534#endif /* ISCCFG_CFG_H */ 535