cfg.h 14 KB
Newer Older
1
/*
2
 * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
3
 *
4 5 6
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
7 8 9
 *
 * See the COPYRIGHT file distributed with this work for additional
 * information regarding copyright ownership.
10 11
 */

Brian Wellington's avatar
Brian Wellington committed
12 13
#ifndef ISCCFG_CFG_H
#define ISCCFG_CFG_H 1
14 15 16 17 18

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

19
/*! \file isccfg/cfg.h
20
 * \brief
21 22 23 24 25 26 27
 * This is the new, table-driven, YACC-free configuration file parser.
 */

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

28
#include <isc/formatcheck.h>
29
#include <isc/lang.h>
30
#include <isc/refcount.h>
31 32 33 34 35 36 37
#include <isc/types.h>
#include <isc/list.h>

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

38
/*%
39 40
 * A configuration parser.
 */
41
typedef struct cfg_parser cfg_parser_t;
42

43
/*%
44 45 46 47 48 49
 * 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;

50
/*%
51 52 53 54 55 56 57 58
 * 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;

59
/*%
60 61 62 63
 * A configuration object list element.
 */
typedef struct cfg_listelt cfg_listelt_t;

64
/*%
Automatic Updater's avatar
Automatic Updater committed
65
 * A callback function to be called when parsing an option
66 67 68 69
 * that needs to be interpreted at parsing time, like
 * "directory".
 */
typedef isc_result_t
70
(*cfg_parsecallback_t)(const char *clausename, const cfg_obj_t *obj, void *arg);
71

72 73 74 75 76 77
/***
 *** Functions
 ***/

ISC_LANG_BEGINDECLS

78 79 80 81 82 83
void
cfg_parser_attach(cfg_parser_t *src, cfg_parser_t **dest);
/*%<
 * Reference a parser object.
 */

84 85
isc_result_t
cfg_parser_create(isc_mem_t *mctx, isc_log_t *lctx, cfg_parser_t **ret);
86
/*%<
87 88
 * Create a configuration file parser.  Any warning and error
 * messages will be logged to 'lctx'.
89 90 91 92
 *
 * The parser object returned can be used for a single call
 * to cfg_parse_file() or cfg_parse_buffer().  It must not
 * be reused for parsing multiple files or buffers.
93 94
 */

95 96 97 98
void
cfg_parser_setcallback(cfg_parser_t *pctx,
		       cfg_parsecallback_t callback,
		       void *arg);
99
/*%<
100 101 102 103 104 105 106 107 108
 * 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.
 */

109
isc_result_t
110
cfg_parse_file(cfg_parser_t *pctx, const char *file,
111
	       const cfg_type_t *type, cfg_obj_t **ret);
112

113 114
isc_result_t
cfg_parse_buffer(cfg_parser_t *pctx, isc_buffer_t *buffer,
115
		 const cfg_type_t *type, cfg_obj_t **ret);
116 117
isc_result_t
cfg_parse_buffer2(cfg_parser_t *pctx, isc_buffer_t *buffer,
118
		  const char *file, const cfg_type_t *type,
119
		  cfg_obj_t **ret);
120 121 122 123
isc_result_t
cfg_parse_buffer3(cfg_parser_t *pctx, isc_buffer_t *buffer,
		  const char *file, unsigned int line,
		  const cfg_type_t *type, cfg_obj_t **ret);
124 125 126 127 128
isc_result_t
cfg_parse_buffer4(cfg_parser_t *pctx, isc_buffer_t *buffer,
		  const char *file, unsigned int line,
		  const cfg_type_t *type, unsigned int flags,
		  cfg_obj_t **ret);
129
/*%<
130
 * Read a configuration containing data of type 'type'
131
 * and make '*ret' point to its parse tree.
132 133 134 135 136
 *
 * The configuration is read from the file 'filename'
 * (isc_parse_file()) or the buffer 'buffer'
 * (isc_parse_buffer()).
 *
137 138 139 140 141 142
 * If 'file' is not NULL, it is the name of the file, or a name to use
 * for the buffer in place of the filename, when logging errors.
 *
 * If 'line' is not 0, then it is the beginning line number to report
 * when logging errors. This is useful when passing text that has been
 * read from the middle of a file.
143
 *
144
 * Returns an error if the file or buffer does not parse correctly.
Automatic Updater's avatar
Automatic Updater committed
145
 *
146
 * Requires:
147 148 149 150
 *\li 	"filename" is valid.
 *\li 	"mem" is valid.
 *\li	"type" is valid.
 *\li 	"cfg" is non-NULL and "*cfg" is NULL.
151
 *\li   "flags" be one or more of CFG_PCTX_NODEPRECATED or zero.
152 153
 *
 * Returns:
154 155 156 157
 *     \li #ISC_R_SUCCESS                 - success
 *\li      #ISC_R_NOMEMORY                - no memory available
 *\li      #ISC_R_INVALIDFILE             - file doesn't exist or is unreadable
 *\li      others	                      - file contains errors
158 159
 */

