1 /*
2  * Copyright (C) 2004-2007, 2010, 2013-2015  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  */
50 typedef 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  */
57 typedef 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  */
66 typedef struct cfg_obj cfg_obj_t;
67 
68 /*%
69  * A configuration object list element.
70  */
71 typedef 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  */
78 typedef isc_result_t
79 (*cfg_parsecallback_t)(const char *clausename, const cfg_obj_t *obj, void *arg);
80 
81 /***
82  *** Functions
83  ***/
84 
85 ISC_LANG_BEGINDECLS
86 
87 void
88 cfg_parser_attach(cfg_parser_t *src, cfg_parser_t **dest);
89 /*%<
90  * Reference a parser object.
91  */
92 
93 isc_result_t
94 cfg_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 
104 void
105 cfg_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 
118 isc_result_t
119 cfg_parse_file(cfg_parser_t *pctx, const char *filename,
120 	       const cfg_type_t *type, cfg_obj_t **ret);
121 isc_result_t
122 cfg_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 
147 void
148 cfg_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 
154 isc_boolean_t
155 cfg_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 
161 isc_boolean_t
162 cfg_obj_ismap(const cfg_obj_t *obj);
163 /*%<
164  * Return true iff 'obj' is of a map type.
165  */
166 
167 isc_result_t
168 cfg_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 
183 const cfg_obj_t *
184 cfg_map_getname(const cfg_obj_t *mapobj);
185 /*%<
186  * Get the name of a named map object, like a server "key" clause.
187  *
188  * Requires:
189  *    \li  'mapobj' points to a valid configuration object of a map type.
190  *
191  * Returns:
192  * \li     A pointer to a configuration object naming the map object,
193  *	or NULL if the map object does not have a name.
194  */
195 
196 isc_boolean_t
197 cfg_obj_istuple(const cfg_obj_t *obj);
198 /*%<
199  * Return true iff 'obj' is of a map type.
200  */
201 
202 const cfg_obj_t *
203 cfg_tuple_get(const cfg_obj_t *tupleobj, const char *name);
204 /*%<
205  * Extract an element from a configuration object, which
206  * must be of a tuple type.
207  *
208  * Requires:
209  * \li     'tupleobj' points to a valid configuration object of a tuple type.
210  * \li     'name' points to a null-terminated string naming one of the
211  *\li	fields of said tuple type.
212  */
213 
214 isc_boolean_t
215 cfg_obj_isuint32(const cfg_obj_t *obj);
216 /*%<
217  * Return true iff 'obj' is of integer type.
218  */
219 
220 isc_uint32_t
221 cfg_obj_asuint32(const cfg_obj_t *obj);
222 /*%<
223  * Returns the value of a configuration object of 32-bit integer type.
224  *
225  * Requires:
226  * \li     'obj' points to a valid configuration object of 32-bit integer type.
227  *
228  * Returns:
229  * \li     A 32-bit unsigned integer.
230  */
231 
232 isc_boolean_t
233 cfg_obj_isuint64(const cfg_obj_t *obj);
234 /*%<
235  * Return true iff 'obj' is of integer type.
236  */
237 
238 isc_uint64_t
239 cfg_obj_asuint64(const cfg_obj_t *obj);
240 /*%<
241  * Returns the value of a configuration object of 64-bit integer type.
242  *
243  * Requires:
244  * \li     'obj' points to a valid configuration object of 64-bit integer type.
245  *
246  * Returns:
247  * \li     A 64-bit unsigned integer.
248  */
249 
250 isc_uint32_t
251 cfg_obj_asfixedpoint(const cfg_obj_t *obj);
252 /*%<
253  * Returns the value of a configuration object of fixed point number.
254  *
255  * Requires:
256  * \li     'obj' points to a valid configuration object of fixed point type.
257  *
258  * Returns:
259  * \li     A 32-bit unsigned integer.
260  */
261 
262 isc_boolean_t
263 cfg_obj_isstring(const cfg_obj_t *obj);
264 /*%<
265  * Return true iff 'obj' is of string type.
266  */
267 
268 const char *
269 cfg_obj_asstring(const cfg_obj_t *obj);
270 /*%<
271  * Returns the value of a configuration object of a string type
272  * as a null-terminated string.
273  *
274  * Requires:
275  * \li     'obj' points to a valid configuration object of a string type.
276  *
277  * Returns:
278  * \li     A pointer to a null terminated string.
279  */
280 
281 isc_boolean_t
282 cfg_obj_isboolean(const cfg_obj_t *obj);
283 /*%<
284  * Return true iff 'obj' is of a boolean type.
285  */
286 
287 isc_boolean_t
288 cfg_obj_asboolean(const cfg_obj_t *obj);
289 /*%<
290  * Returns the value of a configuration object of a boolean type.
291  *
292  * Requires:
293  * \li     'obj' points to a valid configuration object of a boolean type.
294  *
295  * Returns:
296  * \li     A boolean value.
297  */
298 
299 isc_boolean_t
300 cfg_obj_issockaddr(const cfg_obj_t *obj);
301 /*%<
302  * Return true iff 'obj' is a socket address.
303  */
304 
305 const isc_sockaddr_t *
306 cfg_obj_assockaddr(const cfg_obj_t *obj);
307 /*%<
308  * Returns the value of a configuration object representing a socket address.
309  *
310  * Requires:
311  * \li     'obj' points to a valid configuration object of a socket address type.
312  *
313  * Returns:
314  * \li     A pointer to a sockaddr.  The sockaddr must be copied by the caller
315  *      if necessary.
316  */
317 
318 isc_boolean_t
319 cfg_obj_isnetprefix(const cfg_obj_t *obj);
320 /*%<
321  * Return true iff 'obj' is a network prefix.
322  */
323 
324 void
325 cfg_obj_asnetprefix(const cfg_obj_t *obj, isc_netaddr_t *netaddr,
326 		    unsigned int *prefixlen);
327 /*%<
328  * Gets the value of a configuration object representing a network
329  * prefix.  The network address is returned through 'netaddr' and the
330  * prefix length in bits through 'prefixlen'.
331  *
332  * Requires:
333  * \li     'obj' points to a valid configuration object of network prefix type.
334  *\li	'netaddr' and 'prefixlen' are non-NULL.
335  */
336 
337 isc_boolean_t
338 cfg_obj_islist(const cfg_obj_t *obj);
339 /*%<
340  * Return true iff 'obj' is of list type.
341  */
342 
343 const cfg_listelt_t *
344 cfg_list_first(const cfg_obj_t *obj);
345 /*%<
346  * Returns the first list element in a configuration object of a list type.
347  *
348  * Requires:
349  * \li     'obj' points to a valid configuration object of a list type or NULL.
350  *
351  * Returns:
352  *   \li   A pointer to a cfg_listelt_t representing the first list element,
353  * 	or NULL if the list is empty or nonexistent.
354  */
355 
356 const cfg_listelt_t *
357 cfg_list_next(const cfg_listelt_t *elt);
358 /*%<
359  * Returns the next element of a list of configuration objects.
360  *
361  * Requires:
362  * \li     'elt' points to cfg_listelt_t obtained from cfg_list_first() or
363  *	a previous call to cfg_list_next().
364  *
365  * Returns:
366  * \li     A pointer to a cfg_listelt_t representing the next element,
367  * 	or NULL if there are no more elements.
368  */
369 
370 unsigned int
371 cfg_list_length(const cfg_obj_t *obj, isc_boolean_t recurse);
372 /*%<
373  * Returns the length of a list of configure objects.  If obj is
374  * not a list, returns 0.  If recurse is true, add in the length of
375  * all contained lists.
376  */
377 
378 cfg_obj_t *
379 cfg_listelt_value(const cfg_listelt_t *elt);
380 /*%<
381  * Returns the configuration object associated with cfg_listelt_t.
382  *
383  * Requires:
384  * \li     'elt' points to cfg_listelt_t obtained from cfg_list_first() or
385  *	cfg_list_next().
386  *
387  * Returns:
388  * \li     A non-NULL pointer to a configuration object.
389  */
390 
391 void
392 cfg_print(const cfg_obj_t *obj,
393 	  void (*f)(void *closure, const char *text, int textlen),
394 	  void *closure);
395 void
396 cfg_printx(const cfg_obj_t *obj, unsigned int flags,
397 	   void (*f)(void *closure, const char *text, int textlen),
398 	   void *closure);
399 
400 #define CFG_PRINTER_XKEY        0x1     /* '?' out shared keys. */
401 
402 /*%<
403  * Print the configuration object 'obj' by repeatedly calling the
404  * function 'f', passing 'closure' and a region of text starting
405  * at 'text' and comprising 'textlen' characters.
406  *
407  * If CFG_PRINTER_XKEY the contents of shared keys will be obscured
408  * by replacing them with question marks ('?')
409  */
410 
411 void
412 cfg_print_grammar(const cfg_type_t *type,
413 	  void (*f)(void *closure, const char *text, int textlen),
414 	  void *closure);
415 /*%<
416  * Print a summary of the grammar of the configuration type 'type'.
417  */
418 
419 isc_boolean_t
420 cfg_obj_istype(const cfg_obj_t *obj, const cfg_type_t *type);
421 /*%<
422  * Return true iff 'obj' is of type 'type'.
423  */
424 
425 void
426 cfg_obj_attach(cfg_obj_t *src, cfg_obj_t **dest);
427 /*%<
428  * Reference a configuration object.
429  */
430 
431 void
432 cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj);
433 /*%<
434  * Delete a reference to a configuration object; destroy the object if
435  * there are no more references.
436  *
437  * Require:
438  * \li     '*obj' is a valid cfg_obj_t.
439  * \li     'pctx' is a valid cfg_parser_t.
440  */
441 
442 void
443 cfg_obj_log(const cfg_obj_t *obj, isc_log_t *lctx, int level,
444 	    const char *fmt, ...)
445 	ISC_FORMAT_PRINTF(4, 5);
446 /*%<
447  * Log a message concerning configuration object 'obj' to the logging
448  * channel of 'pctx', at log level 'level'.  The message will be prefixed
449  * with the file name(s) and line number where 'obj' was defined.
450  */
451 
452 const char *
453 cfg_obj_file(const cfg_obj_t *obj);
454 /*%<
455  * Return the file that defined this object.
456  */
457 
458 unsigned int
459 cfg_obj_line(const cfg_obj_t *obj);
460 /*%<
461  * Return the line in file where this object was defined.
462  */
463 
464 
465 ISC_LANG_ENDDECLS
466 
467 #endif /* ISCCFG_CFG_H */
468