← Back to branch summary

~ubuntu-branches/ubuntu/maverick/bind9/maverick

« back to all changes in this revision

Viewing changes to lib/isccfg/include/isccfg/cfg.h

  • Committer: Bazaar Package Importer
  • Author(s): LaMont Jones, LaMont Jones, Internet Software Consortium, Inc, localization folks
  • Date: 2008-08-02 14:20:20 UTC
  • mfrom: (1.2.1 upstream) (6.1.24 intrepid)
  • Revision ID: james.westby@ubuntu.com-20080802142020-l1hon9jy8lbbjxmg
http://bugs.debian.org/149259
http://bugs.debian.org/492418
http://bugs.debian.org/493392
http://bugs.debian.org/492564
http://bugs.debian.org/490027
http://bugs.debian.org/492949
http://bugs.debian.org/492425
http://bugs.debian.org/491369
http://bugs.debian.org/492048
http://bugs.debian.org/490630
http://bugs.debian.org/492587
[LaMont Jones]

* default to using resolvconf if it is installed
* fix sonames and dependencies.  Closes: #149259, #492418
* Do not build-depend libcap2-dev on non-linux.  Closes: #493392
* drop unused query-loc manpage.  Closes: #492564
* lwresd: Deliver /etc/bind directory.  Closes: #490027
* fix query-source comment in default install

[Internet Software Consortium, Inc]

* 9.5.0-P2.  Closes: #492949

[localization folks]

* l10n: Spanish debconf translation.  Closes: #492425 (Ignacio Mondino)
* l10n: Swedish debconf templates.  Closes: #491369 (Martin Ågren)
* l10n: Japanese debconf translations.  Closes: #492048 (Hideki Yamane
  (Debian-JP))
* l10n: Finnish translation.  Closes: #490630 (Esko Arajärvi)
* l10n: Italian debconf translations.  Closes: #492587 (Alessandro Vietta)

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/isccfg/include/isccfg/cfg.h
1
1
/*
2
 
 * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
 
2
 * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
3
3
 * Copyright (C) 2000-2002  Internet Software Consortium.
4
4
 *
5
 
 * Permission to use, copy, modify, and distribute this software for any
 
5
 * Permission to use, copy, modify, and/or distribute this software for any
6
6
 * purpose with or without fee is hereby granted, provided that the above
7
7
 * copyright notice and this permission notice appear in all copies.
8
8
 *
15
15
 * PERFORMANCE OF THIS SOFTWARE.
16
16
 */
17
17
 
18
 
/* $Id: cfg.h,v 1.30.12.4 2004/03/08 09:05:07 marka Exp $ */
 
18
/* $Id: cfg.h,v 1.44 2007/10/12 04:17:18 each Exp $ */
19
19
 
20
20
#ifndef ISCCFG_CFG_H
21
21
#define ISCCFG_CFG_H 1
24
24
 ***** Module Info
25
25
 *****/
26
26
 
27
 
/*
 
27
/*! \file isccfg/cfg.h
 
28
 * \brief
28
29
 * This is the new, table-driven, YACC-free configuration file parser.
29
30
 */
30
31
 
42
43
 *** Types
43
44
 ***/
44
45
 
 
46
/*%
 
47
 * A configuration parser.
 
48
 */
45
49
typedef struct cfg_parser cfg_parser_t;
46
 
/*
47
 
 * A configuration parser.
48
 
 */
49
50
 
50
 
/*
 
51
/*%
51
52
 * A configuration type definition object.  There is a single
52
53
 * static cfg_type_t object for each data type supported by
53
54
 * the configuration parser.
54
55
 */
55
56
typedef struct cfg_type cfg_type_t;
56
57
 
57
 
/*
 
58
/*%
58
59
 * A configuration object.  This is the basic building block of the
59
60
 * configuration parse tree.  It contains a value (which may be
60
61
 * of one of several types) and information identifying the file
63
64
 */
64
65
typedef struct cfg_obj cfg_obj_t;
65
66
 
66
 
/*
 
67
/*%
67
68
 * A configuration object list element.
68
69
 */
69
70
typedef struct cfg_listelt cfg_listelt_t;
70
71
 
71
 
/*
 
72
/*%
72
73
 * A callback function to be called when parsing an option 
73
74
 * that needs to be interpreted at parsing time, like
74
75
 * "directory".
75
76
 */
76
77
typedef isc_result_t
77
 
