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