2 * Copyright (C) 2004, 2006 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 2000-2002 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.12.6 2006/03/02 00:37:20 marka Exp $ */
21 #define ISCCFG_CFG_H 1
28 * This is the new, table-driven, YACC-free configuration file parser.
35 #include <isc/formatcheck.h>
37 #include <isc/types.h>
45 typedef struct cfg_parser cfg_parser_t
;
47 * A configuration parser.
51 * A configuration type definition object. There is a single
52 * static cfg_type_t object for each data type supported by
53 * the configuration parser.
55 typedef struct cfg_type cfg_type_t
;
58 * A configuration object. This is the basic building block of the
59 * configuration parse tree. It contains a value (which may be
60 * of one of several types) and information identifying the file
61 * and line number the value came from, for printing error
64 typedef struct cfg_obj cfg_obj_t
;
67 * A configuration object list element.
69 typedef struct cfg_listelt cfg_listelt_t
;
72 * A callback function to be called when parsing an option
73 * that needs to be interpreted at parsing time, like
77 (*cfg_parsecallback_t
)(const char *clausename
, const cfg_obj_t
*obj
, void *arg
);
86 cfg_parser_create(isc_mem_t
*mctx
, isc_log_t
*lctx
, cfg_parser_t
**ret
);
88 * Create a configuration file parser. Any warning and error
89 * messages will be logged to 'lctx'.
91 * The parser object returned can be used for a single call
92 * to cfg_parse_file() or cfg_parse_buffer(). It must not
93 * be reused for parsing multiple files or buffers.
97 cfg_parser_setcallback(cfg_parser_t
*pctx
,
98 cfg_parsecallback_t callback
,
101 * Make the parser call 'callback' whenever it encounters
102 * a configuration clause with the callback attribute,
103 * passing it the clause name, the clause value,
104 * and 'arg' as arguments.
106 * To restore the default of not invoking callbacks, pass
107 * callback==NULL and arg==NULL.
111 cfg_parse_file(cfg_parser_t
*pctx
, const char *filename
,
112 const cfg_type_t
*type
, cfg_obj_t
**ret
);
114 cfg_parse_buffer(cfg_parser_t
*pctx
, isc_buffer_t
*buffer
,
115 const cfg_type_t
*type
, cfg_obj_t
**ret
);
117 * Read a configuration containing data of type 'type'
118 * and make '*ret' point to its parse tree.
120 * The configuration is read from the file 'filename'
121 * (isc_parse_file()) or the buffer 'buffer'
122 * (isc_parse_buffer()).
124 * Returns an error if the file does not parse correctly.
127 * "filename" is valid.
130 * "cfg" is non-NULL and "*cfg" is NULL.
133 * ISC_R_SUCCESS - success
134 * ISC_R_NOMEMORY - no memory available
135 * ISC_R_INVALIDFILE - file doesn't exist or is unreadable
136 * others - file contains errors
140 cfg_parser_destroy(cfg_parser_t
**pctxp
);
142 * Destroy a configuration parser.
146 cfg_obj_isvoid(const cfg_obj_t
*obj
);
148 * Return true iff 'obj' is of void type (e.g., an optional
149 * value not specified).
153 cfg_obj_ismap(const cfg_obj_t
*obj
);
155 * Return true iff 'obj' is of a map type.
159 cfg_map_get(const cfg_obj_t
*mapobj
, const char* name
, const cfg_obj_t
**obj
);
161 * Extract an element from a configuration object, which
162 * must be of a map type.
165 * 'mapobj' points to a valid configuration object of a map type.
166 * 'name' points to a null-terminated string.
167 * 'obj' is non-NULL and '*obj' is NULL.
170 * ISC_R_SUCCESS - success
171 * ISC_R_NOTFOUND - name not found in map
175 cfg_map_getname(const cfg_obj_t
*mapobj
);
177 * Get the name of a named map object, like a server "key" clause.
180 * 'mapobj' points to a valid configuration object of a map type.
183 * A pointer to a configuration object naming the map object,
184 * or NULL if the map object does not have a name.
188 cfg_obj_istuple(const cfg_obj_t
*obj
);
190 * Return true iff 'obj' is of a map type.
194 cfg_tuple_get(const cfg_obj_t
*tupleobj
, const char *name
);
196 * Extract an element from a configuration object, which
197 * must be of a tuple type.
200 * 'tupleobj' points to a valid configuration object of a tuple type.
201 * 'name' points to a null-terminated string naming one of the
202 * fields of said tuple type.
206 cfg_obj_isuint32(const cfg_obj_t
*obj
);
208 * Return true iff 'obj' is of integer type.
212 cfg_obj_asuint32(const cfg_obj_t
*obj
);
214 * Returns the value of a configuration object of 32-bit integer type.
217 * 'obj' points to a valid configuration object of 32-bit integer type.
220 * A 32-bit unsigned integer.
224 cfg_obj_isuint64(const cfg_obj_t
*obj
);
226 * Return true iff 'obj' is of integer type.
230 cfg_obj_asuint64(const cfg_obj_t
*obj
);
232 * Returns the value of a configuration object of 64-bit integer type.
235 * 'obj' points to a valid configuration object of 64-bit integer type.
238 * A 64-bit unsigned integer.
242 cfg_obj_isstring(const cfg_obj_t
*obj
);
244 * Return true iff 'obj' is of string type.
248 cfg_obj_asstring(const cfg_obj_t
*obj
);
250 * Returns the value of a configuration object of a string type
251 * as a null-terminated string.
254 * 'obj' points to a valid configuration object of a string type.
257 * A pointer to a null terminated string.
261 cfg_obj_isboolean(const cfg_obj_t
*obj
);
263 * Return true iff 'obj' is of a boolean type.
267 cfg_obj_asboolean(const cfg_obj_t
*obj
);
269 * Returns the value of a configuration object of a boolean type.
272 * 'obj' points to a valid configuration object of a boolean type.
279 cfg_obj_issockaddr(const cfg_obj_t
*obj
);
281 * Return true iff 'obj' is a socket address.
284 const isc_sockaddr_t
*
285 cfg_obj_assockaddr(const cfg_obj_t
*obj
);
287 * Returns the value of a configuration object representing a socket address.
290 * 'obj' points to a valid configuration object of a socket address type.
293 * A pointer to a sockaddr. The sockaddr must be copied by the caller
298 cfg_obj_isnetprefix(const cfg_obj_t
*obj
);
300 * Return true iff 'obj' is a network prefix.
304 cfg_obj_asnetprefix(const cfg_obj_t
*obj
, isc_netaddr_t
*netaddr
,
305 unsigned int *prefixlen
);
307 * Gets the value of a configuration object representing a network
308 * prefix. The network address is returned through 'netaddr' and the
309 * prefix length in bits through 'prefixlen'.
312 * 'obj' points to a valid configuration object of network prefix type.
313 * 'netaddr' and 'prefixlen' are non-NULL.
317 cfg_obj_islist(const cfg_obj_t
*obj
);
319 * Return true iff 'obj' is of list type.
322 const cfg_listelt_t
*
323 cfg_list_first(const cfg_obj_t
*obj
);
325 * Returns the first list element in a configuration object of a list type.
328 * 'obj' points to a valid configuration object of a list type or NULL.
331 * A pointer to a cfg_listelt_t representing the first list element,
332 * or NULL if the list is empty or nonexistent.
335 const cfg_listelt_t
*
336 cfg_list_next(const cfg_listelt_t
*elt
);
338 * Returns the next element of a list of configuration objects.
341 * 'elt' points to cfg_listelt_t obtained from cfg_list_first() or
342 * a previous call to cfg_list_next().
345 * A pointer to a cfg_listelt_t representing the next element,
346 * or NULL if there are no more elements.
350 cfg_listelt_value(const cfg_listelt_t
*elt
);
352 * Returns the configuration object associated with cfg_listelt_t.
355 * 'elt' points to cfg_listelt_t obtained from cfg_list_first() or
359 * A non-NULL pointer to a configuration object.
363 cfg_print(const cfg_obj_t
*obj
,
364 void (*f
)(void *closure
, const char *text
, int textlen
),
367 * Print the configuration object 'obj' by repeatedly calling the
368 * function 'f', passing 'closure' and a region of text starting
369 * at 'text' and comprising 'textlen' characters.
373 cfg_print_grammar(const cfg_type_t
*type
,
374 void (*f
)(void *closure
, const char *text
, int textlen
),
377 * Print a summary of the grammar of the configuration type 'type'.
381 cfg_obj_istype(const cfg_obj_t
*obj
, const cfg_type_t
*type
);
383 * Return true iff 'obj' is of type 'type'.
386 void cfg_obj_destroy(cfg_parser_t
*pctx
, cfg_obj_t
**obj
);
388 * Destroy a configuration object.
392 cfg_obj_log(const cfg_obj_t
*obj
, isc_log_t
*lctx
, int level
,
393 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 cfg_obj_file(const cfg_obj_t
*obj
);
404 * Return the file that defined this object.
408 cfg_obj_line(const cfg_obj_t
*obj
);
410 * Return the line in file where this object was defined.
416 #endif /* ISCCFG_CFG_H */