160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179
isc_result_t
cfg_parser_mapadd(cfg_parser_t *pctx, cfg_obj_t *mapobj,
		  cfg_obj_t *obj, const char *clause);
/*%<
 * Add the object 'obj' to the specified clause in mapbody 'mapobj'.
 * Used for adding new zones.
 *
 * Require:
 * \li     'obj' is a valid cfg_obj_t.
 * \li     'mapobj' is a valid cfg_obj_t of type map.
 * \li     'pctx' is a valid cfg_parser_t.
 */

void
cfg_parser_reset(cfg_parser_t *pctx);
/*%<
 * Reset an existing parser so it can be re-used for a new file or
 * buffer.
 */

180 181
void
cfg_parser_destroy(cfg_parser_t **pctxp);
182
/*%<
183 184
 * Remove a reference to a configuration parser; destroy it if there are no
 * more references.
185 186
 */

187
isc_boolean_t
188
cfg_obj_isvoid(const cfg_obj_t *obj);
189
/*%<
Automatic Updater's avatar
Automatic Updater committed
190
 * Return true iff 'obj' is of void type (e.g., an optional
191 192 193 194
 * value not specified).
 */

isc_boolean_t
195
cfg_obj_ismap(const cfg_obj_t *obj);
196
/*%<
197 198 199
 * Return true iff 'obj' is of a map type.
 */

200 201 202 203 204 205 206 207 208 209 210 211
isc_boolean_t
cfg_obj_isfixedpoint(const cfg_obj_t *obj);
/*%<
 * Return true iff 'obj' is of a fixedpoint type.
 */

isc_boolean_t
cfg_obj_ispercentage(const cfg_obj_t *obj);
/*%<
 * Return true iff 'obj' is of a percentage type.
 */

212
isc_result_t
213
cfg_map_get(const cfg_obj_t *mapobj, const char* name, const cfg_obj_t **obj);
214
/*%<
215 216 217 218
 * Extract an element from a configuration object, which
 * must be of a map type.
 *
 * Requires:
219 220 221
 * \li     'mapobj' points to a valid configuration object of a map type.
 * \li     'name' points to a null-terminated string.
 * \li	'obj' is non-NULL and '*obj' is NULL.
222 223
 *
 * Returns:
224 225
 * \li     #ISC_R_SUCCESS                  - success
 * \li     #ISC_R_NOTFOUND                 - name not found in map
226 227
 */

228 229
const cfg_obj_t *
cfg_map_getname(const cfg_obj_t *mapobj);
230
/*%<
231 232 233
 * Get the name of a named map object, like a server "key" clause.
 *
 * Requires:
234
 *    \li  'mapobj' points to a valid configuration object of a map type.
235 236
 *
 * Returns:
237
 * \li     A pointer to a configuration object naming the map object,
238 239
 *	or NULL if the map object does not have a name.
 */
240

Evan Hunt's avatar
Evan Hunt committed
241 242 243 244 245 246 247 248 249 250 251 252
unsigned int
cfg_map_count(const cfg_obj_t *mapobj);
/*%<
 * Get the number of elements defined in the symbol table of a map object.
 *
 * Requires:
 *    \li  'mapobj' points to a valid configuration object of a map type.
 *
 * Returns:
 * \li     The number of elements in the map object.
 */

253
isc_boolean_t
254
cfg_obj_istuple(const cfg_obj_t *obj);
255
/*%<
256 257 258
 * Return true iff 'obj' is of a map type.
 */

259 260
const cfg_obj_t *
cfg_tuple_get(const cfg_obj_t *tupleobj, const char *name);
261
/*%<
262 263 264 265
 * Extract an element from a configuration object, which
 * must be of a tuple type.
 *
 * Requires:
266 267 268
 * \li     'tupleobj' points to a valid configuration object of a tuple type.
 * \li     'name' points to a null-terminated string naming one of the
 *\li	fields of said tuple type.
269 270
 */

271
isc_boolean_t
272
cfg_obj_isuint32(const cfg_obj_t *obj);
273
/*%<
274 275 276
 * Return true iff 'obj' is of integer type.
 */

277
isc_uint32_t
278
cfg_obj_asuint32(const cfg_obj_t *obj);
279
/*%<
280
 * Returns the value of a configuration object of 32-bit integer type.
281 282
 *
 * Requires:
283
 * \li     'obj' points to a valid configuration object of 32-bit integer type.
284 285
 *
 * Returns:
286
 * \li     A 32-bit unsigned integer.
287 288 289
 */

