confuse: confuse.h File Reference

confuse 3.0

- Main Page
- Data Structures
- Files
- Examples

- File List
- Globals

Data Structures | Macros | Typedefs | Enumerations | Functions
confuse.h File Reference

A configuration file parser library. More...

`#include <stdio.h>`
`#include <stdarg.h>`

Go to the source code of this file.

## Data Structures
struct | cfg_t
| Data structure holding information about a "section". More...
union | cfg_value_t
| Data structure holding the value of a fundamental option value. More...
union | cfg_simple_t
| Data structure holding the pointer to a user provided variable defined with CFG_SIMPLE_*. More...
struct | cfg_defvalue_t
| Data structure holding the default value given by the initialization macros. More...
struct | cfg_opt_t
| Data structure holding information about an option. More...

## Macros
#define | CFGF_NONE 0
| Flags. More...
#define | CFGF_MULTI 1
| option may be specified multiple times (only applies to sections)
#define | CFGF_LIST 2
| option is a list
#define | CFGF_NOCASE 4
| configuration file is case insensitive
#define | CFGF_TITLE 8
| option has a title (only applies to sections)
#define | CFGF_NODEFAULT 16
| option has no default value
#define | CFGF_NO_TITLE_DUPES 32
| multiple section titles must be unique (duplicates raises an error, only applies to sections)
#define | CFGF_IGNORE_UNKNOWN 256
| ignore unknown options in configuration files
#define | CFGF_DEPRECATED 512
| option is deprecated and should be ignored. More...
#define | CFGF_DROP 1024
| option should be dropped after parsing
#define | CFG_SUCCESS 0
| Return codes from cfg_parse(), cfg_parse_boolean(), and cfg_set*() functions. More...
#define | CFG_STR(name, def, flags) __CFG_STR(name, def, flags, 0, 0)
| Initialize a string option.
#define | CFG_STR_LIST(name, def, flags) __CFG_STR_LIST(name, def, flags, 0, 0)
| Initialize a string list option.
#define | CFG_STR_CB(name, def, flags, cb) __CFG_STR(name, def, flags, 0, cb)
| Initialize a string option with a value parsing callback.
#define | CFG_STR_LIST_CB(name, def, flags, cb) __CFG_STR_LIST(name, def, flags, 0, cb)
| Initialize a string list option with a value parsing callback.
#define | CFG_SIMPLE_STR(name, svalue) __CFG_STR(name, 0, CFGF_NONE, svalue, 0)
| Initialize a "simple" string option. More...
#define | CFG_INT(name, def, flags) __CFG_INT(name, def, flags, 0, 0)
| Initialize an integer option.
#define | CFG_INT_LIST(name, def, flags) __CFG_INT_LIST(name, def, flags, 0, 0)
| Initialize an integer list option.
#define | CFG_INT_CB(name, def, flags, cb) __CFG_INT(name, def, flags, 0, cb)
| Initialize an integer option with a value parsing callback.
#define | CFG_INT_LIST_CB(name, def, flags, cb) __CFG_INT_LIST(name, def, flags, 0, cb)
| Initialize an integer list option with a value parsing callback.
#define | CFG_SIMPLE_INT(name, svalue) __CFG_INT(name, 0, CFGF_NONE, svalue, 0)
| Initialize a "simple" integer option (see documentation for CFG_SIMPLE_STR for more information). More...
#define | CFG_FLOAT(name, def, flags) __CFG_FLOAT(name, def, flags, 0, 0)
| Initialize a floating point option.
#define | CFG_FLOAT_LIST(name, def, flags) __CFG_FLOAT_LIST(name, def, flags, 0, 0)
| Initialize a floating point list option.
#define | CFG_FLOAT_CB(name, def, flags, cb) __CFG_FLOAT(name, def, flags, 0, cb)
| Initialize a floating point option with a value parsing callback.
#define | CFG_FLOAT_LIST_CB(name, def, flags, cb) __CFG_FLOAT_LIST(name, def, flags, 0, cb)
| Initialize a floating point list option with a value parsing callback.
#define | CFG_SIMPLE_FLOAT(name, svalue) __CFG_FLOAT(name, 0, CFGF_NONE, svalue, 0)
| Initialize a "simple" floating point option (see documentation for CFG_SIMPLE_STR for more information).
#define | CFG_BOOL(name, def, flags) __CFG_BOOL(name, def, flags, 0, 0)
| Initialize a boolean option.
#define | CFG_BOOL_LIST(name, def, flags) __CFG_BOOL_LIST(name, def, flags, 0, 0)
| Initialize a boolean list option.
#define | CFG_BOOL_CB(name, def, flags, cb) __CFG_BOOL(name, def, flags, 0, cb)
| Initialize a boolean option with a value parsing callback.
#define | CFG_BOOL_LIST_CB(name, def, flags, cb) __CFG_BOOL_LIST(name, def, flags, 0, cb)
| Initialize a boolean list option with a value parsing callback.
#define | CFG_SIMPLE_BOOL(name, svalue) __CFG_BOOL(name, cfg_false, CFGF_NONE, svalue, 0)
| Initialize a "simple" boolean option (see documentation for CFG_SIMPLE_STR for more information).
#define | CFG_SEC(name, opts, flags) {name,CFGT_SEC,0,0,flags,opts,{0,0,cfg_false,0,0},0,{0},0,0,0,0}
| Initialize a section. More...
#define | CFG_FUNC(name, func) {name,CFGT_FUNC,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},func,{0},0,0,0,0}
| Initialize a function. More...
#define | CFG_PTR_CB(name, def, flags, parsecb, freecb) __CFG_PTR(name, def, flags, 0, parsecb, freecb)
| Initialize a user-defined option. More...
#define | CFG_PTR_LIST_CB(name, def, flags, parsecb, freecb) __CFG_PTR(name, def, flags | CFGF_LIST, 0, parsecb, freecb)
| Initialize a list of user-defined options.
#define | CFG_END() {0,CFGT_NONE,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},0,{0},0,0,0,0}
| Terminate list of options. More...

## Typedefs
typedef int(* | cfg_func_t) (cfg_t *cfg, cfg_opt_t *opt, int argc, const char **argv)
| Function prototype used by CFGT_FUNC options. More...
typedef void(* | cfg_print_func_t) (cfg_opt_t *opt, unsigned int index, FILE *fp)
| Function prototype used by the cfg_print_ functions. More...
typedef int(* | cfg_callback_t) (cfg_t *cfg, cfg_opt_t *opt, const char *value, void *result)
| Value parsing callback prototype. More...
typedef int(* | cfg_validate_callback_t) (cfg_t *cfg, cfg_opt_t *opt)
| Validating callback prototype. More...
typedef void(* | cfg_free_func_t) (void *value)
| User-defined memory release function for CFG_PTR values. More...
typedef void(* | cfg_errfunc_t) (cfg_t *cfg, const char *fmt, va_list ap)
| Error reporting function. More...

## Enumerations
enum | cfg_type_t { , CFGT_INT, CFGT_FLOAT, CFGT_STR, CFGT_BOOL, CFGT_SEC, CFGT_FUNC, CFGT_PTR }
| Fundamental option types. More...
enum | cfg_bool_t
| Boolean values. More...

