Annotation of embedaddon/confuse/src/confuse.h, revision 1.1.1.2
1.1 misho 1: /*
1.1.1.2 ! misho 2: * Copyright (c) 2002-2017 Martin Hedenfalk <martin@bzero.se>
1.1 misho 3: *
1.1.1.2 ! misho 4: * Permission to use, copy, modify, and/or distribute this software for any
1.1 misho 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: *
1.1.1.2 ! misho 27: * Copyright © 2002-2017 Martin Hedenfalk <martin@bzero.se>
1.1 misho 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:
1.1.1.2 ! misho 36: #ifndef CONFUSE_H_
! 37: #define CONFUSE_H_
1.1 misho 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
1.1.1.2 ! misho 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 */
1.1 misho 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 {
1.1.1.2 ! misho 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 */
1.1 misho 82: };
83: typedef enum cfg_type_t cfg_type_t;
84:
85: /** Flags. */
1.1.1.2 ! misho 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
1.1 misho 107: #define CFG_FILE_ERROR -1
108: #define CFG_PARSE_ERROR 1
109:
110: typedef union cfg_value_t cfg_value_t;
1.1.1.2 ! misho 111: typedef union cfg_simple_t cfg_simple_t;
1.1 misho 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;
1.1.1.2 ! misho 116: typedef struct cfg_searchpath_t cfg_searchpath_t;
1.1 misho 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: */
1.1.1.2 ! misho 143: typedef int (*cfg_func_t)(cfg_t *cfg, cfg_opt_t *opt, int argc, const char **argv);
1.1 misho 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);
1.1.1.2 ! misho 166:
1.1 misho 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: */
1.1.1.2 ! misho 188: typedef int (*cfg_callback_t)(cfg_t *cfg, cfg_opt_t *opt, const char *value, void *result);
1.1 misho 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:
1.1.1.2 ! misho 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:
1.1 misho 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. */
1.1.1.2 ! misho 232: typedef enum { cfg_false, cfg_true } cfg_bool_t;
1.1 misho 233:
234: /** Error reporting function. */
235: typedef void (*cfg_errfunc_t)(cfg_t *cfg, const char *fmt, va_list ap);
236:
1.1.1.2 ! misho 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:
1.1 misho 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 {
1.1.1.2 ! misho 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 */
1.1 misho 268: };
269:
270: /** Data structure holding the value of a fundamental option value.
271: */
272: union cfg_value_t {
1.1.1.2 ! misho 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;
1.1 misho 290: };
291:
292: /** Data structure holding the default value given by the
293: * initialization macros.
294: */
295: struct cfg_defvalue_t {
1.1.1.2 ! misho 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 */
1.1 misho 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 {
1.1.1.2 ! misho 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 */
1.1 misho 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) \
1.1.1.2 ! misho 334: {name,0,CFGT_STR,0,0,flags,0,{0,0,cfg_false,def,0},0,{.string=svalue},cb,0,0,0,0}
1.1 misho 335: #define __CFG_STR_LIST(name, def, flags, svalue, cb) \
1.1.1.2 ! misho 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}
1.1 misho 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) \
1.1.1.2 ! misho 415: {name,0,CFGT_INT,0,0,flags,0,{def,0,cfg_false,0,0},0,{.number=svalue},cb,0,0,0,0}
1.1 misho 416: #define __CFG_INT_LIST(name, def, flags, svalue, cb) \
1.1.1.2 ! misho 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}
1.1 misho 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).
1.1.1.2 ! misho 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.
1.1 misho 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) \
1.1.1.2 ! misho 451: {name,0,CFGT_FLOAT,0,0,flags,0,{0,def,cfg_false,0,0},0,{.fpnumber=svalue},cb,0,0,0,0}
1.1 misho 452: #define __CFG_FLOAT_LIST(name, def, flags, svalue, cb) \
1.1.1.2 ! misho 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}
1.1 misho 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) \
1.1.1.2 ! misho 484: {name,0,CFGT_BOOL,0,0,flags,0,{0,0,def,0,0},0,{.boolean=svalue},cb,0,0,0,0}
1.1 misho 485: #define __CFG_BOOL_LIST(name, def, flags, svalue, cb) \
1.1.1.2 ! misho 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}
1.1 misho 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) \
1.1.1.2 ! misho 528: {name,0,CFGT_SEC,0,0,flags,opts,{0,0,cfg_false,0,0},0,{0},0,0,0,0,0}
1.1 misho 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) \
1.1.1.2 ! misho 539: {name,0,CFGT_FUNC,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},func,{0},0,0,0,0,0}
1.1 misho 540:
541:
542: #define __CFG_PTR(name, def, flags, svalue, parsecb, freecb) \
1.1.1.2 ! misho 543: {name,0,CFGT_PTR,0,0,flags,0,{0,0,cfg_false,0,def},0,{.ptr=svalue},parsecb,0,0,0,freecb}
1.1 misho 544: #define __CFG_PTR_LIST(name, def, flags, svalue, parsecb, freecb) \
1.1.1.2 ! misho 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}
1.1 misho 546:
547: /** Initialize a user-defined option
548: *
549: * CFG_PTR options can only be used together with a value parsing callback.
1.1.1.2 ! misho 550: *
1.1 misho 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() \
1.1.1.2 ! misho 575: {0,0,CFGT_NONE,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},0,{0},0,0,0,0,0}
1.1 misho 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
1.1.1.2 ! misho 586: * functions are used (since version 2.3).
1.1 misho 587: *
1.1.1.2 ! misho 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>
1.1 misho 598: * @param opts An arrary of options
599: * @param flags One or more flags (bitwise or'ed together). Currently only
1.1.1.2 ! misho 600: * CFGF_NOCASE and CFGF_IGNORE_UNKNOWN are available. Use 0 if no flags are
! 601: * needed.
1.1 misho 602: *
603: * @return A configuration context structure. This pointer is passed
604: * to almost all other functions as the first parameter.
605: */
1.1.1.2 ! misho 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);
1.1 misho 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()
1.1.1.2 ! misho 663: *
! 664: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 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()
1.1.1.2 ! misho 675: *
! 676: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 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()
1.1.1.2 ! misho 684: *
! 685: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 686: */
1.1.1.2 ! misho 687: DLLIMPORT int __export cfg_free_value(cfg_opt_t *opt);
1.1 misho 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.
1.1.1.2 ! misho 691: *
! 692: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 693: */
1.1.1.2 ! misho 694: DLLIMPORT int __export cfg_free(cfg_t *cfg);
1.1 misho 695:
696: /** Install a user-defined error reporting function.
697: * @return The old error reporting function is returned.
698: */
1.1.1.2 ! misho 699: DLLIMPORT cfg_errfunc_t __export cfg_set_error_function(cfg_t *cfg, cfg_errfunc_t errfunc);
1.1 misho 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:
1.1.1.2 ! misho 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:
1.1 misho 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: */
1.1.1.2 ! misho 737: DLLIMPORT long int __export cfg_getnint(cfg_t *cfg, const char *name, unsigned int index);
1.1 misho 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: */
1.1.1.2 ! misho 763: DLLIMPORT double __export cfg_getnfloat(cfg_t *cfg, const char *name, unsigned int index);
1.1 misho 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: */
1.1.1.2 ! misho 780: DLLIMPORT char *__export cfg_opt_getnstr(cfg_opt_t *opt, unsigned int index);
1.1 misho 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: */
1.1.1.2 ! misho 788: DLLIMPORT char *__export cfg_getnstr(cfg_t *cfg, const char *name, unsigned int index);
1.1 misho 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: */
1.1.1.2 ! misho 798: DLLIMPORT char *__export cfg_getstr(cfg_t *cfg, const char *name);
1.1 misho 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);
1.1.1.2 ! misho 806:
1.1 misho 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: */
1.1.1.2 ! misho 814: DLLIMPORT cfg_bool_t __export cfg_getnbool(cfg_t *cfg, const char *name, unsigned int index);
1.1 misho 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:
1.1.1.2 ! misho 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);
1.1 misho 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: */
1.1.1.2 ! misho 838: DLLIMPORT void *__export cfg_getptr(cfg_t *cfg, const char *name);
1.1 misho 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: */
1.1.1.2 ! misho 846: DLLIMPORT cfg_t *__export cfg_opt_getnsec(cfg_opt_t *opt, unsigned int index);
1.1 misho 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: */
1.1.1.2 ! misho 856: DLLIMPORT cfg_t *__export cfg_getnsec(cfg_t *cfg, const char *name, unsigned int index);
1.1 misho 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: */
1.1.1.2 ! misho 865: DLLIMPORT cfg_t *__export cfg_opt_gettsec(cfg_opt_t *opt, const char *title);
1.1 misho 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: */
1.1.1.2 ! misho 876: DLLIMPORT cfg_t *__export cfg_gettsec(cfg_t *cfg, const char *name, const char *title);
1.1 misho 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: */
1.1.1.2 ! misho 888: DLLIMPORT cfg_t *__export cfg_getsec(cfg_t *cfg, const char *name);
1.1 misho 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: */
1.1.1.2 ! misho 917: DLLIMPORT const char *__export cfg_title(cfg_t *cfg);
1.1 misho 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: */
1.1.1.2 ! misho 925: DLLIMPORT const char *__export cfg_name(cfg_t *cfg);
1.1 misho 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: */
1.1.1.2 ! misho 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);
1.1 misho 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: */
1.1.1.2 ! misho 949: DLLIMPORT int __export cfg_include(cfg_t *cfg, cfg_opt_t *opt, int argc, const char **argv);
1.1 misho 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: */
1.1.1.2 ! misho 957: DLLIMPORT char *__export cfg_tilde_expand(const char *filename);
1.1 misho 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:
1.1.1.2 ! misho 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:
1.1 misho 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: */
1.1.1.2 ! misho 984: DLLIMPORT cfg_opt_t *__export cfg_getopt(cfg_t *cfg, const char *name);
1.1 misho 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: */
1.1.1.2 ! misho 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);
1.1 misho 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.
1.1.1.2 ! misho 1031: *
! 1032: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1033: */
1.1.1.2 ! misho 1034: DLLIMPORT int __export cfg_opt_setnint(cfg_opt_t *opt, long int value, unsigned int index);
1.1 misho 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.
1.1.1.2 ! misho 1042: *
! 1043: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1044: */
1.1.1.2 ! misho 1045: DLLIMPORT int __export cfg_setint(cfg_t *cfg, const char *name, long int value);
1.1 misho 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.
1.1.1.2 ! misho 1055: *
! 1056: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1057: */
1.1.1.2 ! misho 1058: DLLIMPORT int __export cfg_setnint(cfg_t *cfg, const char *name, long int value, unsigned int index);
1.1 misho 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.
1.1.1.2 ! misho 1067: *
! 1068: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1069: */
1.1.1.2 ! misho 1070: DLLIMPORT int __export cfg_opt_setnfloat(cfg_opt_t *opt, double value, unsigned int index);
1.1 misho 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.
1.1.1.2 ! misho 1078: *
! 1079: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1080: */
1.1.1.2 ! misho 1081: DLLIMPORT int __export cfg_setfloat(cfg_t *cfg, const char *name, double value);
1.1 misho 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.
1.1.1.2 ! misho 1091: *
! 1092: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1093: */
1.1.1.2 ! misho 1094: DLLIMPORT int __export cfg_setnfloat(cfg_t *cfg, const char *name, double value, unsigned int index);
1.1 misho 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.
1.1.1.2 ! misho 1103: *
! 1104: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1105: */
1.1.1.2 ! misho 1106: DLLIMPORT int __export cfg_opt_setnbool(cfg_opt_t *opt, cfg_bool_t value, unsigned int index);
1.1 misho 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.
1.1.1.2 ! misho 1114: *
! 1115: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1116: */
1.1.1.2 ! misho 1117: DLLIMPORT int __export cfg_setbool(cfg_t *cfg, const char *name, cfg_bool_t value);
1.1 misho 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.
1.1.1.2 ! misho 1127: *
! 1128: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1129: */
1.1.1.2 ! misho 1130: DLLIMPORT int __export cfg_setnbool(cfg_t *cfg, const char *name, cfg_bool_t value, unsigned int index);
1.1 misho 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.
1.1.1.2 ! misho 1140: *
! 1141: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1142: */
1.1.1.2 ! misho 1143: DLLIMPORT int __export cfg_opt_setnstr(cfg_opt_t *opt, const char *value, unsigned int index);
1.1 misho 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.
1.1.1.2 ! misho 1152: *
! 1153: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1154: */
1.1.1.2 ! misho 1155: DLLIMPORT int __export cfg_setstr(cfg_t *cfg, const char *name, const char *value);
1.1 misho 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.
1.1.1.2 ! misho 1166: *
! 1167: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1168: */
1.1.1.2 ! misho 1169: DLLIMPORT int __export cfg_setnstr(cfg_t *cfg, const char *name, const char *value, unsigned int index);
1.1 misho 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.
1.1.1.2 ! misho 1180: *
! 1181: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1182: */
1.1.1.2 ! misho 1183: DLLIMPORT int __export cfg_setlist(cfg_t *cfg, const char *name, unsigned int nvalues, ...);
1.1 misho 1184:
1185: DLLIMPORT int __export cfg_numopts(cfg_opt_t *opts);
1186:
1.1.1.2 ! misho 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:
1.1 misho 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.
1.1.1.2 ! misho 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.
1.1 misho 1282: */
1.1.1.2 ! misho 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);
1.1 misho 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
1.1.1.2 ! misho 1309: *
! 1310: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1311: */
1.1.1.2 ! misho 1312: DLLIMPORT int __export cfg_opt_nprint_var(cfg_opt_t *opt, unsigned int index, FILE *fp);
1.1 misho 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
1.1.1.2 ! misho 1317: *
! 1318: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1319: */
1.1.1.2 ! misho 1320: DLLIMPORT int __export cfg_opt_print_indent(cfg_opt_t *opt, FILE *fp, int indent);
1.1 misho 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
1.1.1.2 ! misho 1331: *
! 1332: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1333: */
1.1.1.2 ! misho 1334: DLLIMPORT int __export cfg_opt_print(cfg_opt_t *opt, FILE *fp);
1.1 misho 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
1.1.1.2 ! misho 1339: *
! 1340: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1341: */
1.1.1.2 ! misho 1342: DLLIMPORT int __export cfg_print_indent(cfg_t *cfg, FILE *fp, int indent);
1.1 misho 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
1.1.1.2 ! misho 1356: *
! 1357: * @return POSIX OK(0), or non-zero on failure.
1.1 misho 1358: */
1.1.1.2 ! misho 1359: DLLIMPORT int __export cfg_print(cfg_t *cfg, FILE *fp);
1.1 misho 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: */
1.1.1.2 ! misho 1368: DLLIMPORT cfg_print_func_t __export cfg_opt_set_print_func(cfg_opt_t *opt, cfg_print_func_t pf);
1.1 misho 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: */
1.1.1.2 ! misho 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);
1.1 misho 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: */
1.1.1.2 ! misho 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);
1.1 misho 1419:
1420: #ifdef __cplusplus
1421: }
1422: #endif
1.1.1.2 ! misho 1423: #endif /* CONFUSE_H_ */
1.1 misho 1424:
1425: /** @example ftpconf.c
1426: */
1427:
1428: /** @example simple.c
1429: */
1430:
1431: /** @example reread.c
1432: */
1.1.1.2 ! misho 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