(*cfg_parsecallback_t)(const char *clausename, cfg_obj_t *obj, void *arg);
 
78
(*cfg_parsecallback_t)(const char *clausename, const cfg_obj_t *obj, void *arg);
78
79
 
79
80
/***
80
81
 *** Functions
84
85
 
85
86
isc_result_t
86
87
cfg_parser_create(isc_mem_t *mctx, isc_log_t *lctx, cfg_parser_t **ret);
87
 
/*
 
88
/*%<
88
89
 * Create a configuration file parser.  Any warning and error
89
90
 * messages will be logged to 'lctx'.
90
91
 *
97
98
cfg_parser_setcallback(cfg_parser_t *pctx,
98
99
                       cfg_parsecallback_t callback,
99
100
                       void *arg);
100
 
/*
 
101
/*%<
101
102
 * Make the parser call 'callback' whenever it encounters
102
103
 * a configuration clause with the callback attribute,
103
104
 * passing it the clause name, the clause value,
113
114
isc_result_t
114
115
cfg_parse_buffer(cfg_parser_t *pctx, isc_buffer_t *buffer,
115
116
                 const cfg_type_t *type, cfg_obj_t **ret);
116
 
/*
 
117
/*%<
117
118
 * Read a configuration containing data of type 'type'
118
119
 * and make '*ret' point to its parse tree.
119
120
 *
124
125
 * Returns an error if the file does not parse correctly.
125
126
 * 
126
127
 * Requires:
127
 
 *      "filename" is valid.
128
 
 *      "mem" is valid.
129
 
 *      "type" is valid.
130
 
 *      "cfg" is non-NULL and "*cfg" is NULL.
 
128
 *\li   "filename" is valid.
 
129
 *\li   "mem" is valid.
 
130
 *\li   "type" is valid.
 
131
 *\li   "cfg" is non-NULL and "*cfg" is NULL.
131
132
 *
132
133
 * Returns:
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
 
134
 *     \li #ISC_R_SUCCESS                 - success
 
135
 *\li      #ISC_R_NOMEMORY                - no memory available
 
136
 *\li      #ISC_R_INVALIDFILE             - file doesn't exist or is unreadable
 
137
 *\li      others                             - file contains errors
137
138
 */
138
139
 
139
140
void
140
141
cfg_parser_destroy(cfg_parser_t **pctxp);
141
 
/*
 
142
/*%<
142
143
 * Destroy a configuration parser.
143
144
 */
144
145
 
145
146
isc_boolean_t
146
 
cfg_obj_isvoid(cfg_obj_t *obj);
147
 
/*
 
147
cfg_obj_isvoid(const cfg_obj_t *obj);
 
148
/*%<
148
149
 * Return true iff 'obj' is of void type (e.g., an optional 
149
150
 * value not specified).
150
151
 */
151
152
 
152
153
isc_boolean_t
153
 
cfg_obj_ismap(cfg_obj_t *obj);
154
 
/*
 
154
cfg_obj_ismap(const cfg_obj_t *obj);
 
155
/*%<
155
156
 * Return true iff 'obj' is of a map type.
156
157
 */
157
158
 
158
159
isc_result_t
159
 
cfg_map_get(cfg_obj_t *mapobj, const char* name, cfg_obj_t **obj);
160
 
/*
 
160
cfg_map_get(const cfg_obj_t *mapobj, const char* name, const cfg_obj_t **obj);
 
161
/*%<
161
162
 * Extract an element from a configuration object, which
162
163
 * must be of a map type.
163
164
 *
164
165
 * Requires:
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.
 
166
 * \li     'mapobj' points to a valid configuration object of a map type.
 
167
 * \li     'name' points to a null-terminated string.
 
168
 * \li  'obj' is non-NULL and '*obj' is NULL.
168
169
 *
169
170
 * Returns:
170
 
 *      ISC_R_SUCCESS                  - success
171
 
 *      ISC_R_NOTFOUND                 - name not found in map
 
171
 * \li     #ISC_R_SUCCESS                  - success
 
172
 * \li     #ISC_R_NOTFOUND                 - name not found in map
172
173
 */
173
174
 
174
 
cfg_obj_t *
175
 
cfg_map_getname(cfg_obj_t *mapobj);
176
 