isc_boolean_t
290
cfg_obj_isuint64(const cfg_obj_t *obj);
291
/*%<
292 293 294 295
 * Return true iff 'obj' is of integer type.
 */

isc_uint64_t
296
cfg_obj_asuint64(const cfg_obj_t *obj);
297
/*%<
298 299 300
 * Returns the value of a configuration object of 64-bit integer type.
 *
 * Requires:
301
 * \li     'obj' points to a valid configuration object of 64-bit integer type.
302 303
 *
 * Returns:
304
 * \li     A 64-bit unsigned integer.
305 306
 */

Evan Hunt's avatar
Evan Hunt committed
307 308 309 310 311 312 313 314 315 316 317 318
isc_uint32_t
cfg_obj_asfixedpoint(const cfg_obj_t *obj);
/*%<
 * Returns the value of a configuration object of fixed point number.
 *
 * Requires:
 * \li     'obj' points to a valid configuration object of fixed point type.
 *
 * Returns:
 * \li     A 32-bit unsigned integer.
 */

319 320 321 322 323 324 325 326 327 328 329 330
isc_uint32_t
cfg_obj_aspercentage(const cfg_obj_t *obj);
/*%<
 * Returns the value of a configuration object of percentage
 *
 * Requires:
 * \li     'obj' points to a valid configuration object of percentage type.
 *
 * Returns:
 * \li     A 32-bit unsigned integer.
 */

331
isc_boolean_t
332
cfg_obj_isstring(const cfg_obj_t *obj);
333
/*%<
334 335 336
 * Return true iff 'obj' is of string type.
 */

337
const char *
338
cfg_obj_asstring(const cfg_obj_t *obj);
339
/*%<
340 341 342 343
 * Returns the value of a configuration object of a string type
 * as a null-terminated string.
 *
 * Requires:
344
 * \li     'obj' points to a valid configuration object of a string type.
345 346
 *
 * Returns:
347
 * \li     A pointer to a null terminated string.
348 349
 */

350
isc_boolean_t
351
cfg_obj_isboolean(const cfg_obj_t *obj);
352
/*%<
353 354 355
 * Return true iff 'obj' is of a boolean type.
 */

Brian Wellington's avatar
Brian Wellington committed
356
isc_boolean_t
357
cfg_obj_asboolean(const cfg_obj_t *obj);
358
/*%<
Brian Wellington's avatar
Brian Wellington committed
359 360 361
 * Returns the value of a configuration object of a boolean type.
 *
 * Requires:
362
 * \li     'obj' points to a valid configuration object of a boolean type.
Brian Wellington's avatar
Brian Wellington committed
363 364
 *
 * Returns:
365
 * \li     A boolean value.
Brian Wellington's avatar
Brian Wellington committed
366 367
 */

368
isc_boolean_t
369
cfg_obj_issockaddr(const cfg_obj_t *obj);
370
/*%<
371
 * Return true iff 'obj' is a socket address.
372 373
 */

374 375
const isc_sockaddr_t *
cfg_obj_assockaddr(const cfg_obj_t *obj);
376
/*%<
377
 * Returns the value of a configuration object representing a socket address.
Brian Wellington's avatar
Brian Wellington committed
378 379
 *
 * Requires:
380
 * \li     'obj' points to a valid configuration object of a socket address type.
Brian Wellington's avatar
Brian Wellington committed
381 382
 *
 * Returns:
383
 * \li     A pointer to a sockaddr.  The sockaddr must be copied by the caller
Brian Wellington's avatar
Brian Wellington committed
384 385
 *      if necessary.
 */
386

Evan Hunt's avatar
Evan Hunt committed
387 388 389 390 391 392 393
isc_dscp_t
cfg_obj_getdscp(const cfg_obj_t *obj);
/*%<
 * Returns the DSCP value of a configuration object representing a
 * socket address.
 *
 * Requires:
Tinderbox User's avatar
Tinderbox User committed
394
 * \li     'obj' points to a valid configuration object of a
Evan Hunt's avatar
Evan Hunt committed
395 396 397 398 399 400
 *         socket address type.
 *
 * Returns:
 * \li     DSCP value associated with a sockaddr, or -1.
 */

401
isc_boolean_t
402
cfg_obj_isnetprefix(const cfg_obj_t *obj);
403
/*%<
404 405 406 407
 * Return true iff 'obj' is a network prefix.
 */

void
408
cfg_obj_asnetprefix(const cfg_obj_t *obj, isc_netaddr_t *netaddr,
409
		    unsigned int *prefixlen);
410
/*%<
411 412 413 414 415
 * 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:
416 417
 * \li     'obj' points to a valid configuration object of network prefix type.
 *\li	'netaddr' and 'prefixlen' are non-NULL.
418
 */
Brian Wellington's avatar
Brian Wellington committed
419