## Functions
DLLIMPORT cfg_t *__export | cfg_init (cfg_opt_t *opts, cfg_flag_t flags)
| Create and initialize a cfg_t structure. More...
DLLIMPORT int __export | cfg_add_searchpath (cfg_t *cfg, const char *dir)
| Add a searchpath directory to the configuration context, the const char* argument will be duplicated and then freed as part of the usual context takedown. More...
DLLIMPORT char *__export | cfg_searchpath (cfg_searchpath_t *path, const char *file)
| Search the linked-list of cfg_searchpath_t for the specified file. More...
DLLIMPORT int __export | cfg_parse (cfg_t *cfg, const char *filename)
| Parse a configuration file. More...
DLLIMPORT int __export | cfg_parse_fp (cfg_t *cfg, FILE *fp)
| Same as cfg_parse() above, but takes an already opened file as argument. More...
DLLIMPORT int __export | cfg_parse_buf (cfg_t *cfg, const char *buf)
| Same as cfg_parse() above, but takes a character buffer as argument. More...
DLLIMPORT int __export | cfg_free_value (cfg_opt_t *opt)
| Free the memory allocated for the values of a given option. More...
DLLIMPORT int __export | cfg_free (cfg_t *cfg)
| Free a cfg_t context. More...
DLLIMPORT cfg_errfunc_t __export | cfg_set_error_function (cfg_t *cfg, cfg_errfunc_t errfunc)
| Install a user-defined error reporting function. More...
DLLIMPORT void __export | cfg_error (cfg_t *cfg, const char *fmt,...)
| Show a parser error. More...
DLLIMPORT signed long __export | cfg_opt_getnint (cfg_opt_t *opt, unsigned int index)
| Returns the value of an integer option, given a cfg_opt_t pointer. More...
DLLIMPORT long int __export | cfg_getnint (cfg_t *cfg, const char *name, unsigned int index)
| Indexed version of cfg_getint(), used for lists. More...
DLLIMPORT long int __export | cfg_getint (cfg_t *cfg, const char *name)
| Returns the value of an integer option. More...
DLLIMPORT double __export | cfg_opt_getnfloat (cfg_opt_t *opt, unsigned int index)
| Returns the value of a floating point option, given a cfg_opt_t pointer. More...
DLLIMPORT double __export | cfg_getnfloat (cfg_t *cfg, const char *name, unsigned int index)
| Indexed version of cfg_getfloat(), used for lists. More...
DLLIMPORT double __export | cfg_getfloat (cfg_t *cfg, const char *name)
| Returns the value of a floating point option. More...
DLLIMPORT char *__export | cfg_opt_getnstr (cfg_opt_t *opt, unsigned int index)
| Returns the value of a string option, given a cfg_opt_t pointer. More...
DLLIMPORT char *__export | cfg_getnstr (cfg_t *cfg, const char *name, unsigned int index)
| Indexed version of cfg_getstr(), used for lists. More...
DLLIMPORT char *__export | cfg_getstr (cfg_t *cfg, const char *name)
| Returns the value of a string option. More...
DLLIMPORT cfg_bool_t __export | cfg_opt_getnbool (cfg_opt_t *opt, unsigned int index)
| Returns the value of a boolean option, given a cfg_opt_t pointer. More...
DLLIMPORT cfg_bool_t __export | cfg_getnbool (cfg_t *cfg, const char *name, unsigned int index)
| Indexed version of cfg_getbool(), used for lists. More...
DLLIMPORT cfg_bool_t __export | cfg_getbool (cfg_t *cfg, const char *name)
| Returns the value of a boolean option. More...
DLLIMPORT void *__export | cfg_getptr (cfg_t *cfg, const char *name)
| Returns the value of a user-defined option (void pointer). More...
DLLIMPORT cfg_t *__export | cfg_opt_getnsec (cfg_opt_t *opt, unsigned int index)
| Returns the value of a section option, given a cfg_opt_t pointer. More...
DLLIMPORT cfg_t *__export | cfg_getnsec (cfg_t *cfg, const char *name, unsigned int index)
| Indexed version of cfg_getsec(), used for sections with the CFGF_MULTI flag set. More...
DLLIMPORT cfg_t *__export | cfg_opt_gettsec (cfg_opt_t *opt, const char *title)
| Returns the value of a section option, given a cfg_opt_t pointer and the title. More...
DLLIMPORT cfg_t *__export | cfg_gettsec (cfg_t *cfg, const char *name, const char *title)
| Return a section given the title, used for section with the CFGF_TITLE flag set. More...
DLLIMPORT cfg_t *__export | cfg_getsec (cfg_t *cfg, const char *name)
| Returns the value of a section option. More...
DLLIMPORT unsigned int __export | cfg_opt_size (cfg_opt_t *opt)
| Return the number of values this option has. More...
DLLIMPORT unsigned int __export | cfg_size (cfg_t *cfg, const char *name)
| Return the number of values this option has. More...
DLLIMPORT const char *__export | cfg_title (cfg_t *cfg)
| Return the title of a section. More...
DLLIMPORT const char *__export | cfg_name (cfg_t *cfg)
| Return the name of a section. More...
DLLIMPORT const char *__export | cfg_opt_name (cfg_opt_t *opt)
| Return the name of an option. More...
DLLIMPORT int __export | cfg_include (cfg_t *cfg, cfg_opt_t *opt, int argc, const char **argv)
| Predefined include-function. More...
DLLIMPORT char *__export | cfg_tilde_expand (const char *filename)
| Does tilde expansion (~ -> $HOME) on the filename. More...
DLLIMPORT int __export | cfg_parse_boolean (const char *s)
| Parse a boolean option string. More...
DLLIMPORT cfg_opt_t *__export | cfg_getopt (cfg_t *cfg, const char *name)
| Return an option given it's name. More...
DLLIMPORT cfg_value_t * | cfg_setopt (cfg_t *cfg, cfg_opt_t *opt, const char *value)
| Set an option (create an instance of an option). More...
DLLIMPORT int __export | cfg_opt_setnint (cfg_opt_t *opt, long int value, unsigned int index)
| Set a value of an integer option. More...
DLLIMPORT int __export | cfg_setint (cfg_t *cfg, const char *name, long int value)
| Set the value of an integer option given its name. More...
DLLIMPORT int __export | cfg_setnint (cfg_t *cfg, const char *name, long int value, unsigned int index)
| Set a value of an integer option given its name and index. More...
DLLIMPORT int __export | cfg_opt_setnfloat (cfg_opt_t *opt, double value, unsigned int index)
| Set a value of a floating point option. More...
DLLIMPORT int __export | cfg_setfloat (cfg_t *cfg, const char *name, double value)
| Set the value of a floating point option given its name. More...
DLLIMPORT int __export | cfg_setnfloat (cfg_t *cfg, const char *name, double value, unsigned int index)
| Set a value of a floating point option given its name and index. More...
DLLIMPORT int __export | cfg_opt_setnbool (cfg_opt_t *opt, cfg_bool_t value, unsigned int index)
| Set a value of a boolean option. More...
DLLIMPORT int __export | cfg_setbool (cfg_t *cfg, const char *name, cfg_bool_t value)
| Set the value of a boolean option given its name. More...
DLLIMPORT int __export | cfg_setnbool (cfg_t *cfg, const char *name, cfg_bool_t value, unsigned int index)
| Set a value of a boolean option given its name and index. More...
DLLIMPORT int __export | cfg_opt_setnstr (cfg_opt_t *opt, const char *value, unsigned int index)
| Set a value of a string option. More...
DLLIMPORT int __export | cfg_setstr (cfg_t *cfg, const char *name, const char *value)
| Set the value of a string option given its name. More...
DLLIMPORT int __export | cfg_setnstr (cfg_t *cfg, const char *name, const char *value, unsigned int index)
| Set a value of a boolean option given its name and index. More...
DLLIMPORT int __export | cfg_setlist (cfg_t *cfg, const char *name, unsigned int nvalues,...)
| Set values for a list option. More...
DLLIMPORT int __export | cfg_addlist (cfg_t *cfg, const char *name, unsigned int nvalues,...)
| Add values for a list option. More...
DLLIMPORT int | cfg_opt_setmulti (cfg_t *cfg, cfg_opt_t *opt, unsigned int nvalues, char **values)
| Set an option (create an instance of an option). More...
DLLIMPORT int | cfg_setmulti (cfg_t *cfg, const char *name, unsigned int nvalues, char **values)
| Set an option (create an instance of an option). More...
DLLIMPORT int __export | cfg_opt_rmnsec (cfg_opt_t *opt, unsigned int index)
| Removes and frees a config section, given a cfg_opt_t pointer. More...
DLLIMPORT int __export | cfg_rmnsec (cfg_t *cfg, const char *name, unsigned int index)
| Indexed version of cfg_rmsec(), used for CFGF_MULTI sections. More...
DLLIMPORT int __export | cfg_rmsec (cfg_t *cfg, const char *name)
| Removes and frees a config section. More...
DLLIMPORT int __export | cfg_opt_rmtsec (cfg_opt_t *opt, const char *title)
| Removes and frees a config section, given a cfg_opt_t pointer and the title. More...
DLLIMPORT int __export | cfg_rmtsec (cfg_t *cfg, const char *name, const char *title)
| Removes and frees a section given the title, used for section with the CFGF_TITLE flag set. More...
DLLIMPORT int __export | cfg_opt_nprint_var (cfg_opt_t *opt, unsigned int index, FILE *fp)
| Default value print function. More...
DLLIMPORT int __export | cfg_opt_print_indent (cfg_opt_t *opt, FILE *fp, int indent)
| Print an option and its value to a file. More...
DLLIMPORT int __export | cfg_opt_print (cfg_opt_t *opt, FILE *fp)
| Print an option and its value to a file. More...
DLLIMPORT int __export | cfg_print_indent (cfg_t *cfg, FILE *fp, int indent)
| Print the options and values to a file. More...
DLLIMPORT int __export | cfg_print (cfg_t *cfg, FILE *fp)
| Print the options and values to a file. More...
DLLIMPORT cfg_print_func_t __export | cfg_opt_set_print_func (cfg_opt_t *opt, cfg_print_func_t pf)
| Set a print callback function for an option. More...
DLLIMPORT cfg_print_func_t __export | cfg_set_print_func (cfg_t *cfg, const char *name, cfg_print_func_t pf)
| Set a print callback function for an option given its name. More...
DLLIMPORT cfg_validate_callback_t __export | cfg_set_validate_func (cfg_t *cfg, const char *name, cfg_validate_callback_t vf)
| Register a validating callback function for an option. More...