/*
 
175
const cfg_obj_t *
 
176
cfg_map_getname(const cfg_obj_t *mapobj);
 
177
/*%<
177
178
 * Get the name of a named map object, like a server "key" clause.
178
179
 *
179
180
 * Requires:
180
 
 *      'mapobj' points to a valid configuration object of a map type.
 
181
 *    \li  'mapobj' points to a valid configuration object of a map type.
181
182
 *
182
183
 * Returns:
183
 
 *      A pointer to a configuration object naming the map object,
 
184
 * \li     A pointer to a configuration object naming the map object,
184
185
 *      or NULL if the map object does not have a name.
185
186
 */
186
187
 
187
188
isc_boolean_t
188
 
cfg_obj_istuple(cfg_obj_t *obj);
189
 
/*
 
189
cfg_obj_istuple(const cfg_obj_t *obj);
 
190
/*%<
190
191
 * Return true iff 'obj' is of a map type.
191
192
 */
192
193
 
193
 
cfg_obj_t *
194
 
cfg_tuple_get(cfg_obj_t *tupleobj, const char *name);
195
 
/*
 
194
const cfg_obj_t *
 
195
cfg_tuple_get(const cfg_obj_t *tupleobj, const char *name);
 
196
/*%<
196
197
 * Extract an element from a configuration object, which
197
198
 * must be of a tuple type.
198
199
 *
199
200
 * Requires:
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.
 
201
 * \li     'tupleobj' points to a valid configuration object of a tuple type.
 
202
 * \li     'name' points to a null-terminated string naming one of the
 
203
 *\li   fields of said tuple type.
203
204
 */
204
205
 
205
206
isc_boolean_t
206
 
cfg_obj_isuint32(cfg_obj_t *obj);
207
 
/*
 
207
cfg_obj_isuint32(const cfg_obj_t *obj);
 
208
/*%<
208
209
 * Return true iff 'obj' is of integer type.
209
210
 */
210
211
 
211
212
isc_uint32_t
212
 
cfg_obj_asuint32(cfg_obj_t *obj);
213
 
/*
 
213
cfg_obj_asuint32(const cfg_obj_t *obj);
 
214
/*%<
214
215
 * Returns the value of a configuration object of 32-bit integer type.
215
216
 *
216
217
 * Requires:
217
 
 *      'obj' points to a valid configuration object of 32-bit integer type.
 
218
 * \li     'obj' points to a valid configuration object of 32-bit integer type.
218
219
 *
219
220
 * Returns:
220
 
 *      A 32-bit unsigned integer.
 
221
 * \li     A 32-bit unsigned integer.
221
222
 */
222
223
 
223
224
isc_boolean_t
224
 
cfg_obj_isuint64(cfg_obj_t *obj);
225
 
/*
 
225
cfg_obj_isuint64(const cfg_obj_t *obj);
 
226
/*%<
226
227
 * Return true iff 'obj' is of integer type.
227
228
 */
228
229
 
229
230
isc_uint64_t
230
 
cfg_obj_asuint64(cfg_obj_t *obj);
231
 
/*
 
231
cfg_obj_asuint64(const cfg_obj_t *obj);
 
232
/*%<
232
233
 * Returns the value of a configuration object of 64-bit integer type.
233
234
 *
234
235
 * Requires:
235
 
 *      'obj' points to a valid configuration object of 64-bit integer type.
 
236
 * \li     'obj' points to a valid configuration object of 64-bit integer type.
236
237
 *
237
238
 * Returns:
238
 
 *      A 64-bit unsigned integer.
 
239
 * \li     A 64-bit unsigned integer.
239
240
 */
240
241
 
241
242
isc_boolean_t
242
 
cfg_obj_isstring(cfg_obj_t *obj);
243
 
/*
 
243
cfg_obj_isstring(const cfg_obj_t *obj);
 
244
/*%<
244
245
 * Return true iff 'obj' is of string type.
245
246
 */
246
247
 
247
 
char *
248
 
cfg_obj_asstring(cfg_obj_t *obj);
249
 
/*
 
248
const char *
 
249
cfg_obj_asstring(const cfg_obj_t *obj);
 
250
/*%<
250
251
 * Returns the value of a configuration object of a string type
251
252
 * as a null-terminated string.
252
253
 *
253
254
 * Requires:
254
 
 *      'obj' points to a valid configuration object of a string type.
 
255
 * \li     'obj' points to a valid configuration object of a string type.
255
256
 *
256
257
 * Returns:
257
 
 *      A pointer to a null terminated string.
 
258
 * \li     A pointer to a null terminated string.
258
259
 */
259
260
 
260
261
isc_boolean_t
261
 
