1/* $NetBSD: cfg.h,v 1.2.6.1 2012/06/05 21:15:37 bouyer Exp $ */ 2 3/* 4 * Copyright (C) 2004-2007, 2010 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 */ 52typedef 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 */ 59typedef 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 */ 68typedef struct cfg_obj cfg_obj_t; 69 70/*% 71 * A configuration object list element. 72 */ 73typedef 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 */ 80typedef isc_result_t 81(*cfg_parsecallback_t)(const char *clausename, const cfg_obj_t *obj, void *arg); 82 83/*** 84 *** Functions 85 ***/ 86 87ISC_LANG_BEGINDECLS 88 89void 90cfg_parser_attach(cfg_parser_t *src, cfg_parser_t **dest); 91/*%< 92 * Reference a parser object. 93 */ 94 95isc_result_t 96cfg_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 106void 107cfg_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 120isc_result_t 121cfg_parse_file(cfg_parser_t *pctx, const char *filename, 122 const cfg_type_t *type, cfg_obj_t **ret); 123isc_result_t 124cfg_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 149void 150cfg_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 156isc_boolean_t 157cfg_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 163isc_boolean_t 164cfg_obj_ismap(const cfg_obj_t *obj); 165/*%< 166 * Return true iff 'obj' is of a map type. 167 */ 168 169isc_result_t 170cfg_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 185const cfg_obj_t * 186cfg_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 198isc_boolean_t 199cfg_obj_istuple(const cfg_obj_t *obj); 200/*%< 201 * Return true iff 'obj' is of a map type. 202 */ 203 204const cfg_obj_t * 205cfg_tuple_get(const cfg_obj_t *tupleobj, const char *name); 206/*%< 207 * Extract an element from a configuration object, which 208 * must be of a tuple type. 209 * 210 * Requires: 211 * \li 'tupleobj' points to a valid configuration object of a tuple type. 212 * \li 'name' points to a null-terminated string naming one of the 213 *\li fields of said tuple type. 214 */ 215 216isc_boolean_t 217cfg_obj_isuint32(const cfg_obj_t *obj); 218/*%< 219 * Return true iff 'obj' is of integer type. 220 */ 221 222isc_uint32_t 223cfg_obj_asuint32(const cfg_obj_t *obj); 224/*%< 225 * Returns the value of a configuration object of 32-bit integer type. 226 * 227 * Requires: 228 * \li 'obj' points to a valid configuration object of 32-bit integer type. 229 * 230 * Returns: 231 * \li A 32-bit unsigned integer. 232 */ 233 234isc_boolean_t 235cfg_obj_isuint64(const cfg_obj_t *obj); 236/*%< 237 * Return true iff 'obj' is of integer type. 238 */ 239 240isc_uint64_t 241cfg_obj_asuint64(const cfg_obj_t *obj); 242/*%< 243 * Returns the value of a configuration object of 64-bit integer type. 244 * 245 * Requires: 246 * \li 'obj' points to a valid configuration object of 64-bit integer type. 247 * 248 * Returns: 249 * \li A 64-bit unsigned integer. 250 */ 251 252isc_boolean_t 253cfg_obj_isstring(const cfg_obj_t *obj); 254/*%< 255 * Return true iff 'obj' is of string type. 256 */ 257 258const char * 259cfg_obj_asstring(const cfg_obj_t *obj); 260/*%< 261 * Returns the value of a configuration object of a string type 262 * as a null-terminated string. 263 * 264 * Requires: 265 * \li 'obj' points to a valid configuration object of a string type. 266 * 267 * Returns: 268 * \li A pointer to a null terminated string. 269 */ 270 271isc_boolean_t 272cfg_obj_isboolean(const cfg_obj_t *obj); 273/*%< 274 * Return true iff 'obj' is of a boolean type. 275 */ 276 277isc_boolean_t 278cfg_obj_asboolean(const cfg_obj_t *obj); 279/*%< 280 * Returns the value of a configuration object of a boolean type. 281 * 282 * Requires: 283 * \li 'obj' points to a valid configuration object of a boolean type. 284 * 285 * Returns: 286 * \li A boolean value. 287 */ 288 289isc_boolean_t 290cfg_obj_issockaddr(const cfg_obj_t *obj); 291/*%< 292 * Return true iff 'obj' is a socket address. 293 */ 294 295const isc_sockaddr_t * 296cfg_obj_assockaddr(const cfg_obj_t *obj); 297/*%< 298 * Returns the value of a configuration object representing a socket address. 299 * 300 * Requires: 301 * \li 'obj' points to a valid configuration object of a socket address type. 302 * 303 * Returns: 304 * \li A pointer to a sockaddr. The sockaddr must be copied by the caller 305 * if necessary. 306 */ 307 308isc_boolean_t 309cfg_obj_isnetprefix(const cfg_obj_t *obj); 310/*%< 311 * Return true iff 'obj' is a network prefix. 312 */ 313 314void 315cfg_obj_asnetprefix(const cfg_obj_t *obj, isc_netaddr_t *netaddr, 316 unsigned int *prefixlen); 317/*%< 318 * Gets the value of a configuration object representing a network 319 * prefix. The network address is returned through 'netaddr' and the 320 * prefix length in bits through 'prefixlen'. 321 * 322 * Requires: 323 * \li 'obj' points to a valid configuration object of network prefix type. 324 *\li 'netaddr' and 'prefixlen' are non-NULL. 325 */ 326 327isc_boolean_t 328cfg_obj_islist(const cfg_obj_t *obj); 329/*%< 330 * Return true iff 'obj' is of list type. 331 */ 332 333const cfg_listelt_t * 334cfg_list_first(const cfg_obj_t *obj); 335/*%< 336 * Returns the first list element in a configuration object of a list type. 337 * 338 * Requires: 339 * \li 'obj' points to a valid configuration object of a list type or NULL. 340 * 341 * Returns: 342 * \li A pointer to a cfg_listelt_t representing the first list element, 343 * or NULL if the list is empty or nonexistent. 344 */ 345 346const cfg_listelt_t * 347cfg_list_next(const cfg_listelt_t *elt); 348/*%< 349 * Returns the next element of a list of configuration objects. 350 * 351 * Requires: 352 * \li 'elt' points to cfg_listelt_t obtained from cfg_list_first() or 353 * a previous call to cfg_list_next(). 354 * 355 * Returns: 356 * \li A pointer to a cfg_listelt_t representing the next element, 357 * or NULL if there are no more elements. 358 */ 359 360unsigned int 361cfg_list_length(const cfg_obj_t *obj, isc_boolean_t recurse); 362/*%< 363 * Returns the length of a list of configure objects. If obj is 364 * not a list, returns 0. If recurse is true, add in the length of 365 * all contained lists. 366 */ 367 368cfg_obj_t * 369cfg_listelt_value(const cfg_listelt_t *elt); 370/*%< 371 * Returns the configuration object associated with cfg_listelt_t. 372 * 373 * Requires: 374 * \li 'elt' points to cfg_listelt_t obtained from cfg_list_first() or 375 * cfg_list_next(). 376 * 377 * Returns: 378 * \li A non-NULL pointer to a configuration object. 379 */ 380 381void 382cfg_print(const cfg_obj_t *obj, 383 void (*f)(void *closure, const char *text, int textlen), 384 void *closure); 385/*%< 386 * Print the configuration object 'obj' by repeatedly calling the 387 * function 'f', passing 'closure' and a region of text starting 388 * at 'text' and comprising 'textlen' characters. 389 */ 390 391void 392cfg_print_grammar(const cfg_type_t *type, 393 void (*f)(void *closure, const char *text, int textlen), 394 void *closure); 395/*%< 396 * Print a summary of the grammar of the configuration type 'type'. 397 */ 398 399isc_boolean_t 400cfg_obj_istype(const cfg_obj_t *obj, const cfg_type_t *type); 401/*%< 402 * Return true iff 'obj' is of type 'type'. 403 */ 404 405void 406cfg_obj_attach(cfg_obj_t *src, cfg_obj_t **dest); 407/*%< 408 * Reference a configuration object. 409 */ 410 411void 412cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj); 413/*%< 414 * Delete a reference to a configuration object; destroy the object if 415 * there are no more references. 416 */ 417 418void 419cfg_obj_log(const cfg_obj_t *obj, isc_log_t *lctx, int level, 420 const char *fmt, ...) 421 ISC_FORMAT_PRINTF(4, 5); 422/*%< 423 * Log a message concerning configuration object 'obj' to the logging 424 * channel of 'pctx', at log level 'level'. The message will be prefixed 425 * with the file name(s) and line number where 'obj' was defined. 426 */ 427 428const char * 429cfg_obj_file(const cfg_obj_t *obj); 430/*%< 431 * Return the file that defined this object. 432 */ 433 434unsigned int 435cfg_obj_line(const cfg_obj_t *obj); 436/*%< 437 * Return the line in file where this object was defined. 438 */ 439 440 441ISC_LANG_ENDDECLS 442 443#endif /* ISCCFG_CFG_H */ 444