cfg.h 9.85 KB
Newer Older
1
/*
2
 * Copyright (C) 2000, 2001  Internet Software Consortium.
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
 * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
 * INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
 * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
 * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

Brian Wellington's avatar
Brian Wellington committed
18
/* $Id: cfg.h,v 1.22 2001/03/27 02:06:12 bwelling Exp $ */
19

Brian Wellington's avatar
Brian Wellington committed
20 21
#ifndef ISCCFG_CFG_H
#define ISCCFG_CFG_H 1
22 23 24 25 26 27 28 29 30 31 32 33 34 35

/*****
 ***** Module Info
 *****/

/*
 * This is the new, table-driven, YACC-free configuration file parser.
 */


/***
 *** Imports
 ***/

36
#include <isc/formatcheck.h>
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
#include <isc/lang.h>
#include <isc/types.h>
#include <isc/list.h>


/***
 *** Types
 ***/

typedef struct cfg_parser cfg_parser_t;
/*
 * A configuration parser.
 */

/*
 * A configuration type definition object.  There is a single
 * static cfg_type_t object for each data type supported by
 * the configuration parser.
 */
typedef struct cfg_type cfg_type_t;

/*
 * A configuration object.  This is the basic building block of the
 * configuration parse tree.  It contains a value (which may be
 * of one of several types) and information identifying the file
 * and line number the value came from, for printing error
 * messages.
 */
typedef struct cfg_obj cfg_obj_t;

67 68 69 70 71
/*
 * A configuration object list element.
 */
typedef struct cfg_listelt cfg_listelt_t;

72 73 74 75 76 77 78 79
/*
 * A callback function to be called when parsing an option 
 * that needs to be interpreted at parsing time, like
 * "directory".
 */
typedef isc_result_t
(*cfg_parsecallback_t)(const char *clausename, cfg_obj_t *obj, void *arg);

80 81 82 83 84 85 86 87 88 89 90 91 92
/***
 *** Functions
 ***/

ISC_LANG_BEGINDECLS

isc_result_t
cfg_parser_create(isc_mem_t *mctx, isc_log_t *lctx, cfg_parser_t **ret);
/*
 * Create a configuration file parser.  Any warning and error
 * messages will be logged to 'lctx'.
 */

93 94 95 96 97 98 99 100 101 102 103 104 105 106
void
cfg_parser_setcallback(cfg_parser_t *pctx,
		       cfg_parsecallback_t callback,
		       void *arg);
/*
 * Make the parser call 'callback' whenever it encounters
 * a configuration clause with the callback attribute,
 * passing it the clause name, the clause value,
 * and 'arg' as arguments.
 *
 * To restore the default of not invoking callbacks, pass
 * callback==NULL and arg==NULL.
 */

107
isc_result_t
Brian Wellington's avatar
Brian Wellington committed
108
cfg_parse_file(cfg_parser_t *pctx, const char *filename,
109
	       cfg_type_t *type, cfg_obj_t **ret);
110 111 112
isc_result_t
cfg_parse_buffer(cfg_parser_t *pctx, isc_buffer_t *buffer,
		 cfg_type_t *type, cfg_obj_t **ret);
113
/*
114
 * Read a configuration containing data of type 'type'
115
 * and make '*ret' point to its parse tree.
116 117 118 119 120
 *
 * The configuration is read from the file 'filename'
 * (isc_parse_file()) or the buffer 'buffer'
 * (isc_parse_buffer()).
 *
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141
 * Returns an error if the file does not parse correctly.
 * 
 * Requires:
 *      "filename" is valid.
 *      "mem" is valid.
 *	"type" is valid.
 *      "cfg" is non-NULL and "*cfg" is NULL.
 *
 * Returns:
 *      ISC_R_SUCCESS                 - success
 *      ISC_R_NOMEMORY                - no memory available
 *      ISC_R_INVALIDFILE             - file doesn't exist or is unreadable
 *      others	                      - file contains errors
 */

void
cfg_parser_destroy(cfg_parser_t **pctxp);
/*
 * Destroy a configuration parser.
 */

142 143 144 145 146 147 148 149 150 151 152 153 154
isc_boolean_t
cfg_obj_isvoid(cfg_obj_t *obj);
/*
 * Return true iff 'obj' is of void type (e.g., an optional 
 * value not specified).
 */

isc_boolean_t
cfg_obj_ismap(cfg_obj_t *obj);
/*
 * Return true iff 'obj' is of a map type.
 */