## Detailed Description

A configuration file parser library.

## Macro Definition Documentation

#define CFG_END | ( |  | ) | {0,CFGT_NONE,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},0,{0},0,0,0,0}

Terminate list of options.

This must be the last initializer in the option list.

Examples:
  ftpconf.c, reread.c, and simple.c.

#define CFG_FUNC | ( |  | name,
|  |  | func
| ) |  | {name,CFGT_FUNC,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},func,{0},0,0,0,0}

Initialize a function.

Parameters

  name | The name of the option
  func | The callback function.

See also
  cfg_func_t

Examples:
  ftpconf.c.

#define CFG_PTR_CB | ( |  | name,
|  |  | def,
|  |  | flags,
|  |  | parsecb,
|  |  | freecb
| ) |  | __CFG_PTR(name, def, flags, 0, parsecb, freecb)

Initialize a user-defined option.

CFG_PTR options can only be used together with a value parsing callback.

Parameters

  name | The name of the option
  def | Default value
  flags | Flags
  parsecb | Value parsing callback
  freecb | Memory release function

See also
  cfg_callback_t, cfg_free_func_t

#define CFG_SEC | ( |  | name,
|  |  | opts,
|  |  | flags
| ) |  | {name,CFGT_SEC,0,0,flags,opts,{0,0,cfg_false,0,0},0,{0},0,0,0,0}

Initialize a section.

Parameters

  name | The name of the option
  opts | Array of options that are valid within this section
  flags | Flags, specify CFGF_MULTI if it should be possible to have multiples of the same section, and CFGF_TITLE if the section(s) must have a title (which can be used in the cfg_gettsec() function)

Examples:
  ftpconf.c, and reread.c.

#define CFG_SIMPLE_INT | ( |  | name,
|  |  | svalue
| ) |  | __CFG_INT(name, 0, CFGF_NONE, svalue, 0)

Initialize a "simple" integer option (see documentation for CFG_SIMPLE_STR for more information).

Note that confuse uses long integers, so make sure that any pointer you provide for svalue points to a long int rather than a normal int. Otherwise, you will have strange problems on 64-bit architectures.

Examples:
  simple.c.

#define CFG_SIMPLE_STR | ( |  | name,
|  |  | svalue
| ) |  | __CFG_STR(name, 0, CFGF_NONE, svalue, 0)

Initialize a "simple" string option.

"Simple" options (in lack of a better expression) does not support lists of values or multiple sections. LibConfuse will store the value of a simple option in the user-defined location specified by the value parameter in the initializer. Simple options are not stored in the cfg_t context, only a pointer. Sections can not be initialized as a "simple" option.

As of version 2.2, libConfuse can now return the values of simple options with the cfg_get functions. This allows using the new cfg_print function with simple options.

libConfuse doesn't support handling default values for "simple" options. They are assumed to be set by the calling application before cfg_parse is called.