cfg_obj_isboolean(cfg_obj_t *obj);
262
 
/*
 
262
cfg_obj_isboolean(const cfg_obj_t *obj);
 
263
/*%<
263
264
 * Return true iff 'obj' is of a boolean type.
264
265
 */
265
266
 
266
267
isc_boolean_t
267
 
cfg_obj_asboolean(cfg_obj_t *obj);
268
 
/*
 
268
cfg_obj_asboolean(const cfg_obj_t *obj);
 
269
/*%<
269
270
 * Returns the value of a configuration object of a boolean type.
270
271
 *
271
272
 * Requires:
272
 
 *      'obj' points to a valid configuration object of a boolean type.
 
273
 * \li     'obj' points to a valid configuration object of a boolean type.
273
274
 *
274
275
 * Returns:
275
 
 *      A boolean value.
 
276
 * \li     A boolean value.
276
277
 */
277
278
 
278
279
isc_boolean_t
279
 
cfg_obj_issockaddr(cfg_obj_t *obj);
280
 
/*
 
280
cfg_obj_issockaddr(const cfg_obj_t *obj);
 
281
/*%<
281
282
 * Return true iff 'obj' is a socket address.
282
283
 */
283
284
 
284
 
isc_sockaddr_t *
285
 
cfg_obj_assockaddr(cfg_obj_t *obj);
286
 
/*
 
285
const isc_sockaddr_t *
 
286
cfg_obj_assockaddr(const cfg_obj_t *obj);
 
287
/*%<
287
288
 * Returns the value of a configuration object representing a socket address.
288
289
 *
289
290
 * Requires:
290
 
 *      'obj' points to a valid configuration object of a socket address type.
 
291
 * \li     'obj' points to a valid configuration object of a socket address type.
291
292
 *
292
293
 * Returns:
293
 
 *      A pointer to a sockaddr.  The sockaddr must be copied by the caller
 
294
 * \li     A pointer to a sockaddr.  The sockaddr must be copied by the caller
294
295
 *      if necessary.
295
296
 */
296
297
 
297
298
isc_boolean_t
298
 
cfg_obj_isnetprefix(cfg_obj_t *obj);
299
 
/*
 
299
cfg_obj_isnetprefix(const cfg_obj_t *obj);
 
300
/*%<
300
301
 * Return true iff 'obj' is a network prefix.
301
302
 */
302
303
 
303
304
void
304
 
