Merge from vendor branch LIBARCHIVE:
[dragonfly.git] / contrib / bind-9.2.4rc7 / lib / isccfg / include / isccfg / cfg.h
1 /*
2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
3  * Copyright (C) 2000, 2001  Internet Software Consortium.
4  *
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.
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.30.2.1 2004/03/09 06:12:31 marka Exp $ */
19
20 #ifndef ISCCFG_CFG_H
21 #define ISCCFG_CFG_H 1
22
23 /*****
24  ***** Module Info
25  *****/
26
27 /*
28  * This is the new, table-driven, YACC-free configuration file parser.
29  */
30
31
32 /***
33  *** Imports
34  ***/
35
36 #include <isc/formatcheck.h>
37 #include <isc/lang.h>
38 #include <isc/types.h>
39 #include <isc/list.h>
40
41
42 /***
43  *** Types
44  ***/
45
46 typedef struct cfg_parser cfg_parser_t;
47 /*
48  * A configuration parser.
49  */
50
51 /*
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.
55  */
56 typedef struct cfg_type cfg_type_t;
57
58 /*
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
63  * messages.
64  */
65 typedef struct cfg_obj cfg_obj_t;
66
67 /*
68  * A configuration object list element.
69  */
70 typedef struct cfg_listelt cfg_listelt_t;
71
72 /*
73  * A callback function to be called when parsing an option 
74  * that needs to be interpreted at parsing time, like
75  * "directory".
76  */
77 typedef isc_result_t
78 (*cfg_parsecallback_t)(const char *clausename, cfg_obj_t *obj, void *arg);
79
80 /***
81  *** Functions
82  ***/
83
84 ISC_LANG_BEGINDECLS
85
86 isc_result_t
87 cfg_parser_create(isc_mem_t *mctx, isc_log_t *lctx, cfg_parser_t **ret);
88 /*
89  * Create a configuration file parser.  Any warning and error
90  * messages will be logged to 'lctx'.
91  *
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.
95  */
96
97 void
98 cfg_parser_setcallback(cfg_parser_t *pctx,
99                        cfg_parsecallback_t callback,
100                        void *arg);
101 /*
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.
106  *
107  * To restore the default of not invoking callbacks, pass
108  * callback==NULL and arg==NULL.
109  */
110
111 isc_result_t
112 cfg_parse_file(cfg_parser_t *pctx, const char *filename,
113                const cfg_type_t *type, cfg_obj_t **ret);
114 isc_result_t
115 cfg_parse_buffer(cfg_parser_t *pctx, isc_buffer_t *buffer,
116                  const cfg_type_t *type, cfg_obj_t **ret);
117 /*
118  * Read a configuration containing data of type 'type'
119  * and make '*ret' point to its parse tree.
120  *
121  * The configuration is read from the file 'filename'
122  * (isc_parse_file()) or the buffer 'buffer'
123  * (isc_parse_buffer()).
124  *
125  * Returns an error if the file does not parse correctly.
126  * 
127  * Requires:
128  *      "filename" is valid.
129  *      "mem" is valid.
130  *      "type" is valid.
131  *      "cfg" is non-NULL and "*cfg" is NULL.
132  *
133  * Returns:
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
138  */
139
140 void
141 cfg_parser_destroy(cfg_parser_t **pctxp);
142 /*
143  * Destroy a configuration parser.
144  */
145
146 isc_boolean_t
147 cfg_obj_isvoid(cfg_obj_t *obj);
148 /*
149  * Return true iff 'obj' is of void type (e.g., an optional 
150  * value not specified).
151  */
152
153 isc_boolean_t
154 cfg_obj_ismap(cfg_obj_t *obj);
155 /*
156  * Return true iff 'obj' is of a map type.
157  */
158
159 isc_result_t
160 cfg_map_get(cfg_obj_t *mapobj, const char* name, cfg_obj_t **obj);
161 /*
162  * Extract an element from a configuration object, which
163  * must be of a map type.
164  *
165  * Requires:
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.
169  *
170  * Returns:
171  *      ISC_R_SUCCESS                  - success
172  *      ISC_R_NOTFOUND                 - name not found in map
173  */
174
175 cfg_obj_t *
176 cfg_map_getname(cfg_obj_t *mapobj);
177 /*
178  * Get the name of a named map object, like a server "key" clause.
179  *
180  * Requires:
181  *      'mapobj' points to a valid configuration object of a map type.
182  *
183  * Returns:
184  *      A pointer to a configuration object naming the map object,
185  *      or NULL if the map object does not have a name.
186  */
187
188 isc_boolean_t
189 cfg_obj_istuple(cfg_obj_t *obj);
190 /*
191  * Return true iff 'obj' is of a map type.
192  */
193
194 cfg_obj_t *
195 cfg_tuple_get(cfg_obj_t *tupleobj, const char *name);
196 /*
197  * Extract an element from a configuration object, which
198  * must be of a tuple type.
199  *
200  * Requires:
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.
204  */
205
206 isc_boolean_t
207 cfg_obj_isuint32(cfg_obj_t *obj);
208 /*
209  * Return true iff 'obj' is of integer type.
210  */
211
212 isc_uint32_t
213 cfg_obj_asuint32(cfg_obj_t *obj);
214 /*
215  * Returns the value of a configuration object of 32-bit integer type.
216  *
217  * Requires:
218  *      'obj' points to a valid configuration object of 32-bit integer type.
219  *
220  * Returns:
221  *      A 32-bit unsigned integer.
222  */
223
224 isc_boolean_t
225 cfg_obj_isuint64(cfg_obj_t *obj);
226 /*
227  * Return true iff 'obj' is of integer type.
228  */
229
230 isc_uint64_t
231 cfg_obj_asuint64(cfg_obj_t *obj);
232 /*
233  * Returns the value of a configuration object of 64-bit integer type.
234  *
235  * Requires:
236  *      'obj' points to a valid configuration object of 64-bit integer type.
237  *
238  * Returns:
239  *      A 64-bit unsigned integer.
240  */
241
242 isc_boolean_t
243 cfg_obj_isstring(cfg_obj_t *obj);
244 /*
245  * Return true iff 'obj' is of string type.
246  */
247
248 char *
249 cfg_obj_asstring(cfg_obj_t *obj);
250 /*
251  * Returns the value of a configuration object of a string type
252  * as a null-terminated string.
253  *
254  * Requires:
255  *      'obj' points to a valid configuration object of a string type.
256  *
257  * Returns:
258  *      A pointer to a null terminated string.
259  */
260
261 isc_boolean_t
262 cfg_obj_isboolean(cfg_obj_t *obj);
263 /*
264  * Return true iff 'obj' is of a boolean type.
265  */
266
267 isc_boolean_t
268 cfg_obj_asboolean(cfg_obj_t *obj);
269 /*
270  * Returns the value of a configuration object of a boolean type.
271  *
272  * Requires:
273  *      'obj' points to a valid configuration object of a boolean type.
274  *
275  * Returns:
276  *      A boolean value.
277  */
278
279 isc_boolean_t
280 cfg_obj_issockaddr(cfg_obj_t *obj);
281 /*
282  * Return true iff 'obj' is a socket address.
283  */
284
285 isc_sockaddr_t *
286 cfg_obj_assockaddr(cfg_obj_t *obj);
287 /*
288  * Returns the value of a configuration object representing a socket address.
289  *
290  * Requires:
291  *      'obj' points to a valid configuration object of a socket address type.
292  *
293  * Returns:
294  *      A pointer to a sockaddr.  The sockaddr must be copied by the caller
295  *      if necessary.
296  */
297
298 isc_boolean_t
299 cfg_obj_isnetprefix(cfg_obj_t *obj);
300 /*
301  * Return true iff 'obj' is a network prefix.
302  */
303
304 void
305 cfg_obj_asnetprefix(cfg_obj_t *obj, isc_netaddr_t *netaddr,
306                     unsigned int *prefixlen);
307 /*
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'.
311  *
312  * Requires:
313  *      'obj' points to a valid configuration object of network prefix type.
314  *      'netaddr' and 'prefixlen' are non-NULL.
315  */
316
317 isc_boolean_t
318 cfg_obj_islist(cfg_obj_t *obj);
319 /*
320  * Return true iff 'obj' is of list type.
321  */
322
323 cfg_listelt_t *
324 cfg_list_first(cfg_obj_t *obj);
325 /*
326  * Returns the first list element in a configuration object of a list type.
327  *
328  * Requires:
329  *      'obj' points to a valid configuration object of a list type or NULL.
330  *
331  * Returns:
332  *      A pointer to a cfg_listelt_t representing the first list element,
333  *      or NULL if the list is empty or nonexistent.
334  */
335
336 cfg_listelt_t *
337 cfg_list_next(cfg_listelt_t *elt);
338 /*
339  * Returns the next element of a list of configuration objects.
340  *
341  * Requires:
342  *      'elt' points to cfg_listelt_t obtained from cfg_list_first() or
343  *      a previous call to cfg_list_next().
344  *
345  * Returns:
346  *      A pointer to a cfg_listelt_t representing the next element,
347  *      or NULL if there are no more elements.
348  */
349
350 cfg_obj_t *
351 cfg_listelt_value(cfg_listelt_t *elt);
352 /*
353  * Returns the configuration object associated with cfg_listelt_t.
354  *
355  * Requires:
356  *      'elt' points to cfg_listelt_t obtained from cfg_list_first() or
357  *      cfg_list_next().
358  *
359  * Returns:
360  *      A non-NULL pointer to a configuration object.
361  */
362
363 void
364 cfg_print(cfg_obj_t *obj,
365           void (*f)(void *closure, const char *text, int textlen),
366           void *closure);
367 /*
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.
371  */
372
373 void
374 cfg_print_grammar(const cfg_type_t *type,
375           void (*f)(void *closure, const char *text, int textlen),
376           void *closure);
377 /*
378  * Print a summary of the grammar of the configuration type 'type'.
379  */
380
381 isc_boolean_t
382 cfg_obj_istype(cfg_obj_t *obj, const cfg_type_t *type);
383 /*
384  * Return true iff 'obj' is of type 'type'. 
385  */
386
387 void cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj);
388 /*
389  * Destroy a configuration object.
390  */
391
392 void
393 cfg_obj_log(cfg_obj_t *obj, isc_log_t *lctx, int level, const char *fmt, ...)
394         ISC_FORMAT_PRINTF(4, 5);
395 /*
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.
399  */
400
401 /*
402  * Configuration object types.
403  */
404 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_namedconf;
405 /* A complete named.conf file. */
406
407 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_rndcconf;
408 /* A complete rndc.conf file. */
409
410 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_rndckey;
411 /* A complete rndc.key file. */
412
413 LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_keyref;
414 /* A key reference, used as an ACL element */
415
416 ISC_LANG_ENDDECLS
417
418 #endif /* ISCCFG_CFG_H */