Parameters

  name | name of the option
  svalue | pointer to a character pointer (a char **). This value must be initalized either to NULL or to a malloc()'ed string. You can't use
      char *user = "joe";
      ...
      cfg_opt_t opts[] = {
          CFG_SIMPLE_STR("user", &user),
      ...
  since libConfuse will try to free the static string "joe" (which is an error) when a "user" option is found. Rather, use the following code snippet:
      char *user = strdup("joe");
      ...
      cfg_opt_t opts[] = {
           CFG_SIMPLE_STR("user", &user),
      ...
  Alternatively, the default value can be set after the opts struct is defined, as in:
      char *user = 0;
      ...
      cfg_opt_t opts[] = {
           CFG_SIMPLE_STR("user", &user),
      ...
      user = strdup("joe");
      cfg = cfg_init(opts, 0);
      cfg_parse(cfg, filename);

Examples:
  simple.c.

#define CFG_SUCCESS 0

Return codes from cfg_parse(), cfg_parse_boolean(), and cfg_set*() functions.

Examples:
  ftpconf.c, and reread.c.

Referenced by cfg_add_searchpath(), cfg_addlist(), cfg_free(), cfg_free_value(), cfg_opt_nprint_var(), cfg_opt_print_indent(), cfg_opt_rmnsec(), cfg_opt_setmulti(), cfg_opt_setnbool(), cfg_opt_setnfloat(), cfg_opt_setnint(), cfg_opt_setnstr(), cfg_parse_buf(), cfg_parse_fp(), cfg_print_indent(), and cfg_setlist().

#define CFGF_DEPRECATED 512

option is deprecated and should be ignored.

#define CFGF_NONE 0

Flags.

Examples:
  ftpconf.c, and reread.c.

## Typedef Documentation

typedef int(* cfg_callback_t) (cfg_t *cfg, cfg_opt_t *opt, const char *value, void *result)

Value parsing callback prototype.

This is a callback function (different from the one registered with the CFG_FUNC initializer) used to parse a value. This can be used to override the internal parsing of a value.

Suppose you want an integer option that only can have certain values, for example 1, 2 and 3, and these should be written in the configuration file as "yes", "no" and "maybe". The callback function would be called with the found value ("yes", "no" or "maybe") as a string, and the result should be stored in the result parameter.

Parameters

  cfg | The configuration file context.
  opt | The option.
  value | The value found in the configuration file.
  result | Pointer to storage for the result, cast to a void pointer.

Returns
  On success, 0 should be returned. All other values indicates an error, and the parsing is aborted. The callback function should notify the error itself, for example by calling cfg_error().

typedef void(* cfg_errfunc_t) (cfg_t *cfg, const char *fmt, va_list ap)

Error reporting function.

typedef void(* cfg_free_func_t) (void *value)

User-defined memory release function for CFG_PTR values.

This callback is used to free memory allocated in a value parsing callback function. Especially useful for CFG_PTR options, since libConfuse will not itself release such values. If the values are simply allocated with a malloc(3), one can use the standard free(3) function here.

typedef int(* cfg_func_t) (cfg_t *cfg, cfg_opt_t *opt, int argc, const char **argv)

Function prototype used by CFGT_FUNC options.

This is a callback function, registered with the CFG_FUNC initializer. Each time libConfuse finds a function, the registered callback function is called (parameters are passed as strings, any conversion to other types should be made in the callback function). libConfuse does not support any storage of the data found; these are passed as parameters to the callback, and it's the responsibility of the callback function to do whatever it should do with the data.

Parameters

  cfg | The configuration file context.
  opt | The option.
  argc | Number of arguments passed. The callback function is responsible for checking that the correct number of arguments are passed.
  argv | Arguments as an array of character strings.

Returns
  On success, 0 should be returned. All other values indicates an error, and the parsing is aborted. The callback function should notify the error itself, for example by calling cfg_error().

See also
  CFG_FUNC

typedef void(* cfg_print_func_t) (cfg_opt_t *opt, unsigned int index, FILE *fp)

Function prototype used by the cfg_print_ functions.

This callback function is used to print option values. For options with a value parsing callback, this is often required, especially if a string is mapped to an integer by the callback. This print callback must then map the integer back to the appropriate string.

Except for functions, the print callback function should only print the value of the option, not the name and the equal sign (that is handled by the cfg_opt_print function). For function options however, the name and the parenthesis must be printed by this function. The value to print can be accessed with the cfg_opt_get functions.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  index | Index of the value to get. Zero based.
  fp | File stream to print to, use stdout to print to the screen.

See also
  cfg_print, cfg_set_print_func

typedef int(* cfg_validate_callback_t) (cfg_t *cfg, cfg_opt_t *opt)

Validating callback prototype.

This callback function is called after an option has been parsed and set. The function is called for both fundamental values (strings, integers etc) as well as lists and sections. This can for example be used to validate that all required options in a section has been set to sane values.

Returns
  On success, 0 should be returned. All other values indicates an error, and the parsing is aborted. The callback function should notify the error itself, for example by calling cfg_error().

See also
  cfg_set_validate_func

## Enumeration Type Documentation

enum cfg_bool_t

Boolean values.

enum cfg_type_t

Fundamental option types.

Enumerator
CFGT_INT | integer
CFGT_FLOAT | floating point number
CFGT_STR | string
CFGT_BOOL | boolean value
CFGT_SEC | section
CFGT_FUNC | function
CFGT_PTR | pointer to user-defined value

## Function Documentation

DLLIMPORT int __export cfg_add_searchpath | ( | cfg_t * | cfg,
|  | const char * | dir
| ) |  |

Add a searchpath directory to the configuration context, the const char* argument will be duplicated and then freed as part of the usual context takedown.

All directories added to the context in this manner will be searched for the file specified in cfg_parse(), and for those included. All directories added with this function will be "tilde expanded". Note that the current directory is not added to the searchpath by default.

Parameters

  cfg | The configuration file context as returned from cfg_init().
  dir | Directory to be added to the search path.

Returns
  On success, CFG_SUCCESS, on failure (which can only be caused by a failed malloc()), CFG_PARSE_ERROR.

References CFG_SUCCESS, cfg_tilde_expand(), and cfg_t::path.

DLLIMPORT int __export cfg_addlist | ( | cfg_t * | cfg,
|  | const char * | name,
|  | unsigned int | nvalues,
|  |  | ...
| ) |  |

Add values for a list option.

The new values are appended to any current values in the list.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  nvalues | Number of values to add.
  ... | The values to add, the type must match the type of the option and the number of values must be equal to the nvalues parameter.

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_getopt(), CFG_SUCCESS, CFGF_LIST, and cfg_opt_t::flags.

DLLIMPORT void __export cfg_error | ( | cfg_t * | cfg,
|  | const char * | fmt,
|  |  | ...
| ) |  |

Show a parser error.

Any user-defined error reporting function is called.

See also
  cfg_set_error_function

Examples:
  ftpconf.c.

References cfg_t::errfunc, cfg_t::filename, and cfg_t::line.

Referenced by cfg_getopt(), cfg_include(), and cfg_setopt().

DLLIMPORT int __export cfg_free | ( | cfg_t * | cfg | ) |

Free a cfg_t context.

All memory allocated by the cfg_t context structure are freed, and can't be used in any further cfg_* calls.

Returns
  POSIX OK(0), or non-zero on failure.

Examples:
  ftpconf.c, reread.c, and simple.c.

References cfg_free_value(), CFG_SUCCESS, cfg_t::filename, cfg_t::name, cfg_opt_t::name, cfg_t::opts, cfg_t::path, and cfg_t::title.

Referenced by cfg_free_value(), cfg_opt_rmnsec(), and cfg_setopt().

DLLIMPORT int __export cfg_free_value | ( | cfg_opt_t * | opt | ) |

Free the memory allocated for the values of a given option.

Only the values are freed, not the option itself (it is freed by cfg_free()).

See also
  cfg_free()

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_free(), CFG_SUCCESS, CFGT_PTR, CFGT_SEC, CFGT_STR, cfg_opt_t::nvalues, cfg_t::path, cfg_value_t::ptr, cfg_value_t::section, cfg_value_t::string, cfg_opt_t::type, and cfg_opt_t::values.

Referenced by cfg_free(), cfg_opt_setmulti(), cfg_setlist(), and cfg_setopt().

DLLIMPORT cfg_bool_t __export cfg_getbool | ( | cfg_t * | cfg,
|  | const char * | name
| ) |  |

Returns the value of a boolean option.

Parameters

  cfg | The configuration file context.
  name | The name of the option.

Returns
  The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding cfg_opt_t structure is returned. It is an error to try to get an option that isn't declared.

Examples:
  ftpconf.c.

References cfg_getnbool().

DLLIMPORT double __export cfg_getfloat | ( | cfg_t * | cfg,
|  | const char * | name
| ) |  |

Returns the value of a floating point option.

Parameters

  cfg | The configuration file context.
  name | The name of the option.

Returns
  The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding cfg_opt_t structure is returned. It is an error to try to get an option that isn't declared.

References cfg_getnfloat().

DLLIMPORT long int __export cfg_getint | ( | cfg_t * | cfg,
|  | const char * | name
| ) |  |

Returns the value of an integer option.

This is the same as calling cfg_getnint with index 0.

Parameters

  cfg | The configuration file context.
  name | The name of the option.

Returns
  The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding cfg_opt_t structure is returned. It is an error to try to get an option that isn't declared.

Examples:
  ftpconf.c, and reread.c.

References cfg_getnint().

DLLIMPORT cfg_bool_t __export cfg_getnbool | ( | cfg_t * | cfg,
|  | const char * | name,
|  | unsigned int | index
| ) |  |

Indexed version of cfg_getbool(), used for lists.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  index | Index of the value to get. Zero based.

See also
  cfg_getbool

References cfg_getopt(), and cfg_opt_getnbool().

Referenced by cfg_getbool().

DLLIMPORT double __export cfg_getnfloat | ( | cfg_t * | cfg,
|  | const char * | name,
|  | unsigned int | index
| ) |  |

Indexed version of cfg_getfloat(), used for lists.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  index | Index of the value to get. Zero based.

See also
  cfg_getfloat

References cfg_getopt(), and cfg_opt_getnfloat().

Referenced by cfg_getfloat().

DLLIMPORT long int __export cfg_getnint | ( | cfg_t * | cfg,
|  | const char * | name,
|  | unsigned int | index
| ) |  |

Indexed version of cfg_getint(), used for lists.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  index | Index of the value to get. Zero based.

See also
  cfg_getint

References cfg_getopt(), and cfg_opt_getnint().

Referenced by cfg_getint().

DLLIMPORT cfg_t* __export cfg_getnsec | ( | cfg_t * | cfg,
|  | const char * | name,
|  | unsigned int | index
| ) |  |

Indexed version of cfg_getsec(), used for sections with the CFGF_MULTI flag set.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  index | Index of the section to get. Zero based.

See also
  cfg_getsec

Examples:
  ftpconf.c, and reread.c.

References cfg_getopt(), and cfg_opt_getnsec().

Referenced by cfg_getsec().

DLLIMPORT char* __export cfg_getnstr | ( | cfg_t * | cfg,
|  | const char * | name,
|  | unsigned int | index
| ) |  |

Indexed version of cfg_getstr(), used for lists.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  index | Index of the value to get. Zero based.

See also
  cfg_getstr

Examples:
  ftpconf.c.

References cfg_getopt(), and cfg_opt_getnstr().

Referenced by cfg_getstr().

DLLIMPORT cfg_opt_t* __export cfg_getopt | ( | cfg_t * | cfg,
|  | const char * | name
| ) |  |

Return an option given it's name.

Parameters

  cfg | The configuration file context.
  name | The name of the option.

Returns
  Returns a pointer to the option. If the option isn't declared, libConfuse will print an error message and return 0.

References cfg_error(), cfg_getsec(), CFGF_IGNORE_UNKNOWN, CFGF_NOCASE, cfg_t::flags, cfg_t::name, cfg_opt_t::name, and cfg_t::opts.

Referenced by cfg_addlist(), cfg_getnbool(), cfg_getnfloat(), cfg_getnint(), cfg_getnsec(), cfg_getnstr(), cfg_gettsec(), cfg_rmnsec(), cfg_rmtsec(), cfg_set_print_func(), cfg_setlist(), cfg_setmulti(), cfg_setnbool(), cfg_setnfloat(), cfg_setnint(), cfg_setnstr(), and cfg_size().

DLLIMPORT void* __export cfg_getptr | ( | cfg_t * | cfg,
|  | const char * | name
| ) |  |

Returns the value of a user-defined option (void pointer).

Parameters

  cfg | The configuration file context.
  name | The name of the option.

Returns
  The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding cfg_opt_t structure is returned. It is an error to try to get an option that isn't declared.

DLLIMPORT cfg_t* __export cfg_getsec | ( | cfg_t * | cfg,
|  | const char * | name
| ) |  |

Returns the value of a section option.

The returned value is another cfg_t structure that can be used in following calls to cfg_getint, cfg_getstr or other get-functions.

Parameters

  cfg | The configuration file context.
  name | The name of the option.

Returns
  The requested section is returned. If no section is found with that name, 0 is returned. There can only be default values for section without the CFGF_MULTI flag set. It is an error to try to get a section that isn't declared.

References cfg_getnsec().

Referenced by cfg_getopt().

DLLIMPORT char* __export cfg_getstr | ( | cfg_t * | cfg,
|  | const char * | name
| ) |  |

Returns the value of a string option.

Parameters

  cfg | The configuration file context.
  name | The name of the option.

Returns
  The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding cfg_opt_t structure is returned. It is an error to try to get an option that isn't declared.

Examples:
  ftpconf.c, and reread.c.

References cfg_getnstr().

DLLIMPORT cfg_t* __export cfg_gettsec | ( | cfg_t * | cfg,
|  | const char * | name,
|  | const char * | title
| ) |  |

Return a section given the title, used for section with the CFGF_TITLE flag set.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  title | The title of this section. The CFGF_TITLE flag must have been set for this option.

See also
  cfg_getsec

References cfg_getopt(), and cfg_opt_gettsec().

DLLIMPORT int __export cfg_include | ( | cfg_t * | cfg,
|  | cfg_opt_t * | opt,
|  | int | argc,
|  | const char ** | argv
| ) |  |

Predefined include-function.

This function can be used in the options passed to cfg_init() to specify a function for including other configuration files in the parsing. For example: CFG_FUNC("include", &cfg_include)

Examples:
  ftpconf.c.

References cfg_error().

DLLIMPORT cfg_t* __export cfg_init | ( | cfg_opt_t * | opts,
|  | cfg_flag_t | flags
| ) |  |

Create and initialize a cfg_t structure.

This should be the first function called when setting up the parsing of a configuration file. The options passed in the first parameter is initialized using the CFG_* initializers. The last option in the option array must be CFG_END(), unless you like segmentation faults.

The options must no longer be defined in the same scope as where the cfg_xxx functions are used (since version 2.3).

CFG_IGNORE_UNKNOWN can be specified to use the "__unknown" option whenever an unknown option is parsed. Be sure to define an "__unknown" option in each scope that unknown parameters are allowed.

Call setlocale() before calling this function to localize handling of types, LC_CTYPE, and messages, LC_MESSAGES, since version 2.9:

        setlocale(LC_MESSAGES, "");
        setlocale(LC_CTYPE, "");

Parameters

  opts | An arrary of options
  flags | One or more flags (bitwise or'ed together). Currently only CFGF_NOCASE and CFGF_IGNORE_UNKNOWN are available. Use 0 if no flags are needed.

Returns
  A configuration context structure. This pointer is passed to almost all other functions as the first parameter.

Examples:
  ftpconf.c, reread.c, and simple.c.

References cfg_t::errfunc, cfg_t::filename, cfg_t::flags, cfg_t::line, cfg_t::name, and cfg_t::opts.

DLLIMPORT const char* __export cfg_name | ( | cfg_t * | cfg | ) |

Return the name of a section.

Parameters

  cfg | The configuration file context.

Returns
  Returns the title, or 0 if there is no title. This string should not be modified.

Examples:
  ftpconf.c.

References cfg_t::name.

DLLIMPORT cfg_bool_t __export cfg_opt_getnbool | ( | cfg_opt_t * | opt,
|  | unsigned int | index
| ) |  |

Returns the value of a boolean option, given a cfg_opt_t pointer.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  index | Index of the value to get. Zero based.

See also
  cfg_getnbool

References cfg_value_t::boolean, CFGT_BOOL, cfg_opt_t::simple_value, cfg_opt_t::type, and cfg_opt_t::values.

Referenced by cfg_getnbool(), and cfg_opt_nprint_var().

DLLIMPORT double __export cfg_opt_getnfloat | ( | cfg_opt_t * | opt,
|  | unsigned int | index
| ) |  |

Returns the value of a floating point option, given a cfg_opt_t pointer.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  index | Index of the value to get. Zero based.

See also
  cfg_getnfloat

References CFGT_FLOAT, cfg_value_t::fpnumber, cfg_opt_t::simple_value, cfg_opt_t::type, and cfg_opt_t::values.

Referenced by cfg_getnfloat(), and cfg_opt_nprint_var().

DLLIMPORT signed long __export cfg_opt_getnint | ( | cfg_opt_t * | opt,
|  | unsigned int | index
| ) |  |

Returns the value of an integer option, given a cfg_opt_t pointer.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  index | Index of the value to get. Zero based.

See also
  cfg_getnint

Examples:
  ftpconf.c.

References CFGT_INT, cfg_value_t::number, cfg_opt_t::simple_value, cfg_opt_t::type, and cfg_opt_t::values.

Referenced by cfg_getnint(), and cfg_opt_nprint_var().

DLLIMPORT cfg_t* __export cfg_opt_getnsec | ( | cfg_opt_t * | opt,
|  | unsigned int | index
| ) |  |

Returns the value of a section option, given a cfg_opt_t pointer.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  index | Index of the value to get. Zero based.

See also
  cfg_getnsec

Examples:
  ftpconf.c.

References CFGT_SEC, cfg_value_t::section, cfg_opt_t::type, and cfg_opt_t::values.

Referenced by cfg_getnsec(), cfg_opt_gettsec(), cfg_opt_print_indent(), and cfg_opt_rmtsec().

DLLIMPORT char* __export cfg_opt_getnstr | ( | cfg_opt_t * | opt,
|  | unsigned int | index
| ) |  |

Returns the value of a string option, given a cfg_opt_t pointer.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  index | Index of the value to get. Zero based.

See also
  cfg_getnstr

References CFGT_STR, cfg_opt_t::simple_value, cfg_value_t::string, cfg_opt_t::type, and cfg_opt_t::values.

Referenced by cfg_getnstr(), and cfg_opt_nprint_var().

DLLIMPORT cfg_t* __export cfg_opt_gettsec | ( | cfg_opt_t * | opt,
|  | const char * | title
| ) |  |

Returns the value of a section option, given a cfg_opt_t pointer and the title.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  title | The title of this section. The CFGF_TITLE flag must have been set for this option.

See also
  cfg_gettsec

References cfg_opt_getnsec(), cfg_opt_size(), CFGF_NOCASE, CFGF_TITLE, cfg_opt_t::flags, and cfg_t::title.

Referenced by cfg_gettsec().

DLLIMPORT const char* __export cfg_opt_name | ( | cfg_opt_t * | opt | ) |

Return the name of an option.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())

Returns
  Returns the title, or 0 if there is no title. This string should not be modified.

Examples:
  ftpconf.c.

References cfg_opt_t::name.

DLLIMPORT int __export cfg_opt_nprint_var | ( | cfg_opt_t * | opt,
|  | unsigned int | index,
|  | FILE * | fp
| ) |  |

Default value print function.

Print only the value of a given option. Does not handle sections or functions. Use cfg_opt_print to print the whole assignment ("option = value"), or cfg_print to print the whole config file.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  index | The index in the option value array that should be printed
  fp | File stream to print to.

See also
  cfg_print, cfg_opt_print

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_opt_getnbool(), cfg_opt_getnfloat(), cfg_opt_getnint(), cfg_opt_getnstr(), CFG_SUCCESS, CFGT_BOOL, CFGT_FLOAT, CFGT_FUNC, CFGT_INT, CFGT_PTR, CFGT_SEC, CFGT_STR, and cfg_opt_t::type.

Referenced by cfg_opt_print_indent().

DLLIMPORT int __export cfg_opt_print | ( | cfg_opt_t * | opt,
|  | FILE * | fp
| ) |  |

Print an option and its value to a file.

If a print callback function is specified for the option, it is used instead of cfg_opt_nprint_var.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  fp | File stream to print to.

See also
  cfg_print_func_t

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_opt_print_indent().

DLLIMPORT int __export cfg_opt_print_indent | ( | cfg_opt_t * | opt,
|  | FILE * | fp,
|  | int | indent
| ) |  |

Print an option and its value to a file.

Same as cfg_opt_print, but with the indentation level specified.

See also
  cfg_opt_print

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_opt_getnsec(), cfg_opt_nprint_var(), cfg_opt_size(), cfg_print_indent(), CFG_SUCCESS, cfg_title(), CFGF_LIST, CFGF_TITLE, CFGT_FUNC, CFGT_SEC, CFGT_STR, cfg_opt_t::flags, cfg_opt_t::name, cfg_opt_t::nvalues, cfg_opt_t::pf, cfg_opt_t::simple_value, cfg_value_t::string, cfg_opt_t::type, and cfg_opt_t::values.

Referenced by cfg_opt_print(), and cfg_print_indent().

DLLIMPORT int __export cfg_opt_rmnsec | ( | cfg_opt_t * | opt,
|  | unsigned int | index
| ) |  |

Removes and frees a config section, given a cfg_opt_t pointer.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  index | Index of the section to remove. Zero based.

See also
  cfg_rmnsec

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_free(), cfg_opt_size(), CFG_SUCCESS, CFGT_SEC, cfg_opt_t::nvalues, cfg_value_t::section, cfg_opt_t::type, and cfg_opt_t::values.

Referenced by cfg_opt_rmtsec(), and cfg_rmnsec().

DLLIMPORT int __export cfg_opt_rmtsec | ( | cfg_opt_t * | opt,
|  | const char * | title
| ) |  |

Removes and frees a config section, given a cfg_opt_t pointer and the title.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  title | The title of this section. The CFGF_TITLE flag must have been set for this option.

See also
  cfg_rmtsec

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_opt_getnsec(), cfg_opt_rmnsec(), cfg_opt_size(), CFGF_NOCASE, CFGF_TITLE, cfg_opt_t::flags, and cfg_t::title.

Referenced by cfg_rmtsec().

DLLIMPORT cfg_print_func_t __export cfg_opt_set_print_func | ( | cfg_opt_t * | opt,
|  | cfg_print_func_t | pf
| ) |  |

Set a print callback function for an option.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  pf | The print function callback.

See also
  cfg_print_func_t

References cfg_opt_t::pf.

Referenced by cfg_set_print_func().

DLLIMPORT int cfg_opt_setmulti | ( | cfg_t * | cfg,
|  | cfg_opt_t * | opt,
|  | unsigned int | nvalues,
|  | char ** | values
| ) |  |

Set an option (create an instance of an option).

Parameters

  cfg | The configuration file context.
  opt | The option definition.
  nvalues | The number of values to set for the option.
  values | The value(s) for the option.

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_free_value(), cfg_setopt(), CFG_SUCCESS, cfg_opt_t::nvalues, and cfg_opt_t::values.

Referenced by cfg_setmulti().

DLLIMPORT int __export cfg_opt_setnbool | ( | cfg_opt_t * | opt,
|  | cfg_bool_t | value,
|  | unsigned int | index
| ) |  |

Set a value of a boolean option.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  value | The value to set.
  index | The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set.

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_value_t::boolean, CFG_SUCCESS, CFGT_BOOL, and cfg_opt_t::type.

Referenced by cfg_setnbool().

DLLIMPORT int __export cfg_opt_setnfloat | ( | cfg_opt_t * | opt,
|  | double | value,
|  | unsigned int | index
| ) |  |

Set a value of a floating point option.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  value | The value to set.
  index | The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set.

Returns
  POSIX OK(0), or non-zero on failure.

References CFG_SUCCESS, CFGT_FLOAT, cfg_value_t::fpnumber, and cfg_opt_t::type.

Referenced by cfg_setnfloat().

DLLIMPORT int __export cfg_opt_setnint | ( | cfg_opt_t * | opt,
|  | long int | value,
|  | unsigned int | index
| ) |  |

Set a value of an integer option.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  value | The value to set.
  index | The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set.

Returns
  POSIX OK(0), or non-zero on failure.

References CFG_SUCCESS, CFGT_INT, cfg_value_t::number, and cfg_opt_t::type.

Referenced by cfg_setnint().

DLLIMPORT int __export cfg_opt_setnstr | ( | cfg_opt_t * | opt,
|  | const char * | value,
|  | unsigned int | index
| ) |  |

Set a value of a string option.

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())
  value | The value to set. Memory for the string is allocated and the value is copied. Any previous string value is freed.
  index | The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set.

Returns
  POSIX OK(0), or non-zero on failure.

References CFG_SUCCESS, CFGT_STR, cfg_value_t::string, and cfg_opt_t::type.

Referenced by cfg_setnstr().

DLLIMPORT unsigned int __export cfg_opt_size | ( | cfg_opt_t * | opt | ) |

Return the number of values this option has.

If no default value is given for the option and no value was found in the config file, 0 will be returned (ie, the option value is not set at all).

Parameters

  opt | The option structure (eg, as returned from cfg_getopt())

Examples:
  ftpconf.c.

References cfg_opt_t::nvalues.

Referenced by cfg_opt_gettsec(), cfg_opt_print_indent(), cfg_opt_rmnsec(), cfg_opt_rmtsec(), and cfg_size().

DLLIMPORT int __export cfg_parse | ( | cfg_t * | cfg,
|  | const char * | filename
| ) |  |

Parse a configuration file.

Tilde expansion is performed on the filename before it is opened. After a configuration file has been initialized (with cfg_init()) and parsed (with cfg_parse()), the values can be read with the cfg_getXXX functions.

Parameters

  cfg | The configuration file context as returned from cfg_init().
  filename | The name of the file to parse.

Returns
  On success, CFG_SUCCESS is returned. If the file couldn't be opened for reading, CFG_FILE_ERROR is returned. On all other errors, CFG_PARSE_ERROR is returned and cfg_error() was called with a descriptive error message.

Examples:
  ftpconf.c, reread.c, and simple.c.

References cfg_parse_fp(), cfg_searchpath(), cfg_tilde_expand(), cfg_t::filename, and cfg_t::path.

DLLIMPORT int __export cfg_parse_boolean | ( | const char * | s | ) |

Parse a boolean option string.

Accepted "true" values are "true", "on" and "yes", and accepted "false" values are "false", "off" and "no".

Returns
  Returns 1 or 0 (true/false) if the string was parsed correctly, or -1 if an error occurred.

Referenced by cfg_setopt().

DLLIMPORT int __export cfg_parse_buf | ( | cfg_t * | cfg,
|  | const char * | buf
| ) |  |

Same as cfg_parse() above, but takes a character buffer as argument.

Parameters

  cfg | The configuration file context as returned from cfg_init().
  buf | A zero-terminated string with configuration directives.

See also
  cfg_parse()

Returns
  POSIX OK(0), or non-zero on failure.

Examples:
  reread.c.

References CFG_SUCCESS, cfg_t::filename, and cfg_t::line.

DLLIMPORT int __export cfg_parse_fp | ( | cfg_t * | cfg,
|  | FILE * | fp
| ) |  |

Same as cfg_parse() above, but takes an already opened file as argument.

Reading begins at the current position. After parsing, the position is not reset. The caller is responsible for closing the file.

Parameters

  cfg | The configuration file context as returned from cfg_init().
  fp | An open file stream.

See also
  cfg_parse()

Returns
  POSIX OK(0), or non-zero on failure.

References CFG_SUCCESS, cfg_t::filename, and cfg_t::line.

Referenced by cfg_parse().

DLLIMPORT int __export cfg_print | ( | cfg_t * | cfg,
|  | FILE * | fp
| ) |  |

Print the options and values to a file.

Note that options in any included file are expanded and printed directly to the file. Option values given with environment variables in the parsed input are also printed expanded. This means that if you parse a configuration file you can't expect that the output from this function is identical to the initial file.

Parameters

  cfg | The configuration file context.
  fp | File stream to print to, use stdout to print to the screen.

See also
  cfg_print_func_t, cfg_set_print_func

Returns
  POSIX OK(0), or non-zero on failure.

Examples:
  simple.c.

References cfg_print_indent().

DLLIMPORT int __export cfg_print_indent | ( | cfg_t * | cfg,
|  | FILE * | fp,
|  | int | indent
| ) |  |

Print the options and values to a file.

Same as cfg_print, but with the indentation level specified.

See also
  cfg_print

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_opt_print_indent(), CFG_SUCCESS, cfg_opt_t::name, and cfg_t::opts.

Referenced by cfg_opt_print_indent(), and cfg_print().

DLLIMPORT int __export cfg_rmnsec | ( | cfg_t * | cfg,
|  | const char * | name,
|  | unsigned int | index
| ) |  |

Indexed version of cfg_rmsec(), used for CFGF_MULTI sections.

Parameters

  cfg | The configuration file context.
  name | The name of the section.
  index | Index of the section to remove. Zero based.

See also
  cfg_rmsec

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_getopt(), and cfg_opt_rmnsec().

Referenced by cfg_rmsec().

DLLIMPORT int __export cfg_rmsec | ( | cfg_t * | cfg,
|  | const char * | name
| ) |  |

Removes and frees a config section.

This is the same as calling cfg_rmnsec with index 0.

Parameters

  cfg | The configuration file context.
  name | The name of the section.

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_rmnsec().

DLLIMPORT int __export cfg_rmtsec | ( | cfg_t * | cfg,
|  | const char * | name,
|  | const char * | title
| ) |  |

Removes and frees a section given the title, used for section with the CFGF_TITLE flag set.

Parameters

  cfg | The configuration file context.
  name | The name of the section.
  title | The title of this section. The CFGF_TITLE flag must have been set for this option.

See also
  cfg_rmsec

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_getopt(), and cfg_opt_rmtsec().

DLLIMPORT char* __export cfg_searchpath | ( | cfg_searchpath_t * | path,
|  | const char * | file
| ) |  |

Search the linked-list of cfg_searchpath_t for the specified file.

If not NULL, the return value is freshly allocated and and should be freed by the caller.

Parameters

  path | The linked list of cfg_searchpath_t structs, each containg a directory to be searched
  file | The file for which to search

Returns
  If the file is found on the searchpath then the full path to the file is returned. If not found, NULL is returned.

Referenced by cfg_parse().

DLLIMPORT cfg_errfunc_t __export cfg_set_error_function | ( | cfg_t * | cfg,
|  | cfg_errfunc_t | errfunc
| ) |  |

Install a user-defined error reporting function.

Returns
  The old error reporting function is returned.

References cfg_t::errfunc.

DLLIMPORT cfg_print_func_t __export cfg_set_print_func | ( | cfg_t * | cfg,
|  | const char * | name,
|  | cfg_print_func_t | pf
| ) |  |

Set a print callback function for an option given its name.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  pf | The print callback function.

See also
  cfg_print_func_t

References cfg_getopt(), and cfg_opt_set_print_func().

DLLIMPORT cfg_validate_callback_t __export cfg_set_validate_func | ( | cfg_t * | cfg,
|  | const char * | name,
|  | cfg_validate_callback_t | vf
| ) |  |

Register a validating callback function for an option.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  vf | The validating callback function.

See also
  cfg_validate_callback_t

Examples:
  ftpconf.c.

References cfg_t::flags, cfg_t::opts, and cfg_opt_t::validcb.

DLLIMPORT int __export cfg_setbool | ( | cfg_t * | cfg,
|  | const char * | name,
|  | cfg_bool_t | value
| ) |  |

Set the value of a boolean option given its name.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  value | The value to set. If the option is a list (the CFGF_LIST flag is set), only the first value (with index 0) is set.

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_setnbool().

DLLIMPORT int __export cfg_setfloat | ( | cfg_t * | cfg,
|  | const char * | name,
|  | double | value
| ) |  |

Set the value of a floating point option given its name.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  value | The value to set. If the option is a list (the CFGF_LIST flag is set), only the first value (with index 0) is set.

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_setnfloat().

DLLIMPORT int __export cfg_setint | ( | cfg_t * | cfg,
|  | const char * | name,
|  | long int | value
| ) |  |

Set the value of an integer option given its name.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  value | The value to set. If the option is a list (the CFGF_LIST flag is set), only the first value (with index 0) is set.

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_setnint().

DLLIMPORT int __export cfg_setlist | ( | cfg_t * | cfg,
|  | const char * | name,
|  | unsigned int | nvalues,
|  |  | ...
| ) |  |

Set values for a list option.

All existing values are replaced with the new ones.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  nvalues | Number of values to set.
  ... | The values to set, the type must match the type of the option and the number of values must be equal to the nvalues parameter.

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_free_value(), cfg_getopt(), CFG_SUCCESS, CFGF_LIST, and cfg_opt_t::flags.

DLLIMPORT int cfg_setmulti | ( | cfg_t * | cfg,
|  | const char * | name,
|  | unsigned int | nvalues,
|  | char ** | values
| ) |  |

Set an option (create an instance of an option).

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  nvalues | The number of values to set for the option.
  values | The value(s) for the option.

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_getopt(), and cfg_opt_setmulti().

DLLIMPORT int __export cfg_setnbool | ( | cfg_t * | cfg,
|  | const char * | name,
|  | cfg_bool_t | value,
|  | unsigned int | index
| ) |  |

Set a value of a boolean option given its name and index.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  value | The value to set.
  index | The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set.

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_getopt(), and cfg_opt_setnbool().

Referenced by cfg_setbool().

DLLIMPORT int __export cfg_setnfloat | ( | cfg_t * | cfg,
|  | const char * | name,
|  | double | value,
|  | unsigned int | index
| ) |  |

Set a value of a floating point option given its name and index.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  value | The value to set.
  index | The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set.

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_getopt(), and cfg_opt_setnfloat().

Referenced by cfg_setfloat().

DLLIMPORT int __export cfg_setnint | ( | cfg_t * | cfg,
|  | const char * | name,
|  | long int | value,
|  | unsigned int | index
| ) |  |

Set a value of an integer option given its name and index.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  value | The value to set.
  index | The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set.

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_getopt(), and cfg_opt_setnint().

Referenced by cfg_setint().

DLLIMPORT int __export cfg_setnstr | ( | cfg_t * | cfg,
|  | const char * | name,
|  | const char * | value,
|  | unsigned int | index
| ) |  |

Set a value of a boolean option given its name and index.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  value | The value to set. Memory for the string is allocated and the value is copied. Any privious string value is freed.
  index | The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set.

Returns
  POSIX OK(0), or non-zero on failure.

References cfg_getopt(), and cfg_opt_setnstr().

Referenced by cfg_setstr().

DLLIMPORT cfg_value_t* cfg_setopt | ( | cfg_t * | cfg,
|  | cfg_opt_t * | opt,
|  | const char * | value
| ) |  |

Set an option (create an instance of an option).

Parameters

  cfg | The configuration file context.
  opt | The option definition.
  value | The initial value for the option.

Returns
  Returns a pointer to the value object.

References cfg_value_t::boolean, cfg_error(), cfg_free(), cfg_free_value(), cfg_parse_boolean(), CFGF_LIST, CFGF_MULTI, CFGF_NO_TITLE_DUPES, CFGF_NOCASE, CFGF_TITLE, CFGT_BOOL, CFGT_FLOAT, CFGT_INT, CFGT_PTR, CFGT_SEC, CFGT_STR, cfg_t::errfunc, cfg_t::filename, cfg_t::flags, cfg_opt_t::flags, cfg_value_t::fpnumber, cfg_t::line, cfg_t::name, cfg_opt_t::name, cfg_value_t::number, cfg_opt_t::nvalues, cfg_t::opts, cfg_opt_t::parsecb, cfg_t::path, cfg_value_t::ptr, cfg_value_t::section, cfg_opt_t::simple_value, cfg_value_t::string, cfg_opt_t::subopts, cfg_t::title, cfg_opt_t::type, and cfg_opt_t::values.

Referenced by cfg_opt_setmulti().

DLLIMPORT int __export cfg_setstr | ( | cfg_t * | cfg,
|  | const char * | name,
|  | const char * | value
| ) |  |

Set the value of a string option given its name.

Parameters

  cfg | The configuration file context.
  name | The name of the option.
  value | The value to set. Memory for the string is allocated and the value is copied. Any previous string value is freed. If the option is a list (the CFGF_LIST flag is set), only the first value (with index 0) is set.

Returns
  POSIX OK(0), or non-zero on failure.

Examples:
  simple.c.

References cfg_setnstr().

DLLIMPORT unsigned int __export cfg_size | ( | cfg_t * | cfg,
|  | const char * | name
| ) |  |

Return the number of values this option has.

If no default value is given for the option and no value was found in the config file, 0 will be returned (ie, the option value is not set at all).

Note that there is no way to *not* specify a default value for integers, floats and booleans. Ie, they always have default values (since 0 or NULL is a valid integer/float/boolean value). Only strings and lists may have no default value.

Parameters

  cfg | The configuration file context.
  name | The name of the option.

Examples:
  ftpconf.c, and reread.c.

References cfg_getopt(), and cfg_opt_size().

DLLIMPORT char* __export cfg_tilde_expand | ( | const char * | filename | ) |

Does tilde expansion (~ -> $HOME) on the filename.

Returns
  The expanded filename is returned. If a ~user was not found, the original filename is returned. In any case, a dynamically allocated string is returned, which should be free()'d by the caller.

Referenced by cfg_add_searchpath(), and cfg_parse().

DLLIMPORT const char* __export cfg_title | ( | cfg_t * | cfg | ) |

Return the title of a section.

Parameters

  cfg | The configuration file context.

Returns
  Returns the title, or 0 if there is no title. This string should not be modified.

References cfg_t::title.

Referenced by cfg_opt_print_indent().