Annotation of embedaddon/confuse/src/confuse.h, revision 1.1.1.1
1.1 misho 1: /*
2: * Copyright (c) 2002,2003,2007 Martin Hedenfalk <martin@bzero.se>
3: *
4: * Permission to use, copy, modify, and distribute this software for any
5: * purpose with or without fee is hereby granted, provided that the above
6: * copyright notice and this permission notice appear in all copies.
7: *
8: * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9: * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10: * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11: * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12: * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13: * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14: * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15: */
16:
17: /** A configuration file parser library.
18: * @file confuse.h
19: *
20: */
21:
22: /**
23: * \mainpage libConfuse Documentation
24: *
25: * \section intro
26: *
27: * Copyright © 2002-2003 Martin Hedenfalk <martin@bzero.se>
28: *
29: * The latest versions of this manual and the libConfuse software are
30: * available at http://www.nongnu.org/confuse/
31: *
32: *
33: * <em>If you can't convince, confuse.</em>
34: */
35:
36: #ifndef _cfg_h_
37: #define _cfg_h_
38:
39: #ifdef __cplusplus
40: extern "C" {
41: #endif
42:
43: #include <stdio.h>
44: #include <stdarg.h>
45:
46: #if defined(_WIN32) && !defined(__GNUC__)
47: # ifdef HAVE__FILENO
48: # define fileno _fileno
49: # endif
50: # include <io.h>
51: # ifdef HAVE__ISATTY
52: # define isatty _isatty
53: # endif
54: # ifdef BUILDING_DLL
55: # define DLLIMPORT __declspec (dllexport)
56: # else /* ! BUILDING_DLL */
57: # define DLLIMPORT __declspec (dllimport)
58: # endif /* BUILDING_DLL */
59: #else /* ! _WIN32 || __GNUC__ */
60: # define DLLIMPORT
61: #endif /* _WIN32 */
62:
63: #ifndef __BORLANDC__
64: # define __export
65: #endif
66:
67: /** Fundamental option types */
68: enum cfg_type_t {
69: CFGT_NONE,
70: CFGT_INT, /**< integer */
71: CFGT_FLOAT, /**< floating point number */
72: CFGT_STR, /**< string */
73: CFGT_BOOL, /**< boolean value */
74: CFGT_SEC, /**< section */
75: CFGT_FUNC, /**< function */
76: CFGT_PTR /**< pointer to user-defined value */
77: };
78: typedef enum cfg_type_t cfg_type_t;
79:
80: /** Flags. */
81: #define CFGF_NONE 0
82: #define CFGF_MULTI 1 /**< option may be specified multiple times (only applies to sections) */
83: #define CFGF_LIST 2 /**< option is a list */
84: #define CFGF_NOCASE 4 /**< configuration file is case insensitive */
85: #define CFGF_TITLE 8 /**< option has a title (only applies to sections) */
86: #define CFGF_NODEFAULT 16 /**< option has no default value */
87: #define CFGF_NO_TITLE_DUPES 32 /**< multiple section titles must be unique
88: (duplicates raises an error, only applies to
89: sections) */
90:
91: #define CFGF_RESET 64
92: #define CFGF_DEFINIT 128
93:
94: /** Return codes from cfg_parse(). */
95: #define CFG_SUCCESS 0
96: #define CFG_FILE_ERROR -1
97: #define CFG_PARSE_ERROR 1
98:
99: typedef union cfg_value_t cfg_value_t;
100: typedef struct cfg_opt_t cfg_opt_t;
101: typedef struct cfg_t cfg_t;
102: typedef struct cfg_defvalue_t cfg_defvalue_t;
103: typedef int cfg_flag_t;
104:
105: /** Function prototype used by CFGT_FUNC options.
106: *
107: * This is a callback function, registered with the CFG_FUNC
108: * initializer. Each time libConfuse finds a function, the registered
109: * callback function is called (parameters are passed as strings, any
110: * conversion to other types should be made in the callback
111: * function). libConfuse does not support any storage of the data
112: * found; these are passed as parameters to the callback, and it's the
113: * responsibility of the callback function to do whatever it should do
114: * with the data.
115: *
116: * @param cfg The configuration file context.
117: * @param opt The option.
118: * @param argc Number of arguments passed. The callback function is
119: * responsible for checking that the correct number of arguments are
120: * passed.
121: * @param argv Arguments as an array of character strings.
122: *
123: * @return On success, 0 should be returned. All other values
124: * indicates an error, and the parsing is aborted. The callback
125: * function should notify the error itself, for example by calling
126: * cfg_error().
127: *
128: * @see CFG_FUNC
129: */
130: typedef int (*cfg_func_t)(cfg_t *cfg, cfg_opt_t *opt,
131: int argc, const char **argv);
132:
133: /** Function prototype used by the cfg_print_ functions.
134: *
135: * This callback function is used to print option values. For options
136: * with a value parsing callback, this is often required, especially
137: * if a string is mapped to an integer by the callback. This print
138: * callback must then map the integer back to the appropriate string.
139: *
140: * Except for functions, the print callback function should only print
141: * the value of the option, not the name and the equal sign (that is
142: * handled by the cfg_opt_print function). For function options
143: * however, the name and the parenthesis must be printed by this
144: * function. The value to print can be accessed with the cfg_opt_get
145: * functions.
146: *
147: * @param opt The option structure (eg, as returned from cfg_getopt())
148: * @param index Index of the value to get. Zero based.
149: * @param fp File stream to print to, use stdout to print to the screen.
150: *
151: * @see cfg_print, cfg_set_print_func
152: */
153: typedef void (*cfg_print_func_t)(cfg_opt_t *opt, unsigned int index, FILE *fp);
154:
155: /** Value parsing callback prototype
156: *
157: * This is a callback function (different from the one registered with the
158: * CFG_FUNC initializer) used to parse a value. This can be used to override
159: * the internal parsing of a value.
160: *
161: * Suppose you want an integer option that only can have certain values, for
162: * example 1, 2 and 3, and these should be written in the configuration file as
163: * "yes", "no" and "maybe". The callback function would be called with the
164: * found value ("yes", "no" or "maybe") as a string, and the result should be
165: * stored in the result parameter.
166: *
167: * @param cfg The configuration file context.
168: * @param opt The option.
169: * @param value The value found in the configuration file.
170: * @param result Pointer to storage for the result, cast to a void pointer.
171: *
172: * @return On success, 0 should be returned. All other values indicates an
173: * error, and the parsing is aborted. The callback function should notify the
174: * error itself, for example by calling cfg_error().
175: */
176: typedef int (*cfg_callback_t)(cfg_t *cfg, cfg_opt_t *opt,
177: const char *value, void *result);
178:
179: /** Validating callback prototype
180: *
181: * This callback function is called after an option has been parsed and set.
182: * The function is called for both fundamental values (strings, integers etc)
183: * as well as lists and sections. This can for example be used to validate that
184: * all required options in a section has been set to sane values.
185: *
186: * @return On success, 0 should be returned. All other values indicates an
187: * error, and the parsing is aborted. The callback function should notify the
188: * error itself, for example by calling cfg_error().
189: *
190: * @see cfg_set_validate_func
191: */
192: typedef int (*cfg_validate_callback_t)(cfg_t *cfg, cfg_opt_t *opt);
193:
194: /** User-defined memory release function for CFG_PTR values
195: *
196: * This callback is used to free memory allocated in a value parsing callback
197: * function. Especially useful for CFG_PTR options, since libConfuse will not
198: * itself release such values. If the values are simply allocated with a
199: * malloc(3), one can use the standard free(3) function here.
200: *
201: */
202: typedef void (*cfg_free_func_t)(void *value);
203:
204: /** Boolean values. */
205: typedef enum {cfg_false, cfg_true} cfg_bool_t;
206:
207: /** Error reporting function. */
208: typedef void (*cfg_errfunc_t)(cfg_t *cfg, const char *fmt, va_list ap);
209:
210: /** Data structure holding information about a "section". Sections can
211: * be nested. A section has a list of options (strings, numbers,
212: * booleans or other sections) grouped together.
213: */
214: struct cfg_t {
215: cfg_flag_t flags; /**< Any flags passed to cfg_init() */
216: char *name; /**< The name of this section, the root
217: * section returned from cfg_init() is
218: * always named "root" */
219: cfg_opt_t *opts; /**< Array of options */
220: char *title; /**< Optional title for this section, only
221: * set if CFGF_TITLE flag is set */
222: char *filename; /**< Name of the file being parsed */
223: int line; /**< Line number in the config file */
224: cfg_errfunc_t errfunc; /**< This function (if set with
225: * cfg_set_error_function) is called for
226: * any error message. */
227: };
228:
229: /** Data structure holding the value of a fundamental option value.
230: */
231: union cfg_value_t {
232: long int number; /**< integer value */
233: double fpnumber; /**< floating point value */
234: cfg_bool_t boolean; /**< boolean value */
235: char *string; /**< string value */
236: cfg_t *section; /**< section value */
237: void *ptr; /**< user-defined value */
238: };
239:
240: /** Data structure holding the default value given by the
241: * initialization macros.
242: */
243: struct cfg_defvalue_t {
244: long int number; /**< default integer value */
245: double fpnumber; /**< default floating point value */
246: cfg_bool_t boolean; /**< default boolean value */
247: char *string; /**< default string value */
248: char *parsed; /**< default value that is parsed by
249: * libConfuse, used for lists and
250: * functions */
251: };
252:
253: /** Data structure holding information about an option. The value(s)
254: * are stored as an array of fundamental values (strings, numbers,
255: * etc).
256: */
257: struct cfg_opt_t {
258: char *name; /**< The name of the option */
259: cfg_type_t type; /**< Type of option */
260: unsigned int nvalues; /**< Number of values parsed */
261: cfg_value_t **values; /**< Array of found values */
262: cfg_flag_t flags; /**< Flags */
263: cfg_opt_t *subopts; /**< Suboptions (only applies to sections) */
264: cfg_defvalue_t def; /**< Default value */
265: cfg_func_t func; /**< Function callback for CFGT_FUNC options */
266: void *simple_value; /**< Pointer to user-specified variable to
267: * store simple values (created with the
268: * CFG_SIMPLE_* initializers) */
269: cfg_callback_t parsecb; /**< Value parsing callback function */
270: cfg_validate_callback_t validcb; /**< Value validating callback function */
271: cfg_print_func_t pf; /**< print callback function */
272: cfg_free_func_t freecb; /***< user-defined memory release function */
273: };
274:
275: extern const char __export confuse_copyright[];
276: extern const char __export confuse_version[];
277: extern const char __export confuse_author[];
278:
279: #define __CFG_STR(name, def, flags, svalue, cb) \
280: {name,CFGT_STR,0,0,flags,0,{0,0,cfg_false,def,0},0,svalue,cb,0,0,0}
281: #define __CFG_STR_LIST(name, def, flags, svalue, cb) \
282: {name,CFGT_STR,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,svalue,cb,0,0,0}
283:
284: /** Initialize a string option
285: */
286: #define CFG_STR(name, def, flags) \
287: __CFG_STR(name, def, flags, 0, 0)
288:
289: /** Initialize a string list option
290: */
291: #define CFG_STR_LIST(name, def, flags) \
292: __CFG_STR_LIST(name, def, flags, 0, 0)
293:
294: /** Initialize a string option with a value parsing callback
295: */
296: #define CFG_STR_CB(name, def, flags, cb) \
297: __CFG_STR(name, def, flags, 0, cb)
298:
299: /** Initialize a string list option with a value parsing callback
300: */
301: #define CFG_STR_LIST_CB(name, def, flags, cb) \
302: __CFG_STR_LIST(name, def, flags, 0, cb)
303:
304: /** Initialize a "simple" string option.
305: *
306: * "Simple" options (in lack of a better expression) does not support
307: * lists of values or multiple sections. LibConfuse will store the
308: * value of a simple option in the user-defined location specified by
309: * the value parameter in the initializer. Simple options are not
310: * stored in the cfg_t context, only a pointer. Sections can not be
311: * initialized as a "simple" option.
312: *
313: * As of version 2.2, libConfuse can now return the values of simple
314: * options with the cfg_get functions. This allows using the new
315: * cfg_print function with simple options.
316: *
317: * libConfuse doesn't support handling default values for "simple"
318: * options. They are assumed to be set by the calling application
319: * before cfg_parse is called.
320: *
321: * @param name name of the option
322: * @param svalue pointer to a character pointer (a char **). This value
323: * must be initalized either to NULL or to a malloc()'ed string. You
324: * can't use
325: * <pre>
326: * char *user = "joe";
327: * ...
328: * cfg_opt_t opts[] = {
329: * CFG_SIMPLE_STR("user", &user),
330: * ...
331: * </pre>
332: * since libConfuse will try to free the static string "joe" (which is
333: * an error) when a "user" option is found. Rather, use the following
334: * code snippet:
335: * <pre>
336: * char *user = strdup("joe");
337: * ...
338: * cfg_opt_t opts[] = {
339: * CFG_SIMPLE_STR("user", &user),
340: * ...
341: * </pre>
342: * Alternatively, the default value can be set after the opts struct
343: * is defined, as in:
344: * <pre>
345: * char *user = 0;
346: * ...
347: * cfg_opt_t opts[] = {
348: * CFG_SIMPLE_STR("user", &user),
349: * ...
350: * user = strdup("joe");
351: * cfg = cfg_init(opts, 0);
352: * cfg_parse(cfg, filename);
353: * </pre>
354: *
355: */
356: #define CFG_SIMPLE_STR(name, svalue) \
357: __CFG_STR(name, 0, CFGF_NONE, svalue, 0)
358:
359:
360: #define __CFG_INT(name, def, flags, svalue, cb) \
361: {name,CFGT_INT,0,0,flags,0,{def,0,cfg_false,0,0},0,svalue,cb,0,0,0}
362: #define __CFG_INT_LIST(name, def, flags, svalue, cb) \
363: {name,CFGT_INT,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,svalue,cb,0,0,0}
364:
365: /** Initialize an integer option
366: */
367: #define CFG_INT(name, def, flags) \
368: __CFG_INT(name, def, flags, 0, 0)
369:
370: /** Initialize an integer list option
371: */
372: #define CFG_INT_LIST(name, def, flags) \
373: __CFG_INT_LIST(name, def, flags, 0, 0)
374:
375: /** Initialize an integer option with a value parsing callback
376: */
377: #define CFG_INT_CB(name, def, flags, cb) \
378: __CFG_INT(name, def, flags, 0, cb)
379:
380: /** Initialize an integer list option with a value parsing callback
381: */
382: #define CFG_INT_LIST_CB(name, def, flags, cb) \
383: __CFG_INT_LIST(name, def, flags, 0, cb)
384:
385: /** Initialize a "simple" integer option (see documentation for
386: * CFG_SIMPLE_STR for more information).
387: */
388: #define CFG_SIMPLE_INT(name, svalue) \
389: __CFG_INT(name, 0, CFGF_NONE, svalue, 0)
390:
391:
392:
393: #define __CFG_FLOAT(name, def, flags, svalue, cb) \
394: {name,CFGT_FLOAT,0,0,flags,0,{0,def,cfg_false,0,0},0,svalue,cb,0,0,0}
395: #define __CFG_FLOAT_LIST(name, def, flags, svalue, cb) \
396: {name,CFGT_FLOAT,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,svalue,cb,0,0,0}
397:
398: /** Initialize a floating point option
399: */
400: #define CFG_FLOAT(name, def, flags) \
401: __CFG_FLOAT(name, def, flags, 0, 0)
402:
403: /** Initialize a floating point list option
404: */
405: #define CFG_FLOAT_LIST(name, def, flags) \
406: __CFG_FLOAT_LIST(name, def, flags, 0, 0)
407:
408: /** Initialize a floating point option with a value parsing callback
409: */
410: #define CFG_FLOAT_CB(name, def, flags, cb) \
411: __CFG_FLOAT(name, def, flags, 0, cb)
412:
413: /** Initialize a floating point list option with a value parsing callback
414: */
415: #define CFG_FLOAT_LIST_CB(name, def, flags, cb) \
416: __CFG_FLOAT_LIST(name, def, flags, 0, cb)
417:
418: /** Initialize a "simple" floating point option (see documentation for
419: * CFG_SIMPLE_STR for more information).
420: */
421: #define CFG_SIMPLE_FLOAT(name, svalue) \
422: __CFG_FLOAT(name, 0, CFGF_NONE, svalue, 0)
423:
424:
425:
426: #define __CFG_BOOL(name, def, flags, svalue, cb) \
427: {name,CFGT_BOOL,0,0,flags,0,{0,0,def,0,0},0,svalue,cb,0,0,0}
428: #define __CFG_BOOL_LIST(name, def, flags, svalue, cb) \
429: {name,CFGT_BOOL,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,svalue,cb,0,0,0}
430:
431: /** Initialize a boolean option
432: */
433: #define CFG_BOOL(name, def, flags) \
434: __CFG_BOOL(name, def, flags, 0, 0)
435:
436: /** Initialize a boolean list option
437: */
438: #define CFG_BOOL_LIST(name, def, flags) \
439: __CFG_BOOL_LIST(name, def, flags, 0, 0)
440:
441: /** Initialize a boolean option with a value parsing callback
442: */
443: #define CFG_BOOL_CB(name, def, flags, cb) \
444: __CFG_BOOL(name, def, flags, 0, cb)
445:
446: /** Initialize a boolean list option with a value parsing callback
447: */
448: #define CFG_BOOL_LIST_CB(name, def, flags, cb) \
449: __CFG_BOOL_LIST(name, def, flags, 0, cb)
450:
451: /** Initialize a "simple" boolean option (see documentation for
452: * CFG_SIMPLE_STR for more information).
453: */
454: #define CFG_SIMPLE_BOOL(name, svalue) \
455: __CFG_BOOL(name, cfg_false, CFGF_NONE, svalue, 0)
456:
457:
458:
459: /** Initialize a section
460: *
461: * @param name The name of the option
462: * @param opts Array of options that are valid within this section
463:
464: * @param flags Flags, specify CFGF_MULTI if it should be possible to
465: * have multiples of the same section, and CFGF_TITLE if the
466: * section(s) must have a title (which can be used in the
467: * cfg_gettsec() function)
468: *
469: */
470: #define CFG_SEC(name, opts, flags) \
471: {name,CFGT_SEC,0,0,flags,opts,{0,0,cfg_false,0,0},0,0,0,0,0,0}
472:
473:
474:
475: /** Initialize a function
476: * @param name The name of the option
477: * @param func The callback function.
478: *
479: * @see cfg_func_t
480: */
481: #define CFG_FUNC(name, func) \
482: {name,CFGT_FUNC,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},func,0,0,0,0,0}
483:
484:
485: #define __CFG_PTR(name, def, flags, svalue, parsecb, freecb) \
486: {name,CFGT_PTR,0,0,flags,0,{0,0,cfg_false,0,def},0,svalue,parsecb,0,0,freecb}
487: #define __CFG_PTR_LIST(name, def, flags, svalue, parsecb, freecb) \
488: {name,CFGT_PTR,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,svalue,parsecb,0,0,freecb}
489:
490: /** Initialize a user-defined option
491: *
492: * CFG_PTR options can only be used together with a value parsing callback.
493: *
494: * @param name The name of the option
495: * @param def Default value
496: * @param flags Flags
497: * @param parsecb Value parsing callback
498: * @param freecb Memory release function
499: *
500: * @see cfg_callback_t, cfg_free_func_t
501: */
502: #define CFG_PTR_CB(name, def, flags, parsecb, freecb) \
503: __CFG_PTR(name, def, flags, 0, parsecb, freecb)
504:
505: /** Initialize a list of user-defined options
506: */
507: #define CFG_PTR_LIST_CB(name, def, flags, parsecb, freecb) \
508: __CFG_PTR(name, def, flags | CFGF_LIST, 0, parsecb, freecb)
509:
510: /*#define CFG_SIMPLE_PTR(name, svalue, cb) \
511: __CFG_PTR(name, 0, 0, svalue, cb)*/
512:
513:
514: /** Terminate list of options. This must be the last initializer in
515: * the option list.
516: */
517: #define CFG_END() \
518: {0,CFGT_NONE,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},0,0,0,0,0,0}
519:
520:
521:
522: /** Create and initialize a cfg_t structure. This should be the first function
523: * called when setting up the parsing of a configuration file. The options
524: * passed in the first parameter is initialized using the CFG_* initializers.
525: * The last option in the option array must be CFG_END(), unless you like
526: * segmentation faults.
527: *
528: * The options must no longer be defined in the same scope as where the cfg_xxx
529: * functions are used (since version 2.3).
530: *
531: * @param opts An arrary of options
532: * @param flags One or more flags (bitwise or'ed together). Currently only
533: * CFGF_NOCASE is available. Use 0 if no flags are needed.
534: *
535: * @return A configuration context structure. This pointer is passed
536: * to almost all other functions as the first parameter.
537: */
538: DLLIMPORT cfg_t * __export cfg_init(cfg_opt_t *opts, cfg_flag_t flags);
539:
540: /** Parse a configuration file. Tilde expansion is performed on the
541: * filename before it is opened. After a configuration file has been
542: * initialized (with cfg_init()) and parsed (with cfg_parse()), the
543: * values can be read with the cfg_getXXX functions.
544: *
545: * @param cfg The configuration file context as returned from cfg_init().
546: * @param filename The name of the file to parse.
547: *
548: * @return On success, CFG_SUCCESS is returned. If the file couldn't
549: * be opened for reading, CFG_FILE_ERROR is returned. On all other
550: * errors, CFG_PARSE_ERROR is returned and cfg_error() was called with
551: * a descriptive error message.
552: */
553: DLLIMPORT int __export cfg_parse(cfg_t *cfg, const char *filename);
554:
555: /** Same as cfg_parse() above, but takes an already opened file as
556: * argument. Reading begins at the current position. After parsing,
557: * the position is not reset. The caller is responsible for closing
558: * the file.
559: *
560: * @param cfg The configuration file context as returned from cfg_init().
561: * @param fp An open file stream.
562: *
563: * @see cfg_parse()
564: */
565: DLLIMPORT int __export cfg_parse_fp(cfg_t *cfg, FILE *fp);
566:
567: /** Same as cfg_parse() above, but takes a character buffer as
568: * argument.
569: *
570: * @param cfg The configuration file context as returned from cfg_init().
571: * @param buf A zero-terminated string with configuration directives.
572: *
573: * @see cfg_parse()
574: */
575: DLLIMPORT int __export cfg_parse_buf(cfg_t *cfg, const char *buf);
576:
577: /** Free the memory allocated for the values of a given option. Only
578: * the values are freed, not the option itself (it is freed by cfg_free()).
579: *
580: * @see cfg_free()
581: */
582: DLLIMPORT void __export cfg_free_value(cfg_opt_t *opt);
583:
584: /** Free a cfg_t context. All memory allocated by the cfg_t context
585: * structure are freed, and can't be used in any further cfg_* calls.
586: */
587: DLLIMPORT void __export cfg_free(cfg_t *cfg);
588:
589: /** Install a user-defined error reporting function.
590: * @return The old error reporting function is returned.
591: */
592: DLLIMPORT cfg_errfunc_t __export cfg_set_error_function(cfg_t *cfg,
593: cfg_errfunc_t errfunc);
594:
595: /** Show a parser error. Any user-defined error reporting function is called.
596: * @see cfg_set_error_function
597: */
598: DLLIMPORT void __export cfg_error(cfg_t *cfg, const char *fmt, ...);
599:
600: /** Returns the value of an integer option, given a cfg_opt_t pointer.
601: * @param opt The option structure (eg, as returned from cfg_getopt())
602: * @param index Index of the value to get. Zero based.
603: * @see cfg_getnint
604: */
605: DLLIMPORT signed long __export cfg_opt_getnint(cfg_opt_t *opt, unsigned int index);
606:
607: /** Indexed version of cfg_getint(), used for lists.
608: * @param cfg The configuration file context.
609: * @param name The name of the option.
610: * @param index Index of the value to get. Zero based.
611: * @see cfg_getint
612: */
613: DLLIMPORT long int __export cfg_getnint(cfg_t *cfg, const char *name,
614: unsigned int index);
615:
616: /** Returns the value of an integer option. This is the same as
617: * calling cfg_getnint with index 0.
618: * @param cfg The configuration file context.
619: * @param name The name of the option.
620: * @return The requested value is returned. If the option was not set
621: * in the configuration file, the default value given in the
622: * corresponding cfg_opt_t structure is returned. It is an error to
623: * try to get an option that isn't declared.
624: */
625: DLLIMPORT long int __export cfg_getint(cfg_t *cfg, const char *name);
626:
627: /** Returns the value of a floating point option, given a cfg_opt_t pointer.
628: * @param opt The option structure (eg, as returned from cfg_getopt())
629: * @param index Index of the value to get. Zero based.
630: * @see cfg_getnfloat
631: */
632: DLLIMPORT double __export cfg_opt_getnfloat(cfg_opt_t *opt, unsigned int index);
633:
634: /** Indexed version of cfg_getfloat(), used for lists.
635: * @param cfg The configuration file context.
636: * @param name The name of the option.
637: * @param index Index of the value to get. Zero based.
638: * @see cfg_getfloat
639: */
640: DLLIMPORT double __export cfg_getnfloat(cfg_t *cfg, const char *name,
641: unsigned int index);
642:
643: /** Returns the value of a floating point option.
644: * @param cfg The configuration file context.
645: * @param name The name of the option.
646: * @return The requested value is returned. If the option was not set
647: * in the configuration file, the default value given in the
648: * corresponding cfg_opt_t structure is returned. It is an error to
649: * try to get an option that isn't declared.
650: */
651: DLLIMPORT double __export cfg_getfloat(cfg_t *cfg, const char *name);
652:
653: /** Returns the value of a string option, given a cfg_opt_t pointer.
654: * @param opt The option structure (eg, as returned from cfg_getopt())
655: * @param index Index of the value to get. Zero based.
656: * @see cfg_getnstr
657: */
658: DLLIMPORT char * __export cfg_opt_getnstr(cfg_opt_t *opt, unsigned int index);
659:
660: /** Indexed version of cfg_getstr(), used for lists.
661: * @param cfg The configuration file context.
662: * @param name The name of the option.
663: * @param index Index of the value to get. Zero based.
664: * @see cfg_getstr
665: */
666: DLLIMPORT char * __export cfg_getnstr(cfg_t *cfg, const char *name,
667: unsigned int index);
668:
669: /** Returns the value of a string option.
670: * @param cfg The configuration file context.
671: * @param name The name of the option.
672: * @return The requested value is returned. If the option was not set
673: * in the configuration file, the default value given in the
674: * corresponding cfg_opt_t structure is returned. It is an error to
675: * try to get an option that isn't declared.
676: */
677: DLLIMPORT char * __export cfg_getstr(cfg_t *cfg, const char *name);
678:
679: /** Returns the value of a boolean option, given a cfg_opt_t pointer.
680: * @param opt The option structure (eg, as returned from cfg_getopt())
681: * @param index Index of the value to get. Zero based.
682: * @see cfg_getnbool
683: */
684: DLLIMPORT cfg_bool_t __export cfg_opt_getnbool(cfg_opt_t *opt, unsigned int index);
685:
686: /** Indexed version of cfg_getbool(), used for lists.
687: *
688: * @param cfg The configuration file context.
689: * @param name The name of the option.
690: * @param index Index of the value to get. Zero based.
691: * @see cfg_getbool
692: */
693: DLLIMPORT cfg_bool_t __export cfg_getnbool(cfg_t *cfg, const char *name,
694: unsigned int index);
695:
696: /** Returns the value of a boolean option.
697: * @param cfg The configuration file context.
698: * @param name The name of the option.
699: * @return The requested value is returned. If the option was not set
700: * in the configuration file, the default value given in the
701: * corresponding cfg_opt_t structure is returned. It is an error to
702: * try to get an option that isn't declared.
703: */
704: DLLIMPORT cfg_bool_t __export cfg_getbool(cfg_t *cfg, const char *name);
705:
706:
707: DLLIMPORT void * __export cfg_opt_getnptr(cfg_opt_t *opt, unsigned int index);
708: DLLIMPORT void * __export cfg_getnptr(cfg_t *cfg, const char *name, unsigned int indx);
709:
710: /** Returns the value of a user-defined option (void pointer).
711: * @param cfg The configuration file context.
712: * @param name The name of the option.
713: * @return The requested value is returned. If the option was not set
714: * in the configuration file, the default value given in the
715: * corresponding cfg_opt_t structure is returned. It is an error to
716: * try to get an option that isn't declared.
717: */
718: DLLIMPORT void * __export cfg_getptr(cfg_t *cfg, const char *name);
719:
720:
721: /** Returns the value of a section option, given a cfg_opt_t pointer.
722: * @param opt The option structure (eg, as returned from cfg_getopt())
723: * @param index Index of the value to get. Zero based.
724: * @see cfg_getnsec
725: */
726: DLLIMPORT cfg_t * __export cfg_opt_getnsec(cfg_opt_t *opt, unsigned int index);
727:
728: /** Indexed version of cfg_getsec(), used for sections with the
729: * CFGF_MULTI flag set.
730: *
731: * @param cfg The configuration file context.
732: * @param name The name of the option.
733: * @param index Index of the section to get. Zero based.
734: * @see cfg_getsec
735: */
736: DLLIMPORT cfg_t * __export cfg_getnsec(cfg_t *cfg, const char *name,
737: unsigned int index);
738:
739: /** Returns the value of a section option, given a cfg_opt_t pointer
740: * and the title.
741: * @param opt The option structure (eg, as returned from cfg_getopt())
742: * @param title The title of this section. The CFGF_TITLE flag must
743: * have been set for this option.
744: * @see cfg_gettsec
745: */
746: DLLIMPORT cfg_t * __export cfg_opt_gettsec(cfg_opt_t *opt, const char *title);
747:
748: /** Return a section given the title, used for section with the
749: * CFGF_TITLE flag set.
750: *
751: * @param cfg The configuration file context.
752: * @param name The name of the option.
753: * @param title The title of this section. The CFGF_TITLE flag must
754: * have been set for this option.
755: * @see cfg_getsec
756: */
757: DLLIMPORT cfg_t * __export cfg_gettsec(cfg_t *cfg, const char *name,
758: const char *title);
759:
760: /** Returns the value of a section option. The returned value is
761: * another cfg_t structure that can be used in following calls to
762: * cfg_getint, cfg_getstr or other get-functions.
763: * @param cfg The configuration file context.
764: * @param name The name of the option.
765: * @return The requested section is returned. If no section is found
766: * with that name, 0 is returned. There can only be default values for
767: * section without the CFGF_MULTI flag set. It is an error to try to
768: * get a section that isn't declared.
769: */
770: DLLIMPORT cfg_t * __export cfg_getsec(cfg_t *cfg, const char *name);
771:
772: /** Return the number of values this option has. If no default value
773: * is given for the option and no value was found in the config file,
774: * 0 will be returned (ie, the option value is not set at all).
775: * @param opt The option structure (eg, as returned from cfg_getopt())
776: */
777: DLLIMPORT unsigned int __export cfg_opt_size(cfg_opt_t *opt);
778:
779: /** Return the number of values this option has. If no default value
780: * is given for the option and no value was found in the config file,
781: * 0 will be returned (ie, the option value is not set at all).
782: *
783: * Note that there is no way to *not* specify a default value for integers,
784: * floats and booleans. Ie, they always have default values (since 0 or NULL is
785: * a valid integer/float/boolean value). Only strings and lists may have no
786: * default value.
787: *
788: * @param cfg The configuration file context.
789: * @param name The name of the option.
790: */
791: DLLIMPORT unsigned int __export cfg_size(cfg_t *cfg, const char *name);
792:
793: /** Return the title of a section.
794: *
795: * @param cfg The configuration file context.
796: * @return Returns the title, or 0 if there is no title. This string
797: * should not be modified.
798: */
799: DLLIMPORT const char * __export cfg_title(cfg_t *cfg);
800:
801: /** Return the name of a section.
802: *
803: * @param cfg The configuration file context.
804: * @return Returns the title, or 0 if there is no title. This string
805: * should not be modified.
806: */
807: DLLIMPORT const char * __export cfg_name(cfg_t *cfg);
808:
809: /** Return the name of an option.
810: *
811: * @param opt The option structure (eg, as returned from cfg_getopt())
812: * @return Returns the title, or 0 if there is no title. This string
813: * should not be modified.
814: */
815: DLLIMPORT const char * __export cfg_opt_name(cfg_opt_t *opt);
816:
817: /** Predefined include-function. This function can be used in the
818: * options passed to cfg_init() to specify a function for including
819: * other configuration files in the parsing. For example:
820: * CFG_FUNC("include", &cfg_include)
821: */
822: DLLIMPORT int __export cfg_include(cfg_t *cfg, cfg_opt_t *opt, int argc,
823: const char **argv);
824:
825: /** Does tilde expansion (~ -> $HOME) on the filename.
826: * @return The expanded filename is returned. If a ~user was not
827: * found, the original filename is returned. In any case, a
828: * dynamically allocated string is returned, which should be free()'d
829: * by the caller.
830: */
831: DLLIMPORT char * __export cfg_tilde_expand(const char *filename);
832:
833: /** Parse a boolean option string. Accepted "true" values are "true",
834: * "on" and "yes", and accepted "false" values are "false", "off" and
835: * "no".
836: *
837: * @return Returns 1 or 0 (true/false) if the string was parsed
838: * correctly, or -1 if an error occurred.
839: */
840: DLLIMPORT int __export cfg_parse_boolean(const char *s);
841:
842: /** Return an option given it's name.
843: *
844: * @param cfg The configuration file context.
845: * @param name The name of the option.
846: *
847: * @return Returns a pointer to the option. If the option isn't declared,
848: * libConfuse will print an error message and return 0.
849: */
850: DLLIMPORT cfg_opt_t * __export cfg_getopt(cfg_t *cfg, const char *name);
851:
852: /** Set an option (create an instance of an option).
853: *
854: * @param cfg The configuration file context.
855: * @param opt The option definition.
856: * @param value The initial value for the option.
857: *
858: * @return Returns a pointer to the value object.
859: */
860: DLLIMPORT cfg_value_t *cfg_setopt(cfg_t *cfg, cfg_opt_t *opt, char *value);
861:
862: /** Set a value of an integer option.
863: *
864: * @param opt The option structure (eg, as returned from cfg_getopt())
865: * @param value The value to set.
866: * @param index The index in the option value array that should be
867: * modified. It is an error to set values with indices larger than 0
868: * for options without the CFGF_LIST flag set.
869: */
870: DLLIMPORT void __export cfg_opt_setnint(cfg_opt_t *opt,
871: long int value, unsigned int index);
872:
873: /** Set the value of an integer option given its name.
874: *
875: * @param cfg The configuration file context.
876: * @param name The name of the option.
877: * @param value The value to set. If the option is a list (the CFGF_LIST flag
878: * is set), only the first value (with index 0) is set.
879: */
880: DLLIMPORT void __export cfg_setint(cfg_t *cfg, const char *name,
881: long int value);
882:
883: /** Set a value of an integer option given its name and index.
884: *
885: * @param cfg The configuration file context.
886: * @param name The name of the option.
887: * @param value The value to set.
888: * @param index The index in the option value array that should be
889: * modified. It is an error to set values with indices larger than 0
890: * for options without the CFGF_LIST flag set.
891: */
892: DLLIMPORT void __export cfg_setnint(cfg_t *cfg, const char *name,
893: long int value, unsigned int index);
894:
895: /** Set a value of a floating point option.
896: *
897: * @param opt The option structure (eg, as returned from cfg_getopt())
898: * @param value The value to set.
899: * @param index The index in the option value array that should be
900: * modified. It is an error to set values with indices larger than 0
901: * for options without the CFGF_LIST flag set.
902: */
903: DLLIMPORT void __export cfg_opt_setnfloat(cfg_opt_t *opt,
904: double value, unsigned int index);
905:
906: /** Set the value of a floating point option given its name.
907: *
908: * @param cfg The configuration file context.
909: * @param name The name of the option.
910: * @param value The value to set. If the option is a list (the CFGF_LIST flag
911: * is set), only the first value (with index 0) is set.
912: */
913: DLLIMPORT void __export cfg_setfloat(cfg_t *cfg, const char *name,
914: double value);
915:
916: /** Set a value of a floating point option given its name and index.
917: *
918: * @param cfg The configuration file context.
919: * @param name The name of the option.
920: * @param value The value to set.
921: * @param index The index in the option value array that should be
922: * modified. It is an error to set values with indices larger than 0
923: * for options without the CFGF_LIST flag set.
924: */
925: DLLIMPORT void __export cfg_setnfloat(cfg_t *cfg, const char *name,
926: double value, unsigned int index);
927:
928: /** Set a value of a boolean option.
929: *
930: * @param opt The option structure (eg, as returned from cfg_getopt())
931: * @param value The value to set.
932: * @param index The index in the option value array that should be
933: * modified. It is an error to set values with indices larger than 0
934: * for options without the CFGF_LIST flag set.
935: */
936: DLLIMPORT void __export cfg_opt_setnbool(cfg_opt_t *opt,
937: cfg_bool_t value, unsigned int index);
938:
939: /** Set the value of a boolean option given its name.
940: *
941: * @param cfg The configuration file context.
942: * @param name The name of the option.
943: * @param value The value to set. If the option is a list (the CFGF_LIST flag
944: * is set), only the first value (with index 0) is set.
945: */
946: DLLIMPORT void __export cfg_setbool(cfg_t *cfg, const char *name,
947: cfg_bool_t value);
948:
949: /** Set a value of a boolean option given its name and index.
950: *
951: * @param cfg The configuration file context.
952: * @param name The name of the option.
953: * @param value The value to set.
954: * @param index The index in the option value array that should be
955: * modified. It is an error to set values with indices larger than 0
956: * for options without the CFGF_LIST flag set.
957: */
958: DLLIMPORT void __export cfg_setnbool(cfg_t *cfg, const char *name,
959: cfg_bool_t value, unsigned int index);
960:
961: /** Set a value of a string option.
962: *
963: * @param opt The option structure (eg, as returned from cfg_getopt())
964: * @param value The value to set. Memory for the string is allocated
965: * and the value is copied. Any previous string value is freed.
966: * @param index The index in the option value array that should be
967: * modified. It is an error to set values with indices larger than 0
968: * for options without the CFGF_LIST flag set.
969: */
970: DLLIMPORT void __export cfg_opt_setnstr(cfg_opt_t *opt,
971: const char *value, unsigned int index);
972:
973: /** Set the value of a string option given its name.
974: *
975: * @param cfg The configuration file context.
976: * @param name The name of the option.
977: * @param value The value to set. Memory for the string is allocated and the
978: * value is copied. Any previous string value is freed. If the option is a list
979: * (the CFGF_LIST flag is set), only the first value (with index 0) is set.
980: */
981: DLLIMPORT void __export cfg_setstr(cfg_t *cfg, const char *name,
982: const char *value);
983:
984: /** Set a value of a boolean option given its name and index.
985: *
986: * @param cfg The configuration file context.
987: * @param name The name of the option.
988: * @param value The value to set. Memory for the string is allocated
989: * and the value is copied. Any privious string value is freed.
990: * @param index The index in the option value array that should be
991: * modified. It is an error to set values with indices larger than 0
992: * for options without the CFGF_LIST flag set.
993: */
994: DLLIMPORT void __export cfg_setnstr(cfg_t *cfg, const char *name,
995: const char *value, unsigned int index);
996:
997: /** Set values for a list option. All existing values are replaced
998: * with the new ones.
999: *
1000: * @param cfg The configuration file context.
1001: * @param name The name of the option.
1002: * @param nvalues Number of values to set.
1003: * @param ... The values to set, the type must match the type of the
1004: * option and the number of values must be equal to the nvalues
1005: * parameter.
1006: */
1007: DLLIMPORT void __export cfg_setlist(cfg_t *cfg, const char *name,
1008: unsigned int nvalues, ...);
1009:
1010: DLLIMPORT int __export cfg_numopts(cfg_opt_t *opts);
1011:
1012: /** Add values for a list option. The new values are appended to any
1013: * current values in the list.
1014: *
1015: * @param cfg The configuration file context.
1016: * @param name The name of the option.
1017: * @param nvalues Number of values to add.
1018: * @param ... The values to add, the type must match the type of the
1019: * option and the number of values must be equal to the nvalues
1020: * parameter.
1021: */
1022: DLLIMPORT void __export cfg_addlist(cfg_t *cfg, const char *name,
1023: unsigned int nvalues, ...);
1024:
1025: /** Default value print function.
1026: *
1027: * Print only the value of a given option. Does not handle sections or
1028: * functions. Use cfg_opt_print to print the whole assignment ("option
1029: * = value"), or cfg_print to print the whole config file.
1030: *
1031: * @param opt The option structure (eg, as returned from cfg_getopt())
1032: * @param index The index in the option value array that should be printed
1033: * @param fp File stream to print to.
1034: *
1035: * @see cfg_print, cfg_opt_print
1036: */
1037: DLLIMPORT void __export cfg_opt_nprint_var(cfg_opt_t *opt, unsigned int index,
1038: FILE *fp);
1039:
1040: /** Print an option and its value to a file.
1041: * Same as cfg_opt_print, but with the indentation level specified.
1042: * @see cfg_opt_print
1043: */
1044: DLLIMPORT void __export cfg_opt_print_indent(cfg_opt_t *opt, FILE *fp, int indent);
1045:
1046: /** Print an option and its value to a file.
1047: *
1048: * If a print callback function is specified for the option, it is
1049: * used instead of cfg_opt_nprint_var.
1050: *
1051: * @param opt The option structure (eg, as returned from cfg_getopt())
1052: * @param fp File stream to print to.
1053: *
1054: * @see cfg_print_func_t
1055: */
1056: DLLIMPORT void __export cfg_opt_print(cfg_opt_t *opt, FILE *fp);
1057:
1058: /** Print the options and values to a file.
1059: * Same as cfg_print, but with the indentation level specified.
1060: * @see cfg_print
1061: */
1062: DLLIMPORT void __export cfg_print_indent(cfg_t *cfg, FILE *fp, int indent);
1063:
1064: /** Print the options and values to a file.
1065: *
1066: * Note that options in any included file are expanded and printed
1067: * directly to the file. Option values given with environment
1068: * variables in the parsed input are also printed expanded. This means
1069: * that if you parse a configuration file you can't expect that the
1070: * output from this function is identical to the initial file.
1071: *
1072: * @param cfg The configuration file context.
1073: * @param fp File stream to print to, use stdout to print to the screen.
1074: *
1075: * @see cfg_print_func_t, cfg_set_print_func
1076: */
1077: DLLIMPORT void __export cfg_print(cfg_t *cfg, FILE *fp);
1078:
1079: /** Set a print callback function for an option.
1080: *
1081: * @param opt The option structure (eg, as returned from cfg_getopt())
1082: * @param pf The print function callback.
1083: *
1084: * @see cfg_print_func_t
1085: */
1086: DLLIMPORT cfg_print_func_t __export cfg_opt_set_print_func(cfg_opt_t *opt,
1087: cfg_print_func_t pf);
1088:
1089: /** Set a print callback function for an option given its name.
1090: *
1091: * @param cfg The configuration file context.
1092: * @param name The name of the option.
1093: * @param pf The print callback function.
1094: *
1095: * @see cfg_print_func_t
1096: */
1097: DLLIMPORT cfg_print_func_t __export cfg_set_print_func(cfg_t *cfg, const char *name,
1098: cfg_print_func_t pf);
1099:
1100: /** Register a validating callback function for an option.
1101: *
1102: * @param cfg The configuration file context.
1103: * @param name The name of the option.
1104: * @param vf The validating callback function.
1105: *
1106: * @see cfg_validate_callback_t
1107: */
1108: DLLIMPORT cfg_validate_callback_t __export cfg_set_validate_func(cfg_t *cfg,
1109: const char *name,
1110: cfg_validate_callback_t vf);
1111:
1112: #ifdef __cplusplus
1113: }
1114: #endif
1115:
1116: #endif
1117:
1118: /** @example ftpconf.c
1119: */
1120:
1121: /** @example simple.c
1122: */
1123:
1124: /** @example reread.c
1125: */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to confuse.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / confuse / src