cfg_obj_asnetprefix(cfg_obj_t *obj, isc_netaddr_t *netaddr,
 
305
cfg_obj_asnetprefix(const cfg_obj_t *obj, isc_netaddr_t *netaddr,
305
306
                    unsigned int *prefixlen);
306
 
/*
 
307
/*%<
307
308
 * Gets the value of a configuration object representing a network
308
309
 * prefix.  The network address is returned through 'netaddr' and the
309
310
 * prefix length in bits through 'prefixlen'.
310
311
 *
311
312
 * Requires:
312
 
 *      'obj' points to a valid configuration object of network prefix type.
313
 
 *      'netaddr' and 'prefixlen' are non-NULL.
 
313
 * \li     'obj' points to a valid configuration object of network prefix type.
 
314
 *\li   'netaddr' and 'prefixlen' are non-NULL.
314
315
 */
315
316
 
316
317
isc_boolean_t
317
 
cfg_obj_islist(cfg_obj_t *obj);
318
 
/*
 
318
cfg_obj_islist(const cfg_obj_t *obj);
 
319
/*%<
319
320
 * Return true iff 'obj' is of list type.
320
321
 */
321
322
 
322
 
cfg_listelt_t *
323
 
cfg_list_first(cfg_obj_t *obj);
324
 
/*
 
323
const cfg_listelt_t *
 
324
cfg_list_first(const cfg_obj_t *obj);
 
325
/*%<
325
326
 * Returns the first list element in a configuration object of a list type.
326
327
 *
327
328
 * Requires:
328
 
 *      'obj' points to a valid configuration object of a list type or NULL.
 
329
 * \li     'obj' points to a valid configuration object of a list type or NULL.
329
330
 *
330
331
 * Returns:
331
 
 *      A pointer to a cfg_listelt_t representing the first list element,
 
332
 *   \li   A pointer to a cfg_listelt_t representing the first list element,
332
333
 *      or NULL if the list is empty or nonexistent.
333
334
 */
334
335
 
335
 
cfg_listelt_t *
336
 
cfg_list_next(cfg_listelt_t *elt);
337
 
/*
 
336
const cfg_listelt_t *
 
337
cfg_list_next(const cfg_listelt_t *elt);
 
338
/*%<
338
339
 * Returns the next element of a list of configuration objects.
339
340
 *
340
341
 * Requires:
341
 
 *      'elt' points to cfg_listelt_t obtained from cfg_list_first() or
 
342
 * \li     'elt' points to cfg_listelt_t obtained from cfg_list_first() or
342
343
 *      a previous call to cfg_list_next().
343
344
 *
344
345
 * Returns:
345
 
 *      A pointer to a cfg_listelt_t representing the next element,
 
346
 * \li     A pointer to a cfg_listelt_t representing the next element,
346
347
 *      or NULL if there are no more elements.
347
348
 */
348
349
 
349
 
cfg_obj_t *
350
 
cfg_listelt_value(cfg_listelt_t *elt);
351
 
/*
 
350
unsigned int
 
351
cfg_list_length(const cfg_obj_t *obj, isc_boolean_t recurse);
 
352
/*%<
 
353
 * Returns the length of a list of configure objects.  If obj is
 
354
 * not a list, returns 0.  If recurse is true, add in the length of
 
355
 * all contained lists.
 
356
 */
 
357
 
 
358
const cfg_obj_t *
 
359
cfg_listelt_value(const cfg_listelt_t *elt);
 
360
/*%<
352
361
 * Returns the configuration object associated with cfg_listelt_t.
353
362
 *
354
363
 * Requires:
355
 
 *      'elt' points to cfg_listelt_t obtained from cfg_list_first() or
 
364
 * \li     'elt' points to cfg_listelt_t obtained from cfg_list_first() or
356
365
 *      cfg_list_next().
357
366
 *
358
367
 * Returns:
359
 
 *      A non-NULL pointer to a configuration object.
 
368
 * \li     A non-NULL pointer to a configuration object.
360
369
 */
361
370
 
362
371
void
363
 
cfg_print(cfg_obj_t *obj,
 
372
cfg_print(const cfg_obj_t *obj,
364
373
          void (*f)(void *closure, const char *text, int textlen),
365
374
          void *closure);
366
 
/*
 
375
/*%<
367
376
 * Print the configuration object 'obj' by repeatedly calling the
368
377
 * function 'f', passing 'closure' and a region of text starting
369
378
 * at 'text' and comprising 'textlen' characters.
373
382
cfg_print_grammar(const cfg_type_t *type,
374
383
          void (*f)(void *closure, const char *text, int textlen),
375
384
          void *closure);
376
 
/*
 
385
/*%<
377
386
 * Print a summary of the grammar of the configuration type 'type'.
378
387
 */
379
388
 
380
389
isc_boolean_t
381
 
cfg_obj_istype(cfg_obj_t *obj, const cfg_type_t *type);
382
 
/*
 
390
cfg_obj_istype(const cfg_obj_t *obj, const cfg_type_t *type);
 
391
/*%<
383
392
 * Return true iff 'obj' is of type 'type'. 
384
393
 */
385
394
 
386
395
void cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj);
387
 
/*
 
396
/*%<
388
397
 * Destroy a configuration object.
389
398
 */
390
399
 
391
400
void
392
 
cfg_obj_log(cfg_obj_t *obj, isc_log_t *lctx, int level, const char *fmt, ...)
 
401
cfg_obj_log(const cfg_obj_t *obj, isc_log_t *lctx, int level,
 
402
            const char *fmt, ...)
393
403
        ISC_FORMAT_PRINTF(4, 5);
394
 
/*
 
404
/*%<
395
405
 * Log a message concerning configuration object 'obj' to the logging
396
406
 * channel of 'pctx', at log level 'level'.  The message will be prefixed
397
407
 * with the file name(s) and line number where 'obj' was defined.
398
408
 */
399
409
 
400
410
const char *
401
 
cfg_obj_file(cfg_obj_t *obj);
402
 
/*
 
411
cfg_obj_file(const cfg_obj_t *obj);
 
412
/*%<
403
413
 * Return the file that defined this object.
404
414
 */
405
415
 
406
416
unsigned int
407
 
cfg_obj_line(cfg_obj_t *obj);
408
 
/*
 
417
cfg_obj_line(const cfg_obj_t *obj);
 
418
/*%<
409
419
 * Return the line in file where this object was defined.
410
420
 */
411
421