/contrib/bind9/lib/isccfg/include/isccfg/cfg.h

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