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