2 * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 2000, 2001 Internet Software Consortium.
5 * Permission to use, copy, modify, and 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.
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.
18 /* $Id: cfg.h,v 1.30.2.1 2004/03/09 06:12:31 marka Exp $ */
21 #define ISCCFG_CFG_H 1
28 * This is the new, table-driven, YACC-free configuration file parser.
36 #include <isc/formatcheck.h>
38 #include <isc/types.h>
46 typedef struct cfg_parser cfg_parser_t;
48 * A configuration parser.
52 * A configuration type definition object. There is a single
53 * static cfg_type_t object for each data type supported by
54 * the configuration parser.
56 typedef struct cfg_type cfg_type_t;
59 * A configuration object. This is the basic building block of the
60 * configuration parse tree. It contains a value (which may be
61 * of one of several types) and information identifying the file
62 * and line number the value came from, for printing error
65 typedef struct cfg_obj cfg_obj_t;
68 * A configuration object list element.
70 typedef struct cfg_listelt cfg_listelt_t;
73 * A callback function to be called when parsing an option
74 * that needs to be interpreted at parsing time, like
78 (*cfg_parsecallback_t)(const char *clausename, cfg_obj_t *obj, void *arg);
87 cfg_parser_create(isc_mem_t *mctx, isc_log_t *lctx, cfg_parser_t **ret);
89 * Create a configuration file parser. Any warning and error
90 * messages will be logged to 'lctx'.
92 * The parser object returned can be used for a single call
93 * to cfg_parse_file() or cfg_parse_buffer(). It must not
94 * be reused for parsing multiple files or buffers.
98 cfg_parser_setcallback(cfg_parser_t *pctx,
99 cfg_parsecallback_t callback,
102 * Make the parser call 'callback' whenever it encounters
103 * a configuration clause with the callback attribute,
104 * passing it the clause name, the clause value,
105 * and 'arg' as arguments.
107 * To restore the default of not invoking callbacks, pass
108 * callback==NULL and arg==NULL.
112 cfg_parse_file(cfg_parser_t *pctx, const char *filename,
113 const cfg_type_t *type, cfg_obj_t **ret);
115 cfg_parse_buffer(cfg_parser_t *pctx, isc_buffer_t *buffer,
116 const cfg_type_t *type, cfg_obj_t **ret);
118 * Read a configuration containing data of type 'type'
119 * and make '*ret' point to its parse tree.
121 * The configuration is read from the file 'filename'
122 * (isc_parse_file()) or the buffer 'buffer'
123 * (isc_parse_buffer()).
125 * Returns an error if the file does not parse correctly.
128 * "filename" is valid.
131 * "cfg" is non-NULL and "*cfg" is NULL.
134 * ISC_R_SUCCESS - success
135 * ISC_R_NOMEMORY - no memory available
136 * ISC_R_INVALIDFILE - file doesn't exist or is unreadable
137 * others - file contains errors
141 cfg_parser_destroy(cfg_parser_t **pctxp);
143 * Destroy a configuration parser.
147 cfg_obj_isvoid(cfg_obj_t *obj);
149 * Return true iff 'obj' is of void type (e.g., an optional
150 * value not specified).
154 cfg_obj_ismap(cfg_obj_t *obj);
156 * Return true iff 'obj' is of a map type.
160 cfg_map_get(cfg_obj_t *mapobj, const char* name, cfg_obj_t **obj);
162 * Extract an element from a configuration object, which
163 * must be of a map type.
166 * 'mapobj' points to a valid configuration object of a map type.
167 * 'name' points to a null-terminated string.
168 * 'obj' is non-NULL and '*obj' is NULL.
171 * ISC_R_SUCCESS - success
172 * ISC_R_NOTFOUND - name not found in map
176 cfg_map_getname(cfg_obj_t *mapobj);
178 * Get the name of a named map object, like a server "key" clause.
181 * 'mapobj' points to a valid configuration object of a map type.
184 * A pointer to a configuration object naming the map object,
185 * or NULL if the map object does not have a name.
189 cfg_obj_istuple(cfg_obj_t *obj);
191 * Return true iff 'obj' is of a map type.
195 cfg_tuple_get(cfg_obj_t *tupleobj, const char *name);
197 * Extract an element from a configuration object, which
198 * must be of a tuple type.
201 * 'tupleobj' points to a valid configuration object of a tuple type.
202 * 'name' points to a null-terminated string naming one of the
203 * fields of said tuple type.
207 cfg_obj_isuint32(cfg_obj_t *obj);
209 * Return true iff 'obj' is of integer type.
213 cfg_obj_asuint32(cfg_obj_t *obj);
215 * Returns the value of a configuration object of 32-bit integer type.
218 * 'obj' points to a valid configuration object of 32-bit integer type.
221 * A 32-bit unsigned integer.
225 cfg_obj_isuint64(cfg_obj_t *obj);
227 * Return true iff 'obj' is of integer type.
231 cfg_obj_asuint64(cfg_obj_t *obj);
233 * Returns the value of a configuration object of 64-bit integer type.
236 * 'obj' points to a valid configuration object of 64-bit integer type.
239 * A 64-bit unsigned integer.
243 cfg_obj_isstring(cfg_obj_t *obj);
245 * Return true iff 'obj' is of string type.
249 cfg_obj_asstring(cfg_obj_t *obj);
251 * Returns the value of a configuration object of a string type
252 * as a null-terminated string.
255 * 'obj' points to a valid configuration object of a string type.
258 * A pointer to a null terminated string.
262 cfg_obj_isboolean(cfg_obj_t *obj);
264 * Return true iff 'obj' is of a boolean type.
268 cfg_obj_asboolean(cfg_obj_t *obj);
270 * Returns the value of a configuration object of a boolean type.
273 * 'obj' points to a valid configuration object of a boolean type.
280 cfg_obj_issockaddr(cfg_obj_t *obj);
282 * Return true iff 'obj' is a socket address.
286 cfg_obj_assockaddr(cfg_obj_t *obj);
288 * Returns the value of a configuration object representing a socket address.
291 * 'obj' points to a valid configuration object of a socket address type.
294 * A pointer to a sockaddr. The sockaddr must be copied by the caller
299 cfg_obj_isnetprefix(cfg_obj_t *obj);
301 * Return true iff 'obj' is a network prefix.
305 cfg_obj_asnetprefix(cfg_obj_t *obj, isc_netaddr_t *netaddr,
306 unsigned int *prefixlen);
308 * Gets the value of a configuration object representing a network
309 * prefix. The network address is returned through 'netaddr' and the
310 * prefix length in bits through 'prefixlen'.
313 * 'obj' points to a valid configuration object of network prefix type.
314 * 'netaddr' and 'prefixlen' are non-NULL.
318 cfg_obj_islist(cfg_obj_t *obj);
320 * Return true iff 'obj' is of list type.
324 cfg_list_first(cfg_obj_t *obj);
326 * Returns the first list element in a configuration object of a list type.
329 * 'obj' points to a valid configuration object of a list type or NULL.
332 * A pointer to a cfg_listelt_t representing the first list element,
333 * or NULL if the list is empty or nonexistent.
337 cfg_list_next(cfg_listelt_t *elt);
339 * Returns the next element of a list of configuration objects.
342 * 'elt' points to cfg_listelt_t obtained from cfg_list_first() or
343 * a previous call to cfg_list_next().
346 * A pointer to a cfg_listelt_t representing the next element,
347 * or NULL if there are no more elements.
351 cfg_listelt_value(cfg_listelt_t *elt);
353 * Returns the configuration object associated with cfg_listelt_t.
356 * 'elt' points to cfg_listelt_t obtained from cfg_list_first() or
360 * A non-NULL pointer to a configuration object.
364 cfg_print(cfg_obj_t *obj,
365 void (*f)(void *closure, const char *text, int textlen),
368 * Print the configuration object 'obj' by repeatedly calling the
369 * function 'f', passing 'closure' and a region of text starting
370 * at 'text' and comprising 'textlen' characters.
374 cfg_print_grammar(const cfg_type_t *type,
375 void (*f)(void *closure, const char *text, int textlen),
378 * Print a summary of the grammar of the configuration type 'type'.
382 cfg_obj_istype(cfg_obj_t *obj, const cfg_type_t *type);
384 * Return true iff 'obj' is of type 'type'.
387 void cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj);
389 * Destroy a configuration object.
393 cfg_obj_log(cfg_obj_t *obj, isc_log_t *lctx, int level, const char *fmt, ...)
394 ISC_FORMAT_PRINTF(4, 5);
396 * Log a message concerning configuration object 'obj' to the logging
397 * channel of 'pctx', at log level 'level'. The message will be prefixed
398 * with the file name(s) and line number where 'obj' was defined.
402 * Configuration object types.
404 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_namedconf;
405 /* A complete named.conf file. */
407 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_rndcconf;
408 /* A complete rndc.conf file. */
410 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_rndckey;
411 /* A complete rndc.key file. */
413 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_keyref;
414 /* A key reference, used as an ACL element */
418 #endif /* ISCCFG_CFG_H */