155 156 157 158 159 160 161
isc_result_t
cfg_map_get(cfg_obj_t *mapobj, const char* name, cfg_obj_t **obj);
/*
 * Extract an element from a configuration object, which
 * must be of a map type.
 *
 * Requires:
Andreas Gustafsson's avatar
Andreas Gustafsson committed
162
 *      'mapobj' points to a valid configuration object of a map type.
163 164 165 166 167 168 169 170
 *      'name' points to a null-terminated string.
 * 	'obj' is non-NULL and '*obj' is NULL.
 *
 * Returns:
 *      ISC_R_SUCCESS                  - success
 *      ISC_R_NOTFOUND                 - name not found in map
 */

171 172 173 174 175 176
cfg_obj_t *
cfg_map_getname(cfg_obj_t *mapobj);
/*
 * Get the name of a named map object, like a server "key" clause.
 *
 * Requires:
Andreas Gustafsson's avatar
Andreas Gustafsson committed
177
 *      'mapobj' points to a valid configuration object of a map type.
178 179 180 181 182
 *
 * Returns:
 *      A pointer to a configuration object naming the map object,
 *	or NULL if the map object does not have a name.
 */
183

184 185 186 187 188 189
isc_boolean_t
cfg_obj_istuple(cfg_obj_t *obj);
/*
 * Return true iff 'obj' is of a map type.
 */

190
cfg_obj_t *
Brian Wellington's avatar
typos  
Brian Wellington committed
191
cfg_tuple_get(cfg_obj_t *tupleobj, const char *name);
192 193 194 195 196
/*
 * Extract an element from a configuration object, which
 * must be of a tuple type.
 *
 * Requires:
Andreas Gustafsson's avatar
Andreas Gustafsson committed
197
 *      'tupleobj' points to a valid configuration object of a tuple type.
198 199 200 201
 *      'name' points to a null-terminated string naming one of the
 *	fields of said tuple type.
 */

202 203 204 205 206 207
isc_boolean_t
cfg_obj_isuint32(cfg_obj_t *obj);
/*
 * Return true iff 'obj' is of integer type.
 */

208 209 210
isc_uint32_t
cfg_obj_asuint32(cfg_obj_t *obj);
/*
211
 * Returns the value of a configuration object of 32-bit integer type.
212 213
 *
 * Requires:
214
 *      'obj' points to a valid configuration object of 32-bit integer type.
215 216 217
 *
 * Returns:
 *      A 32-bit unsigned integer.
218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235
 */

isc_boolean_t
cfg_obj_isuint64(cfg_obj_t *obj);
/*
 * Return true iff 'obj' is of integer type.
 */

isc_uint64_t
cfg_obj_asuint64(cfg_obj_t *obj);
/*
 * Returns the value of a configuration object of 64-bit integer type.
 *
 * Requires:
 *      'obj' points to a valid configuration object of 64-bit integer type.
 *
 * Returns:
 *      A 64-bit unsigned integer.
236 237
 */

238 239 240 241 242 243
isc_boolean_t
cfg_obj_isstring(cfg_obj_t *obj);
/*
 * Return true iff 'obj' is of string type.
 */

244 245 246 247 248 249 250 251 252 253 254 255 256
char *
cfg_obj_asstring(cfg_obj_t *obj);
/*
 * Returns the value of a configuration object of a string type
 * as a null-terminated string.
 *
 * Requires:
 *      'obj' points to a valid configuration object of a string type.
 *
 * Returns:
 *      A pointer to a null terminated string.
 */

257 258 259 260 261 262
isc_boolean_t
cfg_obj_isboolean(cfg_obj_t *obj);
/*
 * Return true iff 'obj' is of a boolean type.
 */

Brian Wellington's avatar
Brian Wellington committed
263 264 265 266 267 268 269 270 271 272 273 274
isc_boolean_t
cfg_obj_asboolean(cfg_obj_t *obj);
/*
 * Returns the value of a configuration object of a boolean type.
 *
 * Requires:
 *      'obj' points to a valid configuration object of a boolean type.
 *
 * Returns:
 *      A boolean value.
 */

275 276 277
isc_boolean_t
cfg_obj_issockaddr(cfg_obj_t *obj);
/*
278
 * Return true iff 'obj' is a socket address.
279 280
 */

