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