420
isc_boolean_t
421
cfg_obj_islist(const cfg_obj_t *obj);
422
/*%<
423 424 425
 * Return true iff 'obj' is of list type.
 */

426 427
const cfg_listelt_t *
cfg_list_first(const cfg_obj_t *obj);
428
/*%<
429 430 431
 * Returns the first list element in a configuration object of a list type.
 *
 * Requires:
432
 * \li     'obj' points to a valid configuration object of a list type or NULL.
433 434
 *
 * Returns:
435
 *   \li   A pointer to a cfg_listelt_t representing the first list element,
436
 * 	or NULL if the list is empty or nonexistent.
437 438
 */

439 440
const cfg_listelt_t *
cfg_list_next(const cfg_listelt_t *elt);
441
/*%<
442 443 444
 * Returns the next element of a list of configuration objects.
 *
 * Requires:
445
 * \li     'elt' points to cfg_listelt_t obtained from cfg_list_first() or
446 447 448
 *	a previous call to cfg_list_next().
 *
 * Returns:
449
 * \li     A pointer to a cfg_listelt_t representing the next element,
450 451 452
 * 	or NULL if there are no more elements.
 */

Mark Andrews's avatar
Mark Andrews committed
453
unsigned int
454
cfg_list_length(const cfg_obj_t *obj, isc_boolean_t recurse);
Mark Andrews's avatar
Mark Andrews committed
455 456
/*%<
 * Returns the length of a list of configure objects.  If obj is
457 458
 * not a list, returns 0.  If recurse is true, add in the length of
 * all contained lists.
Mark Andrews's avatar
Mark Andrews committed
459 460
 */

461
cfg_obj_t *
462
cfg_listelt_value(const cfg_listelt_t *elt);
463
/*%<
464 465 466
 * Returns the configuration object associated with cfg_listelt_t.
 *
 * Requires:
467
 * \li     'elt' points to cfg_listelt_t obtained from cfg_list_first() or
468 469 470
 *	cfg_list_next().
 *
 * Returns:
471
 * \li     A non-NULL pointer to a configuration object.
472 473
 */

474
void
475
cfg_print(const cfg_obj_t *obj,
476 477
	  void (*f)(void *closure, const char *text, int textlen),
	  void *closure);
478 479 480 481 482 483
void
cfg_printx(const cfg_obj_t *obj, unsigned int flags,
	   void (*f)(void *closure, const char *text, int textlen),
	   void *closure);

#define CFG_PRINTER_XKEY        0x1     /* '?' out shared keys. */
484
#define CFG_PRINTER_ONELINE     0x2     /* print config as a single line */
485

486
/*%<
487 488 489
 * 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.
490 491 492
 *
 * If CFG_PRINTER_XKEY the contents of shared keys will be obscured
 * by replacing them with question marks ('?')
493 494
 */

495
void
496
cfg_print_grammar(const cfg_type_t *type,
497 498
	  void (*f)(void *closure, const char *text, int textlen),
	  void *closure);
499
/*%<
500 501 502
 * Print a summary of the grammar of the configuration type 'type'.
 */

503
isc_boolean_t
504
cfg_obj_istype(const cfg_obj_t *obj, const cfg_type_t *type);
505
/*%<
Automatic Updater's avatar
Automatic Updater committed
506
 * Return true iff 'obj' is of type 'type'.
507 508
 */

509 510 511 512 513 514 515 516
void
cfg_obj_attach(cfg_obj_t *src, cfg_obj_t **dest);
/*%<
 * Reference a configuration object.
 */

void
cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj);
517
/*%<
518 519
 * Delete a reference to a configuration object; destroy the object if
 * there are no more references.
520 521 522 523
 *
 * Require:
 * \li     '*obj' is a valid cfg_obj_t.
 * \li     'pctx' is a valid cfg_parser_t.
524 525
 */

Andreas Gustafsson's avatar
Andreas Gustafsson committed
526
void
527
cfg_obj_log(const cfg_obj_t *obj, isc_log_t *lctx, int level,
528
	    const char *fmt, ...)
529
	ISC_FORMAT_PRINTF(4, 5);
530
/*%<
Andreas Gustafsson's avatar
Andreas Gustafsson committed
531 532 533 534 535
 * 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.
 */

536
const char *
537
cfg_obj_file(const cfg_obj_t *obj);
538
/*%<
539 540 541 542
 * Return the file that defined this object.
 */

unsigned int
543
cfg_obj_line(const cfg_obj_t *obj);
544
/*%<
545 546 547
 * Return the line in file where this object was defined.
 */

548 549
const char *
cfg_map_firstclause(const cfg_type_t *map, const void **clauses,
550
		    unsigned int *idx);
551 552
const char *
cfg_map_nextclause(const cfg_type_t *map, const void **clauses,
553
		   unsigned int *idx);
554

555 556
ISC_LANG_ENDDECLS

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