Brian Wellington's avatar
Brian Wellington committed
281 282 283
isc_sockaddr_t *
cfg_obj_assockaddr(cfg_obj_t *obj);
/*
284
 * Returns the value of a configuration object representing a socket address.
Brian Wellington's avatar
Brian Wellington committed
285 286 287 288 289 290 291 292
 *
 * Requires:
 *      'obj' points to a valid configuration object of a socket address type.
 *
 * Returns:
 *      A pointer to a sockaddr.  The sockaddr must be copied by the caller
 *      if necessary.
 */
293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311

isc_boolean_t
cfg_obj_isnetprefix(cfg_obj_t *obj);
/*
 * Return true iff 'obj' is a network prefix.
 */

void
cfg_obj_asnetprefix(cfg_obj_t *obj, isc_netaddr_t *netaddr,
		    unsigned int *prefixlen);
/*
 * Gets the value of a configuration object representing a network
 * prefix.  The network address is returned through 'netaddr' and the
 * prefix length in bits through 'prefixlen'.
 *
 * Requires:
 *      'obj' points to a valid configuration object of network prefix type.
 *	'netaddr' and 'prefixlen' are non-NULL.
 */
Brian Wellington's avatar
Brian Wellington committed
312

313 314 315 316 317 318
isc_boolean_t
cfg_obj_islist(cfg_obj_t *obj);
/*
 * Return true iff 'obj' is of list type.
 */

319 320 321 322 323 324
cfg_listelt_t *
cfg_list_first(cfg_obj_t *obj);
/*
 * Returns the first list element in a configuration object of a list type.
 *
 * Requires:
325
 *      'obj' points to a valid configuration object of a list type or NULL.
326 327 328
 *
 * Returns:
 *      A pointer to a cfg_listelt_t representing the first list element,
329
 * 	or NULL if the list is empty or nonexistent.
330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358
 */

cfg_listelt_t *
cfg_list_next(cfg_listelt_t *elt);
/*
 * Returns the next element of a list of configuration objects.
 *
 * Requires:
 *      'elt' points to cfg_listelt_t obtained from cfg_list_first() or
 *	a previous call to cfg_list_next().
 *
 * Returns:
 *      A pointer to a cfg_listelt_t representing the next element,
 * 	or NULL if there are no more elements.
 */

cfg_obj_t *
cfg_listelt_value(cfg_listelt_t *elt);
/*
 * Returns the configuration object associated with cfg_listelt_t.
 *
 * Requires:
 *      'elt' points to cfg_listelt_t obtained from cfg_list_first() or
 *	cfg_list_next().
 *
 * Returns:
 *      A non-NULL pointer to a configuration object.
 */

359 360 361 362 363 364 365 366 367 368
void
cfg_print(cfg_obj_t *obj,
	  void (*f)(void *closure, const char *text, int textlen),
	  void *closure);
/*
 * Print the configuration object 'obj' by repeatedly calling the
 * function 'f', passing 'closure' and a region of text starting
 * at 'text' and comprising 'textlen' characters.
 */

369 370 371 372 373 374
isc_boolean_t
cfg_obj_istype(cfg_obj_t *obj, cfg_type_t *type);
/*
 * Return true iff 'obj' is of type 'type'. 
 */

375 376 377 378 379
void cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj);
/*
 * Destroy a configuration object.
 */

Andreas Gustafsson's avatar
Andreas Gustafsson committed
380
void
381 382
cfg_obj_log(cfg_obj_t *obj, isc_log_t *lctx, int level, const char *fmt, ...)
	ISC_FORMAT_PRINTF(4, 5);
Andreas Gustafsson's avatar
Andreas Gustafsson committed
383 384 385 386 387 388
/*
 * Log a message concerning configuration object 'obj' to the logging
 * channel of 'pctx', at log level 'level'.  The message will be prefixed
 * with the file name(s) and line number where 'obj' was defined.
 */

389 390 391 392
/*
 * Configuration object types.
 */
extern cfg_type_t cfg_type_namedconf; /* A complete named.conf file. */
393
extern cfg_type_t cfg_type_rndcconf; /* A complete rndc.conf file. */
394 395
extern cfg_type_t cfg_type_rndcconf; /* A complete rndc.conf file. */
extern cfg_type_t cfg_type_keyref; /* A key reference, used as an ACL element */
396 397 398

ISC_LANG_ENDDECLS

Brian Wellington's avatar
Brian Wellington committed
399
#endif /* ISCCFG_CFG_H */