1: /*
2: * Copyright (c) 2002-2017 Martin Hedenfalk <martin@bzero.se>
3: *
4: * Permission to use, copy, modify, and/or 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-2017 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 CONFUSE_H_
37: #define CONFUSE_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_STATIC
55: # define DLLIMPORT
56: # else /* ! BUILDING_STATIC */
57: # ifdef BUILDING_DLL
58: # define DLLIMPORT __declspec (dllexport)
59: # else /* ! BUILDING_DLL */
60: # define DLLIMPORT __declspec (dllimport)
61: # endif /* BUILDING_DLL */
62: # endif /* BUILDING_STATIC */
63: #else /* ! _WIN32 || __GNUC__ */
64: # define DLLIMPORT
65: #endif /* _WIN32 */
66:
67: #ifndef __BORLANDC__
68: # define __export
69: #endif
70:
71: /** Fundamental option types */
72: enum cfg_type_t {
73: CFGT_NONE,
74: CFGT_INT, /**< integer */
75: CFGT_FLOAT, /**< floating point number */
76: CFGT_STR, /**< string */
77: CFGT_BOOL, /**< boolean value */
78: CFGT_SEC, /**< section */
79: CFGT_FUNC, /**< function */
80: CFGT_PTR, /**< pointer to user-defined value */
81: CFGT_COMMENT /**< comment/annotation */
82: };
83: typedef enum cfg_type_t cfg_type_t;
84:
85: /** Flags. */
86: #define CFGF_NONE (0)
87: #define CFGF_MULTI (1 << 0) /**< option may be specified multiple times (only applies to sections) */
88: #define CFGF_LIST (1 << 1) /**< option is a list */
89: #define CFGF_NOCASE (1 << 2) /**< configuration file is case insensitive */
90: #define CFGF_TITLE (1 << 3) /**< option has a title (only applies to sections) */
91: #define CFGF_NODEFAULT (1 << 4) /**< option has no default value */
92: #define CFGF_NO_TITLE_DUPES (1 << 5) /**< multiple section titles must be unique
93: (duplicates raises an error, only applies to sections) */
94:
95: #define CFGF_RESET (1 << 6)
96: #define CFGF_DEFINIT (1 << 7)
97: #define CFGF_IGNORE_UNKNOWN (1 << 8) /**< ignore unknown options in configuration files */
98: #define CFGF_DEPRECATED (1 << 9) /**< option is deprecated and should be ignored. */
99: #define CFGF_DROP (1 << 10) /**< option should be dropped after parsing */
100: #define CFGF_COMMENTS (1 << 11) /**< Enable option annotation/comments support */
101: #define CFGF_MODIFIED (1 << 12) /**< option has been changed from its default value */
102: #define CFGF_KEYSTRVAL (1 << 13) /**< section has free-form key=value string options created when parsing file */
103:
104: /** Return codes from cfg_parse(), cfg_parse_boolean(), and cfg_set*() functions. */
105: #define CFG_SUCCESS 0
106: #define CFG_FAIL -1
107: #define CFG_FILE_ERROR -1
108: #define CFG_PARSE_ERROR 1
109:
110: typedef union cfg_value_t cfg_value_t;
111: typedef union cfg_simple_t cfg_simple_t;
112: typedef struct cfg_opt_t cfg_opt_t;
113: typedef struct cfg_t cfg_t;
114: typedef struct cfg_defvalue_t cfg_defvalue_t;
115: typedef int cfg_flag_t;
116: typedef struct cfg_searchpath_t cfg_searchpath_t;
117:
118: /** Function prototype used by CFGT_FUNC options.
119: *
120: * This is a callback function, registered with the CFG_FUNC
121: * initializer. Each time libConfuse finds a function, the registered
122: * callback function is called (parameters are passed as strings, any
123: * conversion to other types should be made in the callback
124: * function). libConfuse does not support any storage of the data
125: * found; these are passed as parameters to the callback, and it's the
126: * responsibility of the callback function to do whatever it should do
127: * with the data.
128: *
129: * @param cfg The configuration file context.
130: * @param opt The option.
131: * @param argc Number of arguments passed. The callback function is
132: * responsible for checking that the correct number of arguments are
133: * passed.
134: * @param argv Arguments as an array of character strings.
135: *
136: * @return On success, 0 should be returned. All other values
137: * indicates an error, and the parsing is aborted. The callback
138: * function should notify the error itself, for example by calling
139: * cfg_error().
140: *
141: * @see CFG_FUNC
142: */
143: typedef int (*cfg_func_t)(cfg_t *cfg, cfg_opt_t *opt, int argc, const char **argv);
144:
145: /** Function prototype used by the cfg_print_ functions.
146: *
147: * This callback function is used to print option values. For options
148: * with a value parsing callback, this is often required, especially
149: * if a string is mapped to an integer by the callback. This print
150: * callback must then map the integer back to the appropriate string.
151: *
152: * Except for functions, the print callback function should only print
153: * the value of the option, not the name and the equal sign (that is
154: * handled by the cfg_opt_print function). For function options
155: * however, the name and the parenthesis must be printed by this
156: * function. The value to print can be accessed with the cfg_opt_get
157: * functions.
158: *
159: * @param opt The option structure (eg, as returned from cfg_getopt())
160: * @param index Index of the value to get. Zero based.
161: * @param fp File stream to print to, use stdout to print to the screen.
162: *
163: * @see cfg_print, cfg_set_print_func
164: */
165: typedef void (*cfg_print_func_t)(cfg_opt_t *opt, unsigned int index, FILE *fp);
166:
167: /** Value parsing callback prototype
168: *
169: * This is a callback function (different from the one registered with the
170: * CFG_FUNC initializer) used to parse a value. This can be used to override
171: * the internal parsing of a value.
172: *
173: * Suppose you want an integer option that only can have certain values, for
174: * example 1, 2 and 3, and these should be written in the configuration file as
175: * "yes", "no" and "maybe". The callback function would be called with the
176: * found value ("yes", "no" or "maybe") as a string, and the result should be
177: * stored in the result parameter.
178: *
179: * @param cfg The configuration file context.
180: * @param opt The option.
181: * @param value The value found in the configuration file.
182: * @param result Pointer to storage for the result, cast to a void pointer.
183: *
184: * @return On success, 0 should be returned. All other values indicates an
185: * error, and the parsing is aborted. The callback function should notify the
186: * error itself, for example by calling cfg_error().
187: */
188: typedef int (*cfg_callback_t)(cfg_t *cfg, cfg_opt_t *opt, const char *value, void *result);
189:
190: /** Validating callback prototype
191: *
192: * This callback function is called after an option has been parsed and set.
193: * The function is called for both fundamental values (strings, integers etc)
194: * as well as lists and sections. This can for example be used to validate that
195: * all required options in a section has been set to sane values.
196: *
197: * @return On success, 0 should be returned. All other values indicates an
198: * error, and the parsing is aborted. The callback function should notify the
199: * error itself, for example by calling cfg_error().
200: *
201: * @see cfg_set_validate_func
202: */
203: typedef int (*cfg_validate_callback_t)(cfg_t *cfg, cfg_opt_t *opt);
204:
205: /** Validating callback2 prototype
206: *
207: * This callback function is called before an option is set using the
208: * cfg_set*() APIs. The function is called only for strings, integers,
209: * and floats. Compared to the regular callback function this takes a
210: * value pointer argument which must be casted before use, but can also
211: * be used to correct a value before it is set, e.g. when a too large
212: * value is set this can be used to set the MAX.
213: *
214: * @return On success, 0 should be returned. All other values indicates an
215: * error, and the cfg_set*() function will return without setting the value.
216: *
217: * @see cfg_set_validate_func2()
218: */
219: typedef int (*cfg_validate_callback2_t)(cfg_t *cfg, cfg_opt_t *opt, void *value);
220:
221: /** User-defined memory release function for CFG_PTR values
222: *
223: * This callback is used to free memory allocated in a value parsing callback
224: * function. Especially useful for CFG_PTR options, since libConfuse will not
225: * itself release such values. If the values are simply allocated with a
226: * malloc(3), one can use the standard free(3) function here.
227: *
228: */
229: typedef void (*cfg_free_func_t)(void *value);
230:
231: /** Boolean values. */
232: typedef enum { cfg_false, cfg_true } cfg_bool_t;
233:
234: /** Error reporting function. */
235: typedef void (*cfg_errfunc_t)(cfg_t *cfg, const char *fmt, va_list ap);
236:
237: /** Print filter function.
238: *
239: * @param cfg The configuration file context that opt belongs to.
240: * @param opt The configuration option that is about to be printed, or not.
241: * @return Zero if opt should be printed, non-zero if it should be filtered
242: * out.
243: *
244: * @see cfg_set_print_filter_func()
245: */
246: typedef int (*cfg_print_filter_func_t)(cfg_t *cfg, cfg_opt_t *opt);
247:
248: /** Data structure holding information about a "section". Sections can
249: * be nested. A section has a list of options (strings, numbers,
250: * booleans or other sections) grouped together.
251: */
252: struct cfg_t {
253: cfg_flag_t flags; /**< Any flags passed to cfg_init() */
254: char *name; /**< The name of this section, the root
255: * section returned from cfg_init() is
256: * always named "root" */
257: char *comment; /**< Optional annotation/comment */
258: cfg_opt_t *opts; /**< Array of options */
259: char *title; /**< Optional title for this section, only
260: * set if CFGF_TITLE flag is set */
261: char *filename; /**< Name of the file being parsed */
262: int line; /**< Line number in the config file */
263: cfg_errfunc_t errfunc; /**< This function (if set with
264: * cfg_set_error_function) is called for
265: * any error message. */
266: cfg_searchpath_t *path; /**< Linked list of directories to search */
267: cfg_print_filter_func_t pff; /**< Printing filter function */
268: };
269:
270: /** Data structure holding the value of a fundamental option value.
271: */
272: union cfg_value_t {
273: long int number; /**< integer value */
274: double fpnumber; /**< floating point value */
275: cfg_bool_t boolean; /**< boolean value */
276: char *string; /**< string value */
277: cfg_t *section; /**< section value */
278: void *ptr; /**< user-defined value */
279: };
280:
281: /** Data structure holding the pointer to a user provided variable
282: * defined with CFG_SIMPLE_*
283: */
284: union cfg_simple_t {
285: long int *number;
286: double *fpnumber;
287: cfg_bool_t *boolean;
288: char **string;
289: void **ptr;
290: };
291:
292: /** Data structure holding the default value given by the
293: * initialization macros.
294: */
295: struct cfg_defvalue_t {
296: long int number; /**< default integer value */
297: double fpnumber; /**< default floating point value */
298: cfg_bool_t boolean; /**< default boolean value */
299: const char *string; /**< default string value */
300: char *parsed; /**< default value that is parsed by
301: * libConfuse, used for lists and
302: * functions */
303: };
304:
305: /** Data structure holding information about an option. The value(s)
306: * are stored as an array of fundamental values (strings, numbers,
307: * etc).
308: */
309: struct cfg_opt_t {
310: const char *name; /**< The name of the option */
311: char *comment; /**< Optional comment/annotation */
312: cfg_type_t type; /**< Type of option */
313: unsigned int nvalues; /**< Number of values parsed */
314: cfg_value_t **values; /**< Array of found values */
315: cfg_flag_t flags; /**< Flags */
316: cfg_opt_t *subopts; /**< Suboptions (only applies to sections) */
317: cfg_defvalue_t def; /**< Default value */
318: cfg_func_t func; /**< Function callback for CFGT_FUNC options */
319: cfg_simple_t simple_value; /**< Pointer to user-specified variable to
320: * store simple values (created with the
321: * CFG_SIMPLE_* initializers) */
322: cfg_callback_t parsecb; /**< Value parsing callback function */
323: cfg_validate_callback_t validcb; /**< Value validating parsing callback function */
324: cfg_validate_callback2_t validcb2; /**< Value validating set callback function */
325: cfg_print_func_t pf; /**< print callback function */
326: cfg_free_func_t freecb; /***< user-defined memory release function */
327: };
328:
329: extern const char __export confuse_copyright[];
330: extern const char __export confuse_version[];
331: extern const char __export confuse_author[];
332:
333: #define __CFG_STR(name, def, flags, svalue, cb) \
334: {name,0,CFGT_STR,0,0,flags,0,{0,0,cfg_false,def,0},0,{.string=svalue},cb,0,0,0,0}
335: #define __CFG_STR_LIST(name, def, flags, svalue, cb) \
336: {name,0,CFGT_STR,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,{.string=svalue},cb,0,0,0,0}
337:
338: /** Initialize a string option
339: */
340: #define CFG_STR(name, def, flags) \
341: __CFG_STR(name, def, flags, 0, 0)
342:
343: /** Initialize a string list option
344: */
345: #define CFG_STR_LIST(name, def, flags) \
346: __CFG_STR_LIST(name, def, flags, 0, 0)
347:
348: /** Initialize a string option with a value parsing callback
349: */
350: #define CFG_STR_CB(name, def, flags, cb) \
351: __CFG_STR(name, def, flags, 0, cb)
352:
353: /** Initialize a string list option with a value parsing callback
354: */
355: #define CFG_STR_LIST_CB(name, def, flags, cb) \
356: __CFG_STR_LIST(name, def, flags, 0, cb)
357:
358: /** Initialize a "simple" string option.
359: *
360: * "Simple" options (in lack of a better expression) does not support
361: * lists of values or multiple sections. LibConfuse will store the
362: * value of a simple option in the user-defined location specified by
363: * the value parameter in the initializer. Simple options are not
364: * stored in the cfg_t context, only a pointer. Sections can not be
365: * initialized as a "simple" option.
366: *
367: * As of version 2.2, libConfuse can now return the values of simple
368: * options with the cfg_get functions. This allows using the new
369: * cfg_print function with simple options.
370: *
371: * libConfuse doesn't support handling default values for "simple"
372: * options. They are assumed to be set by the calling application
373: * before cfg_parse is called.
374: *
375: * @param name name of the option
376: * @param svalue pointer to a character pointer (a char **). This value
377: * must be initalized either to NULL or to a malloc()'ed string. You
378: * can't use
379: * <pre>
380: * char *user = "joe";
381: * ...
382: * cfg_opt_t opts[] = {
383: * CFG_SIMPLE_STR("user", &user),
384: * ...
385: * </pre>
386: * since libConfuse will try to free the static string "joe" (which is
387: * an error) when a "user" option is found. Rather, use the following
388: * code snippet:
389: * <pre>
390: * char *user = strdup("joe");
391: * ...
392: * cfg_opt_t opts[] = {
393: * CFG_SIMPLE_STR("user", &user),
394: * ...
395: * </pre>
396: * Alternatively, the default value can be set after the opts struct
397: * is defined, as in:
398: * <pre>
399: * char *user = 0;
400: * ...
401: * cfg_opt_t opts[] = {
402: * CFG_SIMPLE_STR("user", &user),
403: * ...
404: * user = strdup("joe");
405: * cfg = cfg_init(opts, 0);
406: * cfg_parse(cfg, filename);
407: * </pre>
408: *
409: */
410: #define CFG_SIMPLE_STR(name, svalue) \
411: __CFG_STR(name, 0, CFGF_NONE, svalue, 0)
412:
413:
414: #define __CFG_INT(name, def, flags, svalue, cb) \
415: {name,0,CFGT_INT,0,0,flags,0,{def,0,cfg_false,0,0},0,{.number=svalue},cb,0,0,0,0}
416: #define __CFG_INT_LIST(name, def, flags, svalue, cb) \
417: {name,0,CFGT_INT,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,{.number=svalue},cb,0,0,0,0}
418:
419: /** Initialize an integer option
420: */
421: #define CFG_INT(name, def, flags) \
422: __CFG_INT(name, def, flags, 0, 0)
423:
424: /** Initialize an integer list option
425: */
426: #define CFG_INT_LIST(name, def, flags) \
427: __CFG_INT_LIST(name, def, flags, 0, 0)
428:
429: /** Initialize an integer option with a value parsing callback
430: */
431: #define CFG_INT_CB(name, def, flags, cb) \
432: __CFG_INT(name, def, flags, 0, cb)
433:
434: /** Initialize an integer list option with a value parsing callback
435: */
436: #define CFG_INT_LIST_CB(name, def, flags, cb) \
437: __CFG_INT_LIST(name, def, flags, 0, cb)
438:
439: /** Initialize a "simple" integer option (see documentation for
440: * CFG_SIMPLE_STR for more information).
441: * Note that confuse uses long integers, so make sure that any pointer
442: * you provide for svalue points to a long int rather than a normal int.
443: * Otherwise, you will have strange problems on 64-bit architectures.
444: */
445: #define CFG_SIMPLE_INT(name, svalue) \
446: __CFG_INT(name, 0, CFGF_NONE, svalue, 0)
447:
448:
449:
450: #define __CFG_FLOAT(name, def, flags, svalue, cb) \
451: {name,0,CFGT_FLOAT,0,0,flags,0,{0,def,cfg_false,0,0},0,{.fpnumber=svalue},cb,0,0,0,0}
452: #define __CFG_FLOAT_LIST(name, def, flags, svalue, cb) \
453: {name,0,CFGT_FLOAT,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,{.fpnumber=svalue},cb,0,0,0,0}
454:
455: /** Initialize a floating point option
456: */
457: #define CFG_FLOAT(name, def, flags) \
458: __CFG_FLOAT(name, def, flags, 0, 0)
459:
460: /** Initialize a floating point list option
461: */
462: #define CFG_FLOAT_LIST(name, def, flags) \
463: __CFG_FLOAT_LIST(name, def, flags, 0, 0)
464:
465: /** Initialize a floating point option with a value parsing callback
466: */
467: #define CFG_FLOAT_CB(name, def, flags, cb) \
468: __CFG_FLOAT(name, def, flags, 0, cb)
469:
470: /** Initialize a floating point list option with a value parsing callback
471: */
472: #define CFG_FLOAT_LIST_CB(name, def, flags, cb) \
473: __CFG_FLOAT_LIST(name, def, flags, 0, cb)
474:
475: /** Initialize a "simple" floating point option (see documentation for
476: * CFG_SIMPLE_STR for more information).
477: */
478: #define CFG_SIMPLE_FLOAT(name, svalue) \
479: __CFG_FLOAT(name, 0, CFGF_NONE, svalue, 0)
480:
481:
482:
483: #define __CFG_BOOL(name, def, flags, svalue, cb) \
484: {name,0,CFGT_BOOL,0,0,flags,0,{0,0,def,0,0},0,{.boolean=svalue},cb,0,0,0,0}
485: #define __CFG_BOOL_LIST(name, def, flags, svalue, cb) \
486: {name,0,CFGT_BOOL,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,{.boolean=svalue},cb,0,0,0,0}
487:
488: /** Initialize a boolean option
489: */
490: #define CFG_BOOL(name, def, flags) \
491: __CFG_BOOL(name, def, flags, 0, 0)
492:
493: /** Initialize a boolean list option
494: */
495: #define CFG_BOOL_LIST(name, def, flags) \
496: __CFG_BOOL_LIST(name, def, flags, 0, 0)
497:
498: /** Initialize a boolean option with a value parsing callback
499: */
500: #define CFG_BOOL_CB(name, def, flags, cb) \
501: __CFG_BOOL(name, def, flags, 0, cb)
502:
503: /** Initialize a boolean list option with a value parsing callback
504: */
505: #define CFG_BOOL_LIST_CB(name, def, flags, cb) \
506: __CFG_BOOL_LIST(name, def, flags, 0, cb)
507:
508: /** Initialize a "simple" boolean option (see documentation for
509: * CFG_SIMPLE_STR for more information).
510: */
511: #define CFG_SIMPLE_BOOL(name, svalue) \
512: __CFG_BOOL(name, cfg_false, CFGF_NONE, svalue, 0)
513:
514:
515:
516: /** Initialize a section
517: *
518: * @param name The name of the option
519: * @param opts Array of options that are valid within this section
520:
521: * @param flags Flags, specify CFGF_MULTI if it should be possible to
522: * have multiples of the same section, and CFGF_TITLE if the
523: * section(s) must have a title (which can be used in the
524: * cfg_gettsec() function)
525: *
526: */
527: #define CFG_SEC(name, opts, flags) \
528: {name,0,CFGT_SEC,0,0,flags,opts,{0,0,cfg_false,0,0},0,{0},0,0,0,0,0}
529:
530:
531:
532: /** Initialize a function
533: * @param name The name of the option
534: * @param func The callback function.
535: *
536: * @see cfg_func_t
537: */
538: #define CFG_FUNC(name, func) \
539: {name,0,CFGT_FUNC,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},func,{0},0,0,0,0,0}
540:
541:
542: #define __CFG_PTR(name, def, flags, svalue, parsecb, freecb) \
543: {name,0,CFGT_PTR,0,0,flags,0,{0,0,cfg_false,0,def},0,{.ptr=svalue},parsecb,0,0,0,freecb}
544: #define __CFG_PTR_LIST(name, def, flags, svalue, parsecb, freecb) \
545: {name,0,CFGT_PTR,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,{.ptr=svalue},parsecb,0,0,0,freecb}
546:
547: /** Initialize a user-defined option
548: *
549: * CFG_PTR options can only be used together with a value parsing callback.
550: *
551: * @param name The name of the option
552: * @param def Default value
553: * @param flags Flags
554: * @param parsecb Value parsing callback
555: * @param freecb Memory release function
556: *
557: * @see cfg_callback_t, cfg_free_func_t
558: */
559: #define CFG_PTR_CB(name, def, flags, parsecb, freecb) \
560: __CFG_PTR(name, def, flags, 0, parsecb, freecb)
561:
562: /** Initialize a list of user-defined options
563: */
564: #define CFG_PTR_LIST_CB(name, def, flags, parsecb, freecb) \
565: __CFG_PTR(name, def, flags | CFGF_LIST, 0, parsecb, freecb)
566:
567: /*#define CFG_SIMPLE_PTR(name, svalue, cb) \
568: __CFG_PTR(name, 0, 0, svalue, cb)*/
569:
570:
571: /** Terminate list of options. This must be the last initializer in
572: * the option list.
573: */
574: #define CFG_END() \
575: {0,0,CFGT_NONE,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},0,{0},0,0,0,0,0}
576:
577:
578:
579: /** Create and initialize a cfg_t structure. This should be the first function
580: * called when setting up the parsing of a configuration file. The options
581: * passed in the first parameter is initialized using the CFG_* initializers.
582: * The last option in the option array must be CFG_END(), unless you like
583: * segmentation faults.
584: *
585: * The options must no longer be defined in the same scope as where the cfg_xxx
586: * functions are used (since version 2.3).
587: *
588: * CFGF_IGNORE_UNKNOWN can be specified to use the "__unknown" option
589: * whenever an unknown option is parsed. Be sure to define an "__unknown"
590: * option in each scope that unknown parameters are allowed.
591: *
592: * Call setlocale() before calling this function to localize handling of
593: * types, LC_CTYPE, and messages, LC_MESSAGES, since version 2.9:
594: * <pre>
595: * setlocale(LC_MESSAGES, "");
596: * setlocale(LC_CTYPE, "");
597: * </pre>
598: * @param opts An arrary of options
599: * @param flags One or more flags (bitwise or'ed together). Currently only
600: * CFGF_NOCASE and CFGF_IGNORE_UNKNOWN are available. Use 0 if no flags are
601: * needed.
602: *
603: * @return A configuration context structure. This pointer is passed
604: * to almost all other functions as the first parameter.
605: */
606: DLLIMPORT cfg_t *__export cfg_init(cfg_opt_t *opts, cfg_flag_t flags);
607:
608: /** Add a searchpath directory to the configuration context, the
609: * const char* argument will be duplicated and then freed as part
610: * of the usual context takedown.
611: *
612: * All directories added to the context in this manner will be searched
613: * for the file specified in cfg_parse(), and for those included.
614: * All directories added with this function will be "tilde expanded".
615: * Note that the current directory is not added to the searchpath
616: * by default.
617: *
618: * @param cfg The configuration file context as returned from cfg_init().
619: * @param dir Directory to be added to the search path.
620: *
621: * @return On success, CFG_SUCCESS, on failure (which can only be
622: * caused by a failed malloc()), CFG_PARSE_ERROR.
623: */
624: DLLIMPORT int __export cfg_add_searchpath(cfg_t *cfg, const char *dir);
625:
626: /** Search the linked-list of cfg_searchpath_t for the specified
627: * file. If not NULL, the return value is freshly allocated and
628: * and should be freed by the caller.
629: *
630: * @param path The linked list of cfg_searchpath_t structs, each
631: * containg a directory to be searched
632: * @param file The file for which to search
633: *
634: * @return If the file is found on the searchpath then the full
635: * path to the file is returned. If not found, NULL is returned.
636: */
637: DLLIMPORT char *__export cfg_searchpath(cfg_searchpath_t *path, const char *file);
638:
639: /** Parse a configuration file. Tilde expansion is performed on the
640: * filename before it is opened. After a configuration file has been
641: * initialized (with cfg_init()) and parsed (with cfg_parse()), the
642: * values can be read with the cfg_getXXX functions.
643: *
644: * @param cfg The configuration file context as returned from cfg_init().
645: * @param filename The name of the file to parse.
646: *
647: * @return On success, CFG_SUCCESS is returned. If the file couldn't
648: * be opened for reading, CFG_FILE_ERROR is returned. On all other
649: * errors, CFG_PARSE_ERROR is returned and cfg_error() was called with
650: * a descriptive error message.
651: */
652: DLLIMPORT int __export cfg_parse(cfg_t *cfg, const char *filename);
653:
654: /** Same as cfg_parse() above, but takes an already opened file as
655: * argument. Reading begins at the current position. After parsing,
656: * the position is not reset. The caller is responsible for closing
657: * the file.
658: *
659: * @param cfg The configuration file context as returned from cfg_init().
660: * @param fp An open file stream.
661: *
662: * @see cfg_parse()
663: *
664: * @return POSIX OK(0), or non-zero on failure.
665: */
666: DLLIMPORT int __export cfg_parse_fp(cfg_t *cfg, FILE *fp);
667:
668: /** Same as cfg_parse() above, but takes a character buffer as
669: * argument.
670: *
671: * @param cfg The configuration file context as returned from cfg_init().
672: * @param buf A zero-terminated string with configuration directives.
673: *
674: * @see cfg_parse()
675: *
676: * @return POSIX OK(0), or non-zero on failure.
677: */
678: DLLIMPORT int __export cfg_parse_buf(cfg_t *cfg, const char *buf);
679:
680: /** Free the memory allocated for the values of a given option. Only
681: * the values are freed, not the option itself (it is freed by cfg_free()).
682: *
683: * @see cfg_free()
684: *
685: * @return POSIX OK(0), or non-zero on failure.
686: */
687: DLLIMPORT int __export cfg_free_value(cfg_opt_t *opt);
688:
689: /** Free a cfg_t context. All memory allocated by the cfg_t context
690: * structure are freed, and can't be used in any further cfg_* calls.
691: *
692: * @return POSIX OK(0), or non-zero on failure.
693: */
694: DLLIMPORT int __export cfg_free(cfg_t *cfg);
695:
696: /** Install a user-defined error reporting function.
697: * @return The old error reporting function is returned.
698: */
699: DLLIMPORT cfg_errfunc_t __export cfg_set_error_function(cfg_t *cfg, cfg_errfunc_t errfunc);
700:
701: /** Show a parser error. Any user-defined error reporting function is called.
702: * @see cfg_set_error_function
703: */
704: DLLIMPORT void __export cfg_error(cfg_t *cfg, const char *fmt, ...);
705:
706: /** Returns the option comment
707: * @param opt The option structure (eg, as returned from cfg_getopt())
708: * @see cfg_getcomment
709: */
710: DLLIMPORT char * __export cfg_opt_getcomment(cfg_opt_t *opt);
711:
712: /** Returns the option comment
713: *
714: * This function can be used to extract option annotations from a config
715: * file. Only comments preceding the option are read by cfg_parse().
716: *
717: * @param cfg The configuration file context.
718: * @param name The name of the option.
719: * @see cfg_setcomment
720: * @return The comment for this option, or NULL if unset
721: */
722: DLLIMPORT char * __export cfg_getcomment(cfg_t *cfg, const char *name);
723:
724: /** Returns the value of an integer option, given a cfg_opt_t pointer.
725: * @param opt The option structure (eg, as returned from cfg_getopt())
726: * @param index Index of the value to get. Zero based.
727: * @see cfg_getnint
728: */
729: DLLIMPORT signed long __export cfg_opt_getnint(cfg_opt_t *opt, unsigned int index);
730:
731: /** Indexed version of cfg_getint(), used for lists.
732: * @param cfg The configuration file context.
733: * @param name The name of the option.
734: * @param index Index of the value to get. Zero based.
735: * @see cfg_getint
736: */
737: DLLIMPORT long int __export cfg_getnint(cfg_t *cfg, const char *name, unsigned int index);
738:
739: /** Returns the value of an integer option. This is the same as
740: * calling cfg_getnint with index 0.
741: * @param cfg The configuration file context.
742: * @param name The name of the option.
743: * @return The requested value is returned. If the option was not set
744: * in the configuration file, the default value given in the
745: * corresponding cfg_opt_t structure is returned. It is an error to
746: * try to get an option that isn't declared.
747: */
748: DLLIMPORT long int __export cfg_getint(cfg_t *cfg, const char *name);
749:
750: /** Returns the value of a floating point option, given a cfg_opt_t pointer.
751: * @param opt The option structure (eg, as returned from cfg_getopt())
752: * @param index Index of the value to get. Zero based.
753: * @see cfg_getnfloat
754: */
755: DLLIMPORT double __export cfg_opt_getnfloat(cfg_opt_t *opt, unsigned int index);
756:
757: /** Indexed version of cfg_getfloat(), used for lists.
758: * @param cfg The configuration file context.
759: * @param name The name of the option.
760: * @param index Index of the value to get. Zero based.
761: * @see cfg_getfloat
762: */
763: DLLIMPORT double __export cfg_getnfloat(cfg_t *cfg, const char *name, unsigned int index);
764:
765: /** Returns the value of a floating point option.
766: * @param cfg The configuration file context.
767: * @param name The name of the option.
768: * @return The requested value is returned. If the option was not set
769: * in the configuration file, the default value given in the
770: * corresponding cfg_opt_t structure is returned. It is an error to
771: * try to get an option that isn't declared.
772: */
773: DLLIMPORT double __export cfg_getfloat(cfg_t *cfg, const char *name);
774:
775: /** Returns the value of a string option, given a cfg_opt_t pointer.
776: * @param opt The option structure (eg, as returned from cfg_getopt())
777: * @param index Index of the value to get. Zero based.
778: * @see cfg_getnstr
779: */
780: DLLIMPORT char *__export cfg_opt_getnstr(cfg_opt_t *opt, unsigned int index);
781:
782: /** Indexed version of cfg_getstr(), used for lists.
783: * @param cfg The configuration file context.
784: * @param name The name of the option.
785: * @param index Index of the value to get. Zero based.
786: * @see cfg_getstr
787: */
788: DLLIMPORT char *__export cfg_getnstr(cfg_t *cfg, const char *name, unsigned int index);
789:
790: /** Returns the value of a string option.
791: * @param cfg The configuration file context.
792: * @param name The name of the option.
793: * @return The requested value is returned. If the option was not set
794: * in the configuration file, the default value given in the
795: * corresponding cfg_opt_t structure is returned. It is an error to
796: * try to get an option that isn't declared.
797: */
798: DLLIMPORT char *__export cfg_getstr(cfg_t *cfg, const char *name);
799:
800: /** Returns the value of a boolean option, given a cfg_opt_t pointer.
801: * @param opt The option structure (eg, as returned from cfg_getopt())
802: * @param index Index of the value to get. Zero based.
803: * @see cfg_getnbool
804: */
805: DLLIMPORT cfg_bool_t __export cfg_opt_getnbool(cfg_opt_t *opt, unsigned int index);
806:
807: /** Indexed version of cfg_getbool(), used for lists.
808: *
809: * @param cfg The configuration file context.
810: * @param name The name of the option.
811: * @param index Index of the value to get. Zero based.
812: * @see cfg_getbool
813: */
814: DLLIMPORT cfg_bool_t __export cfg_getnbool(cfg_t *cfg, const char *name, unsigned int index);
815:
816: /** Returns the value of a boolean option.
817: * @param cfg The configuration file context.
818: * @param name The name of the option.
819: * @return The requested value is returned. If the option was not set
820: * in the configuration file, the default value given in the
821: * corresponding cfg_opt_t structure is returned. It is an error to
822: * try to get an option that isn't declared.
823: */
824: DLLIMPORT cfg_bool_t __export cfg_getbool(cfg_t *cfg, const char *name);
825:
826:
827: DLLIMPORT void *__export cfg_opt_getnptr(cfg_opt_t *opt, unsigned int index);
828: DLLIMPORT void *__export cfg_getnptr(cfg_t *cfg, const char *name, unsigned int indx);
829:
830: /** Returns the value of a user-defined option (void pointer).
831: * @param cfg The configuration file context.
832: * @param name The name of the option.
833: * @return The requested value is returned. If the option was not set
834: * in the configuration file, the default value given in the
835: * corresponding cfg_opt_t structure is returned. It is an error to
836: * try to get an option that isn't declared.
837: */
838: DLLIMPORT void *__export cfg_getptr(cfg_t *cfg, const char *name);
839:
840:
841: /** Returns the value of a section option, given a cfg_opt_t pointer.
842: * @param opt The option structure (eg, as returned from cfg_getopt())
843: * @param index Index of the value to get. Zero based.
844: * @see cfg_getnsec
845: */
846: DLLIMPORT cfg_t *__export cfg_opt_getnsec(cfg_opt_t *opt, unsigned int index);
847:
848: /** Indexed version of cfg_getsec(), used for sections with the
849: * CFGF_MULTI flag set.
850: *
851: * @param cfg The configuration file context.
852: * @param name The name of the option.
853: * @param index Index of the section to get. Zero based.
854: * @see cfg_getsec
855: */
856: DLLIMPORT cfg_t *__export cfg_getnsec(cfg_t *cfg, const char *name, unsigned int index);
857:
858: /** Returns the value of a section option, given a cfg_opt_t pointer
859: * and the title.
860: * @param opt The option structure (eg, as returned from cfg_getopt())
861: * @param title The title of this section. The CFGF_TITLE flag must
862: * have been set for this option.
863: * @see cfg_gettsec
864: */
865: DLLIMPORT cfg_t *__export cfg_opt_gettsec(cfg_opt_t *opt, const char *title);
866:
867: /** Return a section given the title, used for section with the
868: * CFGF_TITLE flag set.
869: *
870: * @param cfg The configuration file context.
871: * @param name The name of the option.
872: * @param title The title of this section. The CFGF_TITLE flag must
873: * have been set for this option.
874: * @see cfg_getsec
875: */
876: DLLIMPORT cfg_t *__export cfg_gettsec(cfg_t *cfg, const char *name, const char *title);
877:
878: /** Returns the value of a section option. The returned value is
879: * another cfg_t structure that can be used in following calls to
880: * cfg_getint, cfg_getstr or other get-functions.
881: * @param cfg The configuration file context.
882: * @param name The name of the option.
883: * @return The requested section is returned. If no section is found
884: * with that name, 0 is returned. There can only be default values for
885: * section without the CFGF_MULTI flag set. It is an error to try to
886: * get a section that isn't declared.
887: */
888: DLLIMPORT cfg_t *__export cfg_getsec(cfg_t *cfg, const char *name);
889:
890: /** Return the number of values this option has. If no default value
891: * is given for the option and no value was found in the config file,
892: * 0 will be returned (ie, the option value is not set at all).
893: * @param opt The option structure (eg, as returned from cfg_getopt())
894: */
895: DLLIMPORT unsigned int __export cfg_opt_size(cfg_opt_t *opt);
896:
897: /** Return the number of values this option has. If no default value
898: * is given for the option and no value was found in the config file,
899: * 0 will be returned (ie, the option value is not set at all).
900: *
901: * Note that there is no way to *not* specify a default value for integers,
902: * floats and booleans. Ie, they always have default values (since 0 or NULL is
903: * a valid integer/float/boolean value). Only strings and lists may have no
904: * default value.
905: *
906: * @param cfg The configuration file context.
907: * @param name The name of the option.
908: */
909: DLLIMPORT unsigned int __export cfg_size(cfg_t *cfg, const char *name);
910:
911: /** Return the title of a section.
912: *
913: * @param cfg The configuration file context.
914: * @return Returns the title, or 0 if there is no title. This string
915: * should not be modified.
916: */
917: DLLIMPORT const char *__export cfg_title(cfg_t *cfg);
918:
919: /** Return the name of a section.
920: *
921: * @param cfg The configuration file context.
922: * @return Returns the title, or 0 if there is no title. This string
923: * should not be modified.
924: */
925: DLLIMPORT const char *__export cfg_name(cfg_t *cfg);
926:
927: /** Return the name of an option.
928: *
929: * @param opt The option structure (eg, as returned from cfg_getopt())
930: * @return Returns the title, or 0 if there is no title. This string
931: * should not be modified.
932: */
933: DLLIMPORT const char *__export cfg_opt_name(cfg_opt_t *opt);
934:
935: /** Return the string value of a key=value pair
936: *
937: * @param opt The option structure (eg, as returned from cfg_getnopt())
938: * @see cfg_opt_name
939: * @return The string value for the option, or NULL if it's not a
940: * string. This string must not be modified!
941: */
942: DLLIMPORT const char *cfg_opt_getstr(cfg_opt_t *opt);
943:
944: /** Predefined include-function. This function can be used in the
945: * options passed to cfg_init() to specify a function for including
946: * other configuration files in the parsing. For example:
947: * CFG_FUNC("include", &cfg_include)
948: */
949: DLLIMPORT int __export cfg_include(cfg_t *cfg, cfg_opt_t *opt, int argc, const char **argv);
950:
951: /** Does tilde expansion (~ -> $HOME) on the filename.
952: * @return The expanded filename is returned. If a ~user was not
953: * found, the original filename is returned. In any case, a
954: * dynamically allocated string is returned, which should be free()'d
955: * by the caller.
956: */
957: DLLIMPORT char *__export cfg_tilde_expand(const char *filename);
958:
959: /** Parse a boolean option string. Accepted "true" values are "true",
960: * "on" and "yes", and accepted "false" values are "false", "off" and
961: * "no".
962: *
963: * @return Returns 1 or 0 (true/false) if the string was parsed
964: * correctly, or -1 if an error occurred.
965: */
966: DLLIMPORT int __export cfg_parse_boolean(const char *s);
967:
968: /** Return the nth option in a file or section
969: *
970: * @param cfg The configuration file or section context
971: * @param index Option index
972: * @see cfg_num
973: */
974: DLLIMPORT cfg_opt_t *cfg_getnopt(cfg_t *cfg, unsigned int index);
975:
976: /** Return an option given it's name.
977: *
978: * @param cfg The configuration file context.
979: * @param name The name of the option.
980: *
981: * @return Returns a pointer to the option. If the option isn't declared,
982: * libConfuse will print an error message and return 0.
983: */
984: DLLIMPORT cfg_opt_t *__export cfg_getopt(cfg_t *cfg, const char *name);
985:
986: /** Set an option (create an instance of an option).
987: *
988: * @param cfg The configuration file context.
989: * @param opt The option definition.
990: * @param value The initial value for the option.
991: *
992: * @return Returns a pointer to the value object.
993: */
994: DLLIMPORT cfg_value_t *cfg_setopt(cfg_t *cfg, cfg_opt_t *opt, const char *value);
995:
996: /** Annotate an option
997: * @param opt The option structure (eg, as returned from cfg_getopt())
998: * @param comment The annotation
999: * @see cfg_setcomment
1000: * @return POSIX OK(0), or non-zero on failure.
1001: */
1002: DLLIMPORT int __export cfg_opt_setcomment(cfg_opt_t *opt, char *comment);
1003:
1004: /** Annotate an option given its name
1005: *
1006: * All options can be annotated as long as the CFGF_COMMENTS flag is
1007: * given to cfg_init().
1008: *
1009: * When calling cfg_print(), annotations are saved as a C style one-liner
1010: * comment before each option.
1011: *
1012: * When calling cfg_parse(), only one-liner comments preceding an option
1013: * are read and used to annotate the option.
1014: *
1015: * @param cfg The configuration file context.
1016: * @param name The name of the option.
1017: * @param comment The annotation
1018: *
1019: * @return POSIX OK(0), or non-zero on failure. This function will fail
1020: * if memory for the new comment cannot be allocated.
1021: */
1022: DLLIMPORT int __export cfg_setcomment(cfg_t *cfg, const char *name, char *comment);
1023:
1024: /** Set a value of an integer option.
1025: *
1026: * @param opt The option structure (eg, as returned from cfg_getopt())
1027: * @param value The value to set.
1028: * @param index The index in the option value array that should be
1029: * modified. It is an error to set values with indices larger than 0
1030: * for options without the CFGF_LIST flag set.
1031: *
1032: * @return POSIX OK(0), or non-zero on failure.
1033: */
1034: DLLIMPORT int __export cfg_opt_setnint(cfg_opt_t *opt, long int value, unsigned int index);
1035:
1036: /** Set the value of an integer option given its name.
1037: *
1038: * @param cfg The configuration file context.
1039: * @param name The name of the option.
1040: * @param value The value to set. If the option is a list (the CFGF_LIST flag
1041: * is set), only the first value (with index 0) is set.
1042: *
1043: * @return POSIX OK(0), or non-zero on failure.
1044: */
1045: DLLIMPORT int __export cfg_setint(cfg_t *cfg, const char *name, long int value);
1046:
1047: /** Set a value of an integer option given its name and index.
1048: *
1049: * @param cfg The configuration file context.
1050: * @param name The name of the option.
1051: * @param value The value to set.
1052: * @param index The index in the option value array that should be
1053: * modified. It is an error to set values with indices larger than 0
1054: * for options without the CFGF_LIST flag set.
1055: *
1056: * @return POSIX OK(0), or non-zero on failure.
1057: */
1058: DLLIMPORT int __export cfg_setnint(cfg_t *cfg, const char *name, long int value, unsigned int index);
1059:
1060: /** Set a value of a floating point option.
1061: *
1062: * @param opt The option structure (eg, as returned from cfg_getopt())
1063: * @param value The value to set.
1064: * @param index The index in the option value array that should be
1065: * modified. It is an error to set values with indices larger than 0
1066: * for options without the CFGF_LIST flag set.
1067: *
1068: * @return POSIX OK(0), or non-zero on failure.
1069: */
1070: DLLIMPORT int __export cfg_opt_setnfloat(cfg_opt_t *opt, double value, unsigned int index);
1071:
1072: /** Set the value of a floating point option given its name.
1073: *
1074: * @param cfg The configuration file context.
1075: * @param name The name of the option.
1076: * @param value The value to set. If the option is a list (the CFGF_LIST flag
1077: * is set), only the first value (with index 0) is set.
1078: *
1079: * @return POSIX OK(0), or non-zero on failure.
1080: */
1081: DLLIMPORT int __export cfg_setfloat(cfg_t *cfg, const char *name, double value);
1082:
1083: /** Set a value of a floating point option given its name and index.
1084: *
1085: * @param cfg The configuration file context.
1086: * @param name The name of the option.
1087: * @param value The value to set.
1088: * @param index The index in the option value array that should be
1089: * modified. It is an error to set values with indices larger than 0
1090: * for options without the CFGF_LIST flag set.
1091: *
1092: * @return POSIX OK(0), or non-zero on failure.
1093: */
1094: DLLIMPORT int __export cfg_setnfloat(cfg_t *cfg, const char *name, double value, unsigned int index);
1095:
1096: /** Set a value of a boolean option.
1097: *
1098: * @param opt The option structure (eg, as returned from cfg_getopt())
1099: * @param value The value to set.
1100: * @param index The index in the option value array that should be
1101: * modified. It is an error to set values with indices larger than 0
1102: * for options without the CFGF_LIST flag set.
1103: *
1104: * @return POSIX OK(0), or non-zero on failure.
1105: */
1106: DLLIMPORT int __export cfg_opt_setnbool(cfg_opt_t *opt, cfg_bool_t value, unsigned int index);
1107:
1108: /** Set the value of a boolean option given its name.
1109: *
1110: * @param cfg The configuration file context.
1111: * @param name The name of the option.
1112: * @param value The value to set. If the option is a list (the CFGF_LIST flag
1113: * is set), only the first value (with index 0) is set.
1114: *
1115: * @return POSIX OK(0), or non-zero on failure.
1116: */
1117: DLLIMPORT int __export cfg_setbool(cfg_t *cfg, const char *name, cfg_bool_t value);
1118:
1119: /** Set a value of a boolean option given its name and index.
1120: *
1121: * @param cfg The configuration file context.
1122: * @param name The name of the option.
1123: * @param value The value to set.
1124: * @param index The index in the option value array that should be
1125: * modified. It is an error to set values with indices larger than 0
1126: * for options without the CFGF_LIST flag set.
1127: *
1128: * @return POSIX OK(0), or non-zero on failure.
1129: */
1130: DLLIMPORT int __export cfg_setnbool(cfg_t *cfg, const char *name, cfg_bool_t value, unsigned int index);
1131:
1132: /** Set a value of a string option.
1133: *
1134: * @param opt The option structure (eg, as returned from cfg_getopt())
1135: * @param value The value to set. Memory for the string is allocated
1136: * and the value is copied. Any previous string value is freed.
1137: * @param index The index in the option value array that should be
1138: * modified. It is an error to set values with indices larger than 0
1139: * for options without the CFGF_LIST flag set.
1140: *
1141: * @return POSIX OK(0), or non-zero on failure.
1142: */
1143: DLLIMPORT int __export cfg_opt_setnstr(cfg_opt_t *opt, const char *value, unsigned int index);
1144:
1145: /** Set the value of a string option given its name.
1146: *
1147: * @param cfg The configuration file context.
1148: * @param name The name of the option.
1149: * @param value The value to set. Memory for the string is allocated and the
1150: * value is copied. Any previous string value is freed. If the option is a list
1151: * (the CFGF_LIST flag is set), only the first value (with index 0) is set.
1152: *
1153: * @return POSIX OK(0), or non-zero on failure.
1154: */
1155: DLLIMPORT int __export cfg_setstr(cfg_t *cfg, const char *name, const char *value);
1156:
1157: /** Set a value of a boolean option given its name and index.
1158: *
1159: * @param cfg The configuration file context.
1160: * @param name The name of the option.
1161: * @param value The value to set. Memory for the string is allocated
1162: * and the value is copied. Any privious string value is freed.
1163: * @param index The index in the option value array that should be
1164: * modified. It is an error to set values with indices larger than 0
1165: * for options without the CFGF_LIST flag set.
1166: *
1167: * @return POSIX OK(0), or non-zero on failure.
1168: */
1169: DLLIMPORT int __export cfg_setnstr(cfg_t *cfg, const char *name, const char *value, unsigned int index);
1170:
1171: /** Set values for a list option. All existing values are replaced
1172: * with the new ones.
1173: *
1174: * @param cfg The configuration file context.
1175: * @param name The name of the option.
1176: * @param nvalues Number of values to set.
1177: * @param ... The values to set, the type must match the type of the
1178: * option and the number of values must be equal to the nvalues
1179: * parameter.
1180: *
1181: * @return POSIX OK(0), or non-zero on failure.
1182: */
1183: DLLIMPORT int __export cfg_setlist(cfg_t *cfg, const char *name, unsigned int nvalues, ...);
1184:
1185: DLLIMPORT int __export cfg_numopts(cfg_opt_t *opts);
1186:
1187: /** Return number of options in a file or section
1188: *
1189: * @param cfg The configuration file or section context
1190: *
1191: * When a file has been parsed this function returns the number of
1192: * options/settings the file, or a sub-section, has.
1193: *
1194: * @return Number of options in a config file or section.
1195: */
1196: DLLIMPORT unsigned int __export cfg_num(cfg_t *cfg);
1197:
1198: /** Add values for a list option. The new values are appended to any
1199: * current values in the list.
1200: *
1201: * @param cfg The configuration file context.
1202: * @param name The name of the option.
1203: * @param nvalues Number of values to add.
1204: * @param ... The values to add, the type must match the type of the
1205: * option and the number of values must be equal to the nvalues
1206: * parameter.
1207: *
1208: * @return POSIX OK(0), or non-zero on failure.
1209: */
1210: DLLIMPORT int __export cfg_addlist(cfg_t *cfg, const char *name, unsigned int nvalues, ...);
1211:
1212: /** Set an option (create an instance of an option).
1213: *
1214: * @param cfg The configuration file context.
1215: * @param opt The option definition.
1216: * @param nvalues The number of values to set for the option.
1217: * @param values The value(s) for the option.
1218: *
1219: * @return POSIX OK(0), or non-zero on failure.
1220: */
1221: DLLIMPORT int cfg_opt_setmulti(cfg_t *cfg, cfg_opt_t *opt, unsigned int nvalues, char **values);
1222:
1223: /** Set an option (create an instance of an option).
1224: *
1225: * @param cfg The configuration file context.
1226: * @param name The name of the option.
1227: * @param nvalues The number of values to set for the option.
1228: * @param values The value(s) for the option.
1229: *
1230: * @return POSIX OK(0), or non-zero on failure.
1231: */
1232: DLLIMPORT int cfg_setmulti(cfg_t *cfg, const char *name, unsigned int nvalues, char **values);
1233:
1234: /** Create a new titled config section.
1235: *
1236: * @param cfg The configuration file context.
1237: * @param name The name of the option.
1238: * @param title The title of this section.
1239: *
1240: * @return A pointer to the created section or if the section
1241: * already exists a pointer to that section is returned.
1242: * If the section could not be created or found, 0 is returned.
1243: */
1244: DLLIMPORT cfg_t *cfg_addtsec(cfg_t *cfg, const char *name, const char *title);
1245:
1246: /** Removes and frees a config section, given a cfg_opt_t pointer.
1247: * @param opt The option structure (eg, as returned from cfg_getopt())
1248: * @param index Index of the section to remove. Zero based.
1249: * @see cfg_rmnsec
1250: *
1251: * @return POSIX OK(0), or non-zero on failure.
1252: */
1253: DLLIMPORT int __export cfg_opt_rmnsec(cfg_opt_t *opt, unsigned int index);
1254:
1255: /** Indexed version of cfg_rmsec(), used for CFGF_MULTI sections.
1256: * @param cfg The configuration file context.
1257: * @param name The name of the section.
1258: * @param index Index of the section to remove. Zero based.
1259: * @see cfg_rmsec
1260: *
1261: * @return POSIX OK(0), or non-zero on failure.
1262: */
1263: DLLIMPORT int __export cfg_rmnsec(cfg_t *cfg, const char *name, unsigned int index);
1264:
1265: /** Removes and frees a config section. This is the same as
1266: * calling cfg_rmnsec with index 0.
1267: * @param cfg The configuration file context.
1268: * @param name The name of the section.
1269: *
1270: * @return POSIX OK(0), or non-zero on failure.
1271: */
1272: DLLIMPORT int __export cfg_rmsec(cfg_t *cfg, const char *name);
1273:
1274: /** Removes and frees a config section, given a cfg_opt_t pointer
1275: * and the title.
1276: * @param opt The option structure (eg, as returned from cfg_getopt())
1277: * @param title The title of this section. The CFGF_TITLE flag must
1278: * have been set for this option.
1279: * @see cfg_rmtsec
1280: *
1281: * @return POSIX OK(0), or non-zero on failure.
1282: */
1283: DLLIMPORT int __export cfg_opt_rmtsec(cfg_opt_t *opt, const char *title);
1284:
1285: /** Removes and frees a section given the title, used for section with the
1286: * CFGF_TITLE flag set.
1287: *
1288: * @param cfg The configuration file context.
1289: * @param name The name of the section.
1290: * @param title The title of this section. The CFGF_TITLE flag must
1291: * have been set for this option.
1292: * @see cfg_rmsec
1293: *
1294: * @return POSIX OK(0), or non-zero on failure.
1295: */
1296: DLLIMPORT int __export cfg_rmtsec(cfg_t *cfg, const char *name, const char *title);
1297:
1298: /** Default value print function.
1299: *
1300: * Print only the value of a given option. Does not handle sections or
1301: * functions. Use cfg_opt_print to print the whole assignment ("option
1302: * = value"), or cfg_print to print the whole config file.
1303: *
1304: * @param opt The option structure (eg, as returned from cfg_getopt())
1305: * @param index The index in the option value array that should be printed
1306: * @param fp File stream to print to.
1307: *
1308: * @see cfg_print, cfg_opt_print
1309: *
1310: * @return POSIX OK(0), or non-zero on failure.
1311: */
1312: DLLIMPORT int __export cfg_opt_nprint_var(cfg_opt_t *opt, unsigned int index, FILE *fp);
1313:
1314: /** Print an option and its value to a file.
1315: * Same as cfg_opt_print, but with the indentation level specified.
1316: * @see cfg_opt_print
1317: *
1318: * @return POSIX OK(0), or non-zero on failure.
1319: */
1320: DLLIMPORT int __export cfg_opt_print_indent(cfg_opt_t *opt, FILE *fp, int indent);
1321:
1322: /** Print an option and its value to a file.
1323: *
1324: * If a print callback function is specified for the option, it is
1325: * used instead of cfg_opt_nprint_var.
1326: *
1327: * @param opt The option structure (eg, as returned from cfg_getopt())
1328: * @param fp File stream to print to.
1329: *
1330: * @see cfg_print_func_t
1331: *
1332: * @return POSIX OK(0), or non-zero on failure.
1333: */
1334: DLLIMPORT int __export cfg_opt_print(cfg_opt_t *opt, FILE *fp);
1335:
1336: /** Print the options and values to a file.
1337: * Same as cfg_print, but with the indentation level specified.
1338: * @see cfg_print
1339: *
1340: * @return POSIX OK(0), or non-zero on failure.
1341: */
1342: DLLIMPORT int __export cfg_print_indent(cfg_t *cfg, FILE *fp, int indent);
1343:
1344: /** Print the options and values to a file.
1345: *
1346: * Note that options in any included file are expanded and printed
1347: * directly to the file. Option values given with environment
1348: * variables in the parsed input are also printed expanded. This means
1349: * that if you parse a configuration file you can't expect that the
1350: * output from this function is identical to the initial file.
1351: *
1352: * @param cfg The configuration file context.
1353: * @param fp File stream to print to, use stdout to print to the screen.
1354: *
1355: * @see cfg_print_func_t, cfg_set_print_func
1356: *
1357: * @return POSIX OK(0), or non-zero on failure.
1358: */
1359: DLLIMPORT int __export cfg_print(cfg_t *cfg, FILE *fp);
1360:
1361: /** Set a print callback function for an option.
1362: *
1363: * @param opt The option structure (eg, as returned from cfg_getopt())
1364: * @param pf The print function callback.
1365: *
1366: * @see cfg_print_func_t
1367: */
1368: DLLIMPORT cfg_print_func_t __export cfg_opt_set_print_func(cfg_opt_t *opt, cfg_print_func_t pf);
1369:
1370: /** Set a print callback function for an option given its name.
1371: *
1372: * @param cfg The configuration file context.
1373: * @param name The name of the option.
1374: * @param pf The print callback function.
1375: *
1376: * @see cfg_print_func_t
1377: */
1378: DLLIMPORT cfg_print_func_t __export cfg_set_print_func(cfg_t *cfg, const char *name, cfg_print_func_t pf);
1379:
1380: /** Install a user-defined print filter function. This callback is
1381: * called for each option when printing cfg, or something above cfg
1382: * if cfg is a section in some parent cfg. When cfg (or something
1383: * above cfg) is printed, this filter is also inherited to child
1384: * sections unless the child section has its own print filter.
1385: *
1386: * @param cfg The configuration file context.
1387: * @param pff The print filter callback function.
1388: *
1389: * @return The old print filter function is returned.
1390: *
1391: * @see cfg_print_filter_func_t
1392: */
1393: DLLIMPORT cfg_print_filter_func_t __export cfg_set_print_filter_func(cfg_t *cfg, cfg_print_filter_func_t pff);
1394:
1395: /** Register a validating callback function for an option.
1396: *
1397: * @param cfg The configuration file context.
1398: * @param name The name of the option.
1399: * @param vf The validating callback function.
1400: *
1401: * @see cfg_validate_callback_t
1402: */
1403: DLLIMPORT cfg_validate_callback_t __export cfg_set_validate_func(cfg_t *cfg, const char *name, cfg_validate_callback_t vf);
1404:
1405: /** Register a validating callback function for an option.
1406: *
1407: * This callback is called for all cfg_set*() functions, although not
1408: * cfg_opt_set*(), and can be used to check and modify a value/string
1409: * *before* it is actually set. The regular callbacks are run after
1410: * the fact and are only called when parsing a buffer or file.
1411: *
1412: * @param cfg The configuration file context.
1413: * @param name The name of the option.
1414: * @param vf The validating callback function.
1415: *
1416: * @see cfg_validate_callback2_t
1417: */
1418: DLLIMPORT cfg_validate_callback2_t __export cfg_set_validate_func2(cfg_t *cfg, const char *name, cfg_validate_callback2_t vf);
1419:
1420: #ifdef __cplusplus
1421: }
1422: #endif
1423: #endif /* CONFUSE_H_ */
1424:
1425: /** @example ftpconf.c
1426: */
1427:
1428: /** @example simple.c
1429: */
1430:
1431: /** @example reread.c
1432: */
1433:
1434: /**
1435: * Local Variables:
1436: * indent-tabs-mode: t
1437: * c-file-style: "linux"
1438: * End:
1439: */
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