confuse.h - Man Page

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

#define CFGF_NONE   (0)
Flags​.
#define CFGF_MULTI   (1 <<  0)
option may be specified multiple times (only applies to sections)
#define CFGF_LIST   (1 <<  1)
option is a list
#define CFGF_NOCASE   (1 <<  2)
configuration file is case insensitive
#define CFGF_TITLE   (1 <<  3)
option has a title (only applies to sections)
#define CFGF_NODEFAULT   (1 <<  4)
option has no default value
#define CFGF_NO_TITLE_DUPES   (1 <<  5)
multiple section titles must be unique (duplicates raises an error, only applies to sections)
#define CFGF_RESET   (1 <<  6)
used internally to clear an option's values before (re)setting
#define CFGF_DEFINIT   (1 <<  7)
used internally, the option's default value has been initialized
#define CFGF_IGNORE_UNKNOWN   (1 <<  8)
ignore unknown options in configuration files
#define CFGF_DEPRECATED   (1 <<  9)
option is deprecated and should be ignored​.
#define CFGF_DROP   (1 << 10)
option should be dropped after parsing
#define CFGF_COMMENTS   (1 << 11)
Enable option annotation/comments support​.
#define CFGF_MODIFIED   (1 << 12)
option has been changed from its default value
#define CFGF_KEYSTRVAL   (1 << 13)
section has free-form key=value string options created when parsing file
#define CFGF_USE_INCLUDE_FUNCTION   (1 << 14)
add an include() function to the section's options
#define CFGF_JSON_LISTS   (1 << 15)
accept and print JSON-style [ ] as an alternative to { } for lists
#define CFG_SUCCESS   0
Success, all OK (POSIX '0')
#define CFG_FAIL   -1
Generic failure​.
#define CFG_FILE_ERROR   -1
Error opening the configuration file​.
#define CFG_PARSE_ERROR   1
Error parsing the configuration​.
#define CFG_STR(name,  def,  flags)     __CFG_STR(name, def, flags, NULL, NULL)
Initialize a string option​.
#define CFG_RAWSEC(_name,  _flags)
Initialize a raw section option​.
#define CFG_STR_LIST(name,  def,  flags)     __CFG_STR_LIST(name, def, flags, NULL, NULL)
Initialize a string list option​.
#define CFG_STR_CB(name,  def,  flags,  cb)     __CFG_STR(name, def, flags, NULL, 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, NULL, cb)
Initialize a string list option with a value parsing callback​.
#define CFG_SIMPLE_STR(name,  svalue)     __CFG_STR(name, NULL, CFGF_NONE, svalue, NULL)
Initialize a 'simple' string option​.
#define CFG_INT(name,  def,  flags)     __CFG_INT(name, def, flags, NULL, NULL)
Initialize an integer option​.
#define CFG_INT_LIST(name,  def,  flags)     __CFG_INT_LIST(name, def, flags, NULL, NULL)
Initialize an integer list option​.
#define CFG_INT_CB(name,  def,  flags,  cb)     __CFG_INT(name, def, flags, NULL, 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, NULL, cb)
Initialize an integer list option with a value parsing callback​.
#define CFG_SIMPLE_INT(name,  svalue)     __CFG_INT(name, 0, CFGF_NONE, svalue, NULL)
Initialize a 'simple' integer option (see documentation for CFG_SIMPLE_STR for more information)​.
#define CFG_INT64(name,  def,  flags)   __CFG_INT64(name, def, flags, NULL, NULL)
Initialize a 64-bit signed integer option​.
#define CFG_INT64_LIST(name,  def,  flags)   __CFG_INT64_LIST(name, def, flags, NULL, NULL)
Initialize a 64-bit signed integer list option​.
#define CFG_INT64_CB(name,  def,  flags,  cb)   __CFG_INT64(name, def, flags, NULL, cb)
Initialize a 64-bit signed integer option with a parsing callback​.
#define CFG_INT64_LIST_CB(name,  def,  flags,  cb)   __CFG_INT64_LIST(name, def, flags, NULL, cb)
Initialize a 64-bit signed integer list option with a parsing callback​.
#define CFG_SIMPLE_INT64(name,  svalue)   __CFG_INT64(name, 0, CFGF_NONE, svalue, NULL)
Initialize a 'simple' 64-bit signed integer option, svalue is an int64_t *​.
#define CFG_UINT32(name,  def,  flags)   __CFG_UINT32(name, def, flags, NULL, NULL)
Initialize a 32-bit unsigned integer option​.
#define CFG_UINT32_LIST(name,  def,  flags)   __CFG_UINT32_LIST(name, def, flags, NULL, NULL)
Initialize a 32-bit unsigned integer list option​.
#define CFG_UINT32_CB(name,  def,  flags,  cb)   __CFG_UINT32(name, def, flags, NULL, cb)
Initialize a 32-bit unsigned integer option with a parsing callback​.
#define CFG_UINT32_LIST_CB(name,  def,  flags,  cb)   __CFG_UINT32_LIST(name, def, flags, NULL, cb)
Initialize a 32-bit unsigned integer list option with a parsing callback​.
#define CFG_SIMPLE_UINT32(name,  svalue)   __CFG_UINT32(name, 0, CFGF_NONE, svalue, NULL)
Initialize a 'simple' 32-bit unsigned integer option, svalue is a uint32_t *​.
#define CFG_UINT64(name,  def,  flags)   __CFG_UINT64(name, def, flags, NULL, NULL)
Initialize a 64-bit unsigned integer option​.
#define CFG_UINT64_LIST(name,  def,  flags)   __CFG_UINT64_LIST(name, def, flags, NULL, NULL)
Initialize a 64-bit unsigned integer list option​.
#define CFG_UINT64_CB(name,  def,  flags,  cb)   __CFG_UINT64(name, def, flags, NULL, cb)
Initialize a 64-bit unsigned integer option with a parsing callback​.
#define CFG_UINT64_LIST_CB(name,  def,  flags,  cb)   __CFG_UINT64_LIST(name, def, flags, NULL, cb)
Initialize a 64-bit unsigned integer list option with a parsing callback​.
#define CFG_SIMPLE_UINT64(name,  svalue)   __CFG_UINT64(name, 0, CFGF_NONE, svalue, NULL)
Initialize a 'simple' 64-bit unsigned integer option, svalue is a uint64_t *​.
#define CFG_INT8(name,  def,  flags)   __CFG_INT8(name, def, flags, NULL, NULL)
Initialize an 8-bit signed integer option​.
#define CFG_INT8_LIST(name,  def,  flags)   __CFG_INT8_LIST(name, def, flags, NULL, NULL)
Initialize an 8-bit signed integer list option​.
#define CFG_INT8_CB(name,  def,  flags,  cb)   __CFG_INT8(name, def, flags, NULL, cb)
Initialize an 8-bit signed integer option with a parsing callback​.
#define CFG_INT8_LIST_CB(name,  def,  flags,  cb)   __CFG_INT8_LIST(name, def, flags, NULL, cb)
Initialize an 8-bit signed integer list option with a parsing callback​.
#define CFG_SIMPLE_INT8(name,  svalue)   __CFG_INT8(name, 0, CFGF_NONE, svalue, NULL)
Initialize a 'simple' 8-bit signed integer option, svalue is an int8_t *​.
#define CFG_INT16(name,  def,  flags)   __CFG_INT16(name, def, flags, NULL, NULL)
Initialize a 16-bit signed integer option​.
#define CFG_INT16_LIST(name,  def,  flags)   __CFG_INT16_LIST(name, def, flags, NULL, NULL)
Initialize a 16-bit signed integer list option​.
#define CFG_INT16_CB(name,  def,  flags,  cb)   __CFG_INT16(name, def, flags, NULL, cb)
Initialize a 16-bit signed integer option with a parsing callback​.
#define CFG_INT16_LIST_CB(name,  def,  flags,  cb)   __CFG_INT16_LIST(name, def, flags, NULL, cb)
Initialize a 16-bit signed integer list option with a parsing callback​.
#define CFG_SIMPLE_INT16(name,  svalue)   __CFG_INT16(name, 0, CFGF_NONE, svalue, NULL)
Initialize a 'simple' 16-bit signed integer option, svalue is an int16_t *​.
#define CFG_INT32(name,  def,  flags)   __CFG_INT32(name, def, flags, NULL, NULL)
Initialize a 32-bit signed integer option​.
#define CFG_INT32_LIST(name,  def,  flags)   __CFG_INT32_LIST(name, def, flags, NULL, NULL)
Initialize a 32-bit signed integer list option​.
#define CFG_INT32_CB(name,  def,  flags,  cb)   __CFG_INT32(name, def, flags, NULL, cb)
Initialize a 32-bit signed integer option with a parsing callback​.
#define CFG_INT32_LIST_CB(name,  def,  flags,  cb)   __CFG_INT32_LIST(name, def, flags, NULL, cb)
Initialize a 32-bit signed integer list option with a parsing callback​.
#define CFG_SIMPLE_INT32(name,  svalue)   __CFG_INT32(name, 0, CFGF_NONE, svalue, NULL)
Initialize a 'simple' 32-bit signed integer option, svalue is an int32_t *​.
#define CFG_UINT8(name,  def,  flags)   __CFG_UINT8(name, def, flags, NULL, NULL)
Initialize an 8-bit unsigned integer option​.
#define CFG_UINT8_LIST(name,  def,  flags)   __CFG_UINT8_LIST(name, def, flags, NULL, NULL)
Initialize an 8-bit unsigned integer list option​.
#define CFG_UINT8_CB(name,  def,  flags,  cb)   __CFG_UINT8(name, def, flags, NULL, cb)
Initialize an 8-bit unsigned integer option with a parsing callback​.
#define CFG_UINT8_LIST_CB(name,  def,  flags,  cb)   __CFG_UINT8_LIST(name, def, flags, NULL, cb)
Initialize an 8-bit unsigned integer list option with a parsing callback​.
#define CFG_SIMPLE_UINT8(name,  svalue)   __CFG_UINT8(name, 0, CFGF_NONE, svalue, NULL)
Initialize a 'simple' 8-bit unsigned integer option, svalue is a uint8_t *​.
#define CFG_UINT16(name,  def,  flags)   __CFG_UINT16(name, def, flags, NULL, NULL)
Initialize a 16-bit unsigned integer option​.
#define CFG_UINT16_LIST(name,  def,  flags)   __CFG_UINT16_LIST(name, def, flags, NULL, NULL)
Initialize a 16-bit unsigned integer list option​.
#define CFG_UINT16_CB(name,  def,  flags,  cb)   __CFG_UINT16(name, def, flags, NULL, cb)
Initialize a 16-bit unsigned integer option with a parsing callback​.
#define CFG_UINT16_LIST_CB(name,  def,  flags,  cb)   __CFG_UINT16_LIST(name, def, flags, NULL, cb)
Initialize a 16-bit unsigned integer list option with a parsing callback​.
#define CFG_SIMPLE_UINT16(name,  svalue)   __CFG_UINT16(name, 0, CFGF_NONE, svalue, NULL)
Initialize a 'simple' 16-bit unsigned integer option, svalue is a uint16_t *​.
#define CFG_FLOAT(name,  def,  flags)     __CFG_FLOAT(name, def, flags, NULL, NULL)
Initialize a floating point option​.
#define CFG_FLOAT_LIST(name,  def,  flags)     __CFG_FLOAT_LIST(name, def, flags, NULL, NULL)
Initialize a floating point list option​.
#define CFG_FLOAT_CB(name,  def,  flags,  cb)     __CFG_FLOAT(name, def, flags, NULL, 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, NULL, 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, NULL)
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, NULL, NULL)
Initialize a boolean option​.
#define CFG_BOOL_LIST(name,  def,  flags)     __CFG_BOOL_LIST(name, def, flags, NULL, NULL)
Initialize a boolean list option​.
#define CFG_BOOL_CB(name,  def,  flags,  cb)     __CFG_BOOL(name, def, flags, NULL, 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, NULL, 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, NULL)
Initialize a 'simple' boolean option (see documentation for CFG_SIMPLE_STR for more information)​.
#define CFG_SEC(_name,  _opts,  _flags)
Initialize a section​.
#define CFG_FUNC(_name,  _func)
Initialize a function​.
#define CFG_PTR_CB(name,  def,  flags,  parsecb,  freecb)     __CFG_PTR(name, def, flags, NULL, parsecb, freecb)
Initialize a user-defined option​.
#define CFG_PTR_LIST_CB(name,  def,  flags,  parsecb,  freecb)     __CFG_PTR(name, def, flags | CFGF_LIST, NULL, parsecb, freecb)
Initialize a list of user-defined options​.
#define CFG_END()     { ​.type = CFGT_NONE, }
Terminate list of options​.

typedef enum cfg_type_t cfg_type_t
A fundamental option type, one of the CFGT_* values​.
typedef union cfg_value_t cfg_value_t
A fundamental option value​.
typedef union cfg_simple_t cfg_simple_t
Pointer to a user variable, for CFG_SIMPLE_* options​.
typedef struct cfg_opt_t cfg_opt_t
Describes a single configuration option​.
typedef struct cfg_t cfg_t
A configuration context (the file or a section)
typedef struct cfg_defvalue_t cfg_defvalue_t
Holds an option's default value​.
typedef int cfg_flag_t
Option flags, a bitwise OR of CFGF_* values​.
typedef struct cfg_searchpath_t cfg_searchpath_t
An entry in the include search path​.
typedef int(* cfg_func_t) (cfg_t *cfg, cfg_opt_t *opt, int argc, const char **argv)
Function prototype used by CFGT_FUNC options​.
typedef void(* cfg_print_func_t) (cfg_opt_t *opt, unsigned int index, FILE *fp)
Function prototype used by the cfg_print_ functions​.
typedef int(* cfg_callback_t) (cfg_t *cfg, cfg_opt_t *opt, const char *value, void *result)
Value parsing callback prototype​.
typedef int(* cfg_validate_callback_t) (cfg_t *cfg, cfg_opt_t *opt)
Validating callback prototype​.
typedef int(* cfg_validate_callback2_t) (cfg_t *cfg, cfg_opt_t *opt, void *value)
Validating callback2 prototype​.
typedef void(* cfg_free_func_t) (void *value)
User-defined memory release function for CFG_PTR values​.
typedef void(* cfg_errfunc_t) (cfg_t *cfg, const char *fmt, va_list ap)
Error reporting function​.
typedef int(* cfg_print_filter_func_t) (cfg_t *cfg, cfg_opt_t *opt)
Print filter function​.

enum cfg_type_t {  }
Fundamental option types​.
enum cfg_bool_t
Boolean values​.

DLLIMPORT cfg_t *__export cfg_init (cfg_opt_t *opts, cfg_flag_t flags)
Create and initialize a cfg_t structure​.
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​.
DLLIMPORT char *__export cfg_searchpath (cfg_searchpath_t *path, const char *file)
Search the linked-list of cfg_searchpath_t for the specified file​.
DLLIMPORT int __export cfg_parse (cfg_t *cfg, const char *filename)
Parse a configuration file​.
DLLIMPORT int __export cfg_parse_fp (cfg_t *cfg, FILE *fp)
Same as cfg_parse() above, but takes an already opened file as argument​.
DLLIMPORT int __export cfg_parse_buf (cfg_t *cfg, const char *buf)
Same as cfg_parse() above, but takes a character buffer as argument​.
DLLIMPORT int __export cfg_free_value (cfg_opt_t *opt)
Free the memory allocated for the values of a given option​.
DLLIMPORT int __export cfg_free (cfg_t *cfg)
Free a cfg_t context​.
DLLIMPORT cfg_errfunc_t __export cfg_set_error_function (cfg_t *cfg, cfg_errfunc_t errfunc)
Install a user-defined error reporting function​.
DLLIMPORT void __export cfg_error (cfg_t *cfg, const char *fmt,​.​.​.)
Show a parser error​.
DLLIMPORT char *__export cfg_opt_getcomment (cfg_opt_t *opt)
Returns the option comment​.
DLLIMPORT char *__export cfg_getcomment (cfg_t *cfg, const char *name)
Returns the option comment​.
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​.
DLLIMPORT long int __export cfg_getnint (cfg_t *cfg, const char *name, unsigned int index)
Indexed version of cfg_getint(), used for lists​.
DLLIMPORT long int __export cfg_getint (cfg_t *cfg, const char *name)
Returns the value of an integer option​.
DLLIMPORT int64_t __export cfg_opt_getnint64 (cfg_opt_t *opt, unsigned int index)
Returns the value of a CFGT_INT64 (64-bit signed) option, given a cfg_opt_t pointer​.
DLLIMPORT int64_t __export cfg_getnint64 (cfg_t *cfg, const char *name, unsigned int index)
Indexed version of cfg_getint64(), used for lists​.
DLLIMPORT int64_t __export cfg_getint64 (cfg_t *cfg, const char *name)
Returns the value of a CFGT_INT64 (64-bit signed) option, same as cfg_getnint64() with index 0​.
DLLIMPORT uint32_t __export cfg_opt_getnuint32 (cfg_opt_t *opt, unsigned int index)
Returns the value of a CFGT_UINT32 (32-bit unsigned) option, given a cfg_opt_t pointer​.
DLLIMPORT uint32_t __export cfg_getnuint32 (cfg_t *cfg, const char *name, unsigned int index)
Indexed version of cfg_getuint32(), used for lists​.
DLLIMPORT uint32_t __export cfg_getuint32 (cfg_t *cfg, const char *name)
Returns the value of a CFGT_UINT32 (32-bit unsigned) option, same as cfg_getnuint32() with index 0​.
DLLIMPORT uint64_t __export cfg_opt_getnuint64 (cfg_opt_t *opt, unsigned int index)
Returns the value of a CFGT_UINT64 (64-bit unsigned) option, given a cfg_opt_t pointer​.
DLLIMPORT uint64_t __export cfg_getnuint64 (cfg_t *cfg, const char *name, unsigned int index)
Indexed version of cfg_getuint64(), used for lists​.
DLLIMPORT uint64_t __export cfg_getuint64 (cfg_t *cfg, const char *name)
Returns the value of a CFGT_UINT64 (64-bit unsigned) option, same as cfg_getnuint64() with index 0​.
DLLIMPORT int8_t __export cfg_opt_getnint8 (cfg_opt_t *opt, unsigned int index)
Returns the value of a CFGT_INT8 (8-bit signed) option, given a cfg_opt_t pointer​.
DLLIMPORT int8_t __export cfg_getnint8 (cfg_t *cfg, const char *name, unsigned int index)
Indexed version of cfg_getint8(), used for lists​.
DLLIMPORT int8_t __export cfg_getint8 (cfg_t *cfg, const char *name)
Returns the value of a CFGT_INT8 (8-bit signed) option, same as cfg_getnint8() with index 0​.
DLLIMPORT int16_t __export cfg_opt_getnint16 (cfg_opt_t *opt, unsigned int index)
Returns the value of a CFGT_INT16 (16-bit signed) option, given a cfg_opt_t pointer​.
DLLIMPORT int16_t __export cfg_getnint16 (cfg_t *cfg, const char *name, unsigned int index)
Indexed version of cfg_getint16(), used for lists​.
DLLIMPORT int16_t __export cfg_getint16 (cfg_t *cfg, const char *name)
Returns the value of a CFGT_INT16 (16-bit signed) option, same as cfg_getnint16() with index 0​.
DLLIMPORT int32_t __export cfg_opt_getnint32 (cfg_opt_t *opt, unsigned int index)
Returns the value of a CFGT_INT32 (32-bit signed) option, given a cfg_opt_t pointer​.
DLLIMPORT int32_t __export cfg_getnint32 (cfg_t *cfg, const char *name, unsigned int index)
Indexed version of cfg_getint32(), used for lists​.
DLLIMPORT int32_t __export cfg_getint32 (cfg_t *cfg, const char *name)
Returns the value of a CFGT_INT32 (32-bit signed) option, same as cfg_getnint32() with index 0​.
DLLIMPORT uint8_t __export cfg_opt_getnuint8 (cfg_opt_t *opt, unsigned int index)
Returns the value of a CFGT_UINT8 (8-bit unsigned) option, given a cfg_opt_t pointer​.
DLLIMPORT uint8_t __export cfg_getnuint8 (cfg_t *cfg, const char *name, unsigned int index)
Indexed version of cfg_getuint8(), used for lists​.
DLLIMPORT uint8_t __export cfg_getuint8 (cfg_t *cfg, const char *name)
Returns the value of a CFGT_UINT8 (8-bit unsigned) option, same as cfg_getnuint8() with index 0​.
DLLIMPORT uint16_t __export cfg_opt_getnuint16 (cfg_opt_t *opt, unsigned int index)
Returns the value of a CFGT_UINT16 (16-bit unsigned) option, given a cfg_opt_t pointer​.
DLLIMPORT uint16_t __export cfg_getnuint16 (cfg_t *cfg, const char *name, unsigned int index)
Indexed version of cfg_getuint16(), used for lists​.
DLLIMPORT uint16_t __export cfg_getuint16 (cfg_t *cfg, const char *name)
Returns the value of a CFGT_UINT16 (16-bit unsigned) option, same as cfg_getnuint16() with index 0​.
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​.
DLLIMPORT double __export cfg_getnfloat (cfg_t *cfg, const char *name, unsigned int index)
Indexed version of cfg_getfloat(), used for lists​.
DLLIMPORT double __export cfg_getfloat (cfg_t *cfg, const char *name)
Returns the value of a floating point option​.
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​.
DLLIMPORT char *__export cfg_getnstr (cfg_t *cfg, const char *name, unsigned int index)
Indexed version of cfg_getstr(), used for lists​.
DLLIMPORT char *__export cfg_getstr (cfg_t *cfg, const char *name)
Returns the value of a string option​.
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​.
DLLIMPORT cfg_bool_t __export cfg_getnbool (cfg_t *cfg, const char *name, unsigned int index)
Indexed version of cfg_getbool(), used for lists​.
DLLIMPORT cfg_bool_t __export cfg_getbool (cfg_t *cfg, const char *name)
Returns the value of a boolean option​.
DLLIMPORT void *__export cfg_opt_getnptr (cfg_opt_t *opt, unsigned int index)
Returns the value of a user-defined (CFGT_PTR) option, given a cfg_opt_t pointer​.
DLLIMPORT void *__export cfg_getnptr (cfg_t *cfg, const char *name, unsigned int index)
Indexed version of cfg_getptr(), used for lists of user-defined values​.
DLLIMPORT void *__export cfg_getptr (cfg_t *cfg, const char *name)
Returns the value of a user-defined option (void pointer)​.
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​.
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​.
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​.
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​.
DLLIMPORT cfg_t *__export cfg_getsec (cfg_t *cfg, const char *name)
Returns the value of a section option​.
DLLIMPORT unsigned int __export cfg_opt_size (cfg_opt_t *opt)
Return the number of values this option has​.
DLLIMPORT unsigned int __export cfg_size (cfg_t *cfg, const char *name)
Return the number of values this option has​.
DLLIMPORT const char *__export cfg_title (cfg_t *cfg)
Return the title of a section​.
DLLIMPORT const char *__export cfg_getraw (cfg_t *cfg)
Return the verbatim body of a raw section (CFGT_RAWSEC)​.
DLLIMPORT const char *__export cfg_name (cfg_t *cfg)
Return the name of a section​.
DLLIMPORT const char *__export cfg_opt_name (cfg_opt_t *opt)
Return the name of an option​.
DLLIMPORT const char * cfg_opt_getstr (cfg_opt_t *opt)
Return the string value of a key=value pair​.
DLLIMPORT int __export cfg_include (cfg_t *cfg, cfg_opt_t *opt, int argc, const char **argv)
Predefined include-function​.
DLLIMPORT char *__export cfg_tilde_expand (const char *filename)
Does tilde expansion (~ -> $HOME) on the filename​.
DLLIMPORT int __export cfg_parse_boolean (const char *s)
Parse a boolean option string​.
DLLIMPORT cfg_opt_t * cfg_getnopt (cfg_t *cfg, unsigned int index)
Return the nth option in a file or section​.
DLLIMPORT cfg_opt_t *__export cfg_getopt (cfg_t *cfg, const char *name)
Return an option given it's name​.
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)​.
DLLIMPORT int __export cfg_opt_setcomment (cfg_opt_t *opt, char *comment)
Annotate an option​.
DLLIMPORT int __export cfg_setcomment (cfg_t *cfg, const char *name, char *comment)
Annotate an option given its name​.
DLLIMPORT int __export cfg_opt_setnint (cfg_opt_t *opt, long int value, unsigned int index)
Set a value of an integer option​.
DLLIMPORT int __export cfg_setint (cfg_t *cfg, const char *name, long int value)
Set the value of an integer option given its name​.
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​.
DLLIMPORT int __export cfg_opt_setnint64 (cfg_opt_t *opt, int64_t value, unsigned int index)
Set the value of a CFGT_INT64 (64-bit signed) option, given a cfg_opt_t pointer​.
DLLIMPORT int __export cfg_setint64 (cfg_t *cfg, const char *name, int64_t value)
Set the value of a CFGT_INT64 (64-bit signed) option​.
DLLIMPORT int __export cfg_setnint64 (cfg_t *cfg, const char *name, int64_t value, unsigned int index)
Set a value of a CFGT_INT64 (64-bit signed) option at a given list index​.
DLLIMPORT int __export cfg_opt_setnuint32 (cfg_opt_t *opt, uint32_t value, unsigned int index)
Set the value of a CFGT_UINT32 (32-bit unsigned) option, given a cfg_opt_t pointer​.
DLLIMPORT int __export cfg_setuint32 (cfg_t *cfg, const char *name, uint32_t value)
Set the value of a CFGT_UINT32 (32-bit unsigned) option​.
DLLIMPORT int __export cfg_setnuint32 (cfg_t *cfg, const char *name, uint32_t value, unsigned int index)
Set a value of a CFGT_UINT32 (32-bit unsigned) option at a given list index​.
DLLIMPORT int __export cfg_opt_setnuint64 (cfg_opt_t *opt, uint64_t value, unsigned int index)
Set the value of a CFGT_UINT64 (64-bit unsigned) option, given a cfg_opt_t pointer​.
DLLIMPORT int __export cfg_setuint64 (cfg_t *cfg, const char *name, uint64_t value)
Set the value of a CFGT_UINT64 (64-bit unsigned) option​.
DLLIMPORT int __export cfg_setnuint64 (cfg_t *cfg, const char *name, uint64_t value, unsigned int index)
Set a value of a CFGT_UINT64 (64-bit unsigned) option at a given list index​.
DLLIMPORT int __export cfg_opt_setnint8 (cfg_opt_t *opt, int8_t value, unsigned int index)
Set the value of a CFGT_INT8 (8-bit signed) option, given a cfg_opt_t pointer​.
DLLIMPORT int __export cfg_setint8 (cfg_t *cfg, const char *name, int8_t value)
Set the value of a CFGT_INT8 (8-bit signed) option​.
DLLIMPORT int __export cfg_setnint8 (cfg_t *cfg, const char *name, int8_t value, unsigned int index)
Set a value of a CFGT_INT8 (8-bit signed) option at a given list index​.
DLLIMPORT int __export cfg_opt_setnint16 (cfg_opt_t *opt, int16_t value, unsigned int index)
Set the value of a CFGT_INT16 (16-bit signed) option, given a cfg_opt_t pointer​.
DLLIMPORT int __export cfg_setint16 (cfg_t *cfg, const char *name, int16_t value)
Set the value of a CFGT_INT16 (16-bit signed) option​.
DLLIMPORT int __export cfg_setnint16 (cfg_t *cfg, const char *name, int16_t value, unsigned int index)
Set a value of a CFGT_INT16 (16-bit signed) option at a given list index​.
DLLIMPORT int __export cfg_opt_setnint32 (cfg_opt_t *opt, int32_t value, unsigned int index)
Set the value of a CFGT_INT32 (32-bit signed) option, given a cfg_opt_t pointer​.
DLLIMPORT int __export cfg_setint32 (cfg_t *cfg, const char *name, int32_t value)
Set the value of a CFGT_INT32 (32-bit signed) option​.
DLLIMPORT int __export cfg_setnint32 (cfg_t *cfg, const char *name, int32_t value, unsigned int index)
Set a value of a CFGT_INT32 (32-bit signed) option at a given list index​.
DLLIMPORT int __export cfg_opt_setnuint8 (cfg_opt_t *opt, uint8_t value, unsigned int index)
Set the value of a CFGT_UINT8 (8-bit unsigned) option, given a cfg_opt_t pointer​.
DLLIMPORT int __export cfg_setuint8 (cfg_t *cfg, const char *name, uint8_t value)
Set the value of a CFGT_UINT8 (8-bit unsigned) option​.
DLLIMPORT int __export cfg_setnuint8 (cfg_t *cfg, const char *name, uint8_t value, unsigned int index)
Set a value of a CFGT_UINT8 (8-bit unsigned) option at a given list index​.
DLLIMPORT int __export cfg_opt_setnuint16 (cfg_opt_t *opt, uint16_t value, unsigned int index)
Set the value of a CFGT_UINT16 (16-bit unsigned) option, given a cfg_opt_t pointer​.
DLLIMPORT int __export cfg_setuint16 (cfg_t *cfg, const char *name, uint16_t value)
Set the value of a CFGT_UINT16 (16-bit unsigned) option​.
DLLIMPORT int __export cfg_setnuint16 (cfg_t *cfg, const char *name, uint16_t value, unsigned int index)
Set a value of a CFGT_UINT16 (16-bit unsigned) option at a given list index​.
DLLIMPORT int __export cfg_opt_setnfloat (cfg_opt_t *opt, double value, unsigned int index)
Set a value of a floating point option​.
DLLIMPORT int __export cfg_setfloat (cfg_t *cfg, const char *name, double value)
Set the value of a floating point option given its name​.
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​.
DLLIMPORT int __export cfg_opt_setnbool (cfg_opt_t *opt, cfg_bool_t value, unsigned int index)
Set a value of a boolean option​.
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​.
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​.
DLLIMPORT int __export cfg_opt_setnstr (cfg_opt_t *opt, const char *value, unsigned int index)
Set a value of a string option​.
DLLIMPORT int __export cfg_setstr (cfg_t *cfg, const char *name, const char *value)
Set the value of a string option given its name​.
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​.
DLLIMPORT int __export cfg_setlist (cfg_t *cfg, const char *name, unsigned int nvalues,​.​.​.)
Set values for a list option​.
DLLIMPORT int __export cfg_numopts (cfg_opt_t *opts)
Count the number of options in a cfg_opt_t array​.
DLLIMPORT unsigned int __export cfg_num (cfg_t *cfg)
Return number of options in a file or section​.
DLLIMPORT int __export cfg_addlist (cfg_t *cfg, const char *name, unsigned int nvalues,​.​.​.)
Add values for a list option​.
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)​.
DLLIMPORT int cfg_setmulti (cfg_t *cfg, const char *name, unsigned int nvalues, char **values)
Set an option (create an instance of an option)​.
DLLIMPORT cfg_t * cfg_addtsec (cfg_t *cfg, const char *name, const char *title)
Create a new titled config section​.
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​.
DLLIMPORT int __export cfg_rmnsec (cfg_t *cfg, const char *name, unsigned int index)
Indexed version of cfg_rmsec(), used for CFGF_MULTI sections​.
DLLIMPORT int __export cfg_rmsec (cfg_t *cfg, const char *name)
Removes and frees a config section​.
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​.
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​.
DLLIMPORT int __export cfg_opt_nprint_var (cfg_opt_t *opt, unsigned int index, FILE *fp)
Default value print function​.
DLLIMPORT int __export cfg_opt_print_indent (cfg_opt_t *opt, FILE *fp, int indent)
Print an option and its value to a file​.
DLLIMPORT int __export cfg_opt_print (cfg_opt_t *opt, FILE *fp)
Print an option and its value to a file​.
DLLIMPORT int __export cfg_print_indent (cfg_t *cfg, FILE *fp, int indent)
Print the options and values to a file​.
DLLIMPORT int __export cfg_print (cfg_t *cfg, FILE *fp)
Print the options and values to a file​.
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​.
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​.
DLLIMPORT cfg_print_filter_func_t __export cfg_set_print_filter_func (cfg_t *cfg, cfg_print_filter_func_t pff)
Install a user-defined print filter function​.
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​.
DLLIMPORT cfg_validate_callback2_t __export cfg_set_validate_func2 (cfg_t *cfg, const char *name, cfg_validate_callback2_t vf)
Register a validating callback function for an option​.

const char __export confuse_copyright []
libConfuse copyright string
const char __export confuse_version []
libConfuse version string
const char __export confuse_author []
libConfuse author string

Terminate list of options​. This must be the last initializer in the option list​.

Examples addsec​.c, cli​.c, deprecated​.c, env​.c, ftpconf​.c, nested​.c, parsebuf​.c, reread​.c, and simple​.c​.

Value:.PP

    { \
    ​.name = _name, \
    ​.type = CFGT_FUNC, \
    ​.func = _func, \
}

Initialize a function​.

Parameters

See also

cfg_func_t

Examples ftpconf​.c​.

Initialize an integer option​. The value is a C `long int`, so it is platform width -- 32-bit on ILP32 platforms -- and always signed​. For a defined width or an unsigned value use CFG_INT8() ​.​.​. CFG_INT64() or CFG_UINT8() ​.​.​. CFG_UINT64()

Examples addsec​.c, cli​.c, deprecated​.c, ftpconf​.c, nested​.c, parsebuf​.c, and reread​.c​.

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

Value:.PP

    { \
    ​.name = _name, \
    ​.type = CFGT_SEC, \
    ​.flags = _flags, \
    ​.subopts = _opts, \
}

Initialize a section​.

Parameters

Examples addsec​.c, cli​.c, env​.c, ftpconf​.c, nested​.c, parsebuf​.c, and reread​.c​.

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​.

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 initialized 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 = NULL;
​.​.​.
cfg_opt_t opts[] = {
     CFG_SIMPLE_STR('user', &user),
​.​.​.
user = strdup('joe');
cfg = cfg_init(opts, 0);
cfg_parse(cfg, filename);

Examples simple​.c​.

option is deprecated and should be ignored​.

Examples deprecated​.c​.

Flags​. no flags

Examples addsec​.c, cli​.c, deprecated​.c, ftpconf​.c, nested​.c, parsebuf​.c, and reread​.c​.

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()​.

Error reporting function​.

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​.

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

Print filter function​.

Parameters

cfg The configuration file context that opt belongs to​.
opt The configuration option that is about to be printed, or not​.

Returns

Zero if opt should be printed, non-zero if it should be filtered out​.

See also

cfg_set_print_filter_func()

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

Validating callback2 prototype​. This callback function is called before an option is set using the cfg_set*() APIs​. The function is called only for strings, integers, and floats​. Compared to the regular callback function this takes a value pointer argument which must be cast before use, but can also be used to correct a value before it is set, e​.g​. when a too large value is set this can be used to set the MAX​.

Returns

On success, 0 should be returned​. All other values indicates an error, and the cfg_set*() function will return without setting the value​.

See also

cfg_set_validate_func2()

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

Boolean values​.

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

CFGT_COMMENT

comment/annotation

CFGT_RAWSEC

section whose body is captured verbatim as a string

CFGT_INT64

64-bit signed integer

CFGT_UINT32

32-bit unsigned integer

CFGT_UINT64

64-bit unsigned integer

CFGT_INT8

8-bit signed integer

CFGT_INT16

16-bit signed integer

CFGT_INT32

32-bit signed integer

CFGT_UINT8

8-bit unsigned integer

CFGT_UINT16

16-bit unsigned integer

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_FAIL, CFG_SUCCESS, and cfg_t::path​.

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_FAIL, CFG_SUCCESS, CFGF_LIST, and cfg_opt_t::flags​.

Create a new titled config section​.

Parameters

cfg The configuration file context​.
name The name of the option​.
title The title of this section​.

Returns

A pointer to the created section or if the section already exists a pointer to that section is returned​. If the section could not be created or found, 0 is returned​.

References cfg_t::errfunc, cfg_t::line, cfg_t::path, and cfg_value_t::section​.

Show a parser error​. Any user-defined error reporting function is called​.

See also

cfg_set_error_function

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

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​.

References CFG_FAIL, CFG_SUCCESS, cfg_t::comment, cfg_t::filename, cfg_t::name, cfg_opt_t::name, cfg_t::opts, cfg_t::path, cfg_t::raw, and cfg_t::title​.

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_FAIL, CFG_SUCCESS, CFGF_RESET, CFGT_PTR, CFGT_RAWSEC, CFGT_SEC, CFGT_STR, cfg_opt_t::comment, cfg_opt_t::flags, cfg_opt_t::freecb, 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​.

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​.

Returns the option comment​. This function can be used to extract option annotations from a config file​. Only comments preceding the option are read by cfg_parse()​.

Parameters

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

See also

cfg_setcomment

Returns

The comment for this option, or NULL if unset

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​.

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​.

Returns the value of a CFGT_INT16 (16-bit signed) option, same as cfg_getnint16() with index 0​.

Parameters

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

Returns

The value, or the default from the cfg_opt_t if the option was not set​.

Returns the value of a CFGT_INT32 (32-bit signed) option, same as cfg_getnint32() with index 0​.

Parameters

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

Returns

The value, or the default from the cfg_opt_t if the option was not set​.

Returns the value of a CFGT_INT64 (64-bit signed) option, same as cfg_getnint64() with index 0​.

Parameters

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

Returns

The value, or the default from the cfg_opt_t if the option was not set​.

Returns the value of a CFGT_INT8 (8-bit signed) option, same as cfg_getnint8() with index 0​.

Parameters

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

Returns

The value, or the default from the cfg_opt_t if the option was not set​.

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

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

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

Indexed version of cfg_getint16(), 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_getint16

Indexed version of cfg_getint32(), 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_getint32

Indexed version of cfg_getint64(), 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_getint64

Indexed version of cfg_getint8(), 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_getint8

Return the nth option in a file or section​.

Parameters

cfg The configuration file or section context
index Option index

See also

cfg_num

References cfg_opt_t::name, and cfg_t::opts​.

Indexed version of cfg_getptr(), used for lists of user-defined values​.

Parameters

cfg The configuration file context​.
name The name of the option​.
index Index of the value to get, zero based​.

See also

cfg_getptr

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

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

Indexed version of cfg_getuint16(), 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_getuint16

Indexed version of cfg_getuint32(), 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_getuint32

Indexed version of cfg_getuint64(), 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_getuint64

Indexed version of cfg_getuint8(), 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_getuint8

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​.

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​.

Return the verbatim body of a raw section (CFGT_RAWSEC)​.

Parameters

cfg The raw section context​.

Returns

Returns the captured body, or 0 if none​. Do not modify​.

References cfg_t::raw​.

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​.

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​.

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

Returns the value of a CFGT_UINT16 (16-bit unsigned) option, same as cfg_getnuint16() with index 0​.

Parameters

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

Returns

The value, or the default from the cfg_opt_t if the option was not set​.

Returns the value of a CFGT_UINT32 (32-bit unsigned) option, same as cfg_getnuint32() with index 0​.

Parameters

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

Returns

The value, or the default from the cfg_opt_t if the option was not set​.

Returns the value of a CFGT_UINT64 (64-bit unsigned) option, same as cfg_getnuint64() with index 0​.

Parameters

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

Returns

The value, or the default from the cfg_opt_t if the option was not set​.

Returns the value of a CFGT_UINT8 (8-bit unsigned) option, same as cfg_getnuint8() with index 0​.

Parameters

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

Returns

The value, or the default from the cfg_opt_t if the option was not set​.

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)

References CFG_FAIL​.

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)​.

CFGF_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 array 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​.

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

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​.

References cfg_t::name​.

Return number of options in a file or section​.

Parameters

cfg The configuration file or section context

When a file has been parsed this function returns the number of options/settings the file, or a sub-section, has​.

Returns

Number of options in a config file or section​.

References cfg_t::opts​.

Count the number of options in a cfg_opt_t array​.

Parameters

opts A cfg_opt_t array, terminated by CFG_END()​.

Returns

The number of options in opts, excluding the terminating CFG_END()​.

References cfg_opt_t::name​.

Returns the option comment​.

Parameters

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

See also

cfg_getcomment

References cfg_opt_t::comment​.

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, cfg_simple_t::boolean, CFGT_BOOL, cfg_opt_t::simple_value, cfg_opt_t::type, and cfg_opt_t::values​.

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_simple_t::fpnumber, cfg_opt_t::simple_value, cfg_opt_t::type, and cfg_opt_t::values​.

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

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

Returns the value of a CFGT_INT16 (16-bit signed) 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​.

Returns

The value at index, or 0 if unset or on error​.

See also

cfg_getnint16

References CFGT_INT16, cfg_value_t::i16, cfg_simple_t::i16, cfg_opt_t::simple_value, cfg_opt_t::type, and cfg_opt_t::values​.

Returns the value of a CFGT_INT32 (32-bit signed) 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​.

Returns

The value at index, or 0 if unset or on error​.

See also

cfg_getnint32

References CFGT_INT32, cfg_value_t::i32, cfg_simple_t::i32, cfg_opt_t::simple_value, cfg_opt_t::type, and cfg_opt_t::values​.

Returns the value of a CFGT_INT64 (64-bit signed) 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​.

Returns

The value at index, or 0 if unset or on error​.

See also

cfg_getnint64

References CFGT_INT64, cfg_value_t::i64, cfg_simple_t::i64, cfg_opt_t::simple_value, cfg_opt_t::type, and cfg_opt_t::values​.

Returns the value of a CFGT_INT8 (8-bit signed) 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​.

Returns

The value at index, or 0 if unset or on error​.

See also

cfg_getnint8

References CFGT_INT8, cfg_value_t::i8, cfg_simple_t::i8, cfg_opt_t::simple_value, cfg_opt_t::type, and cfg_opt_t::values​.

Returns the value of a user-defined (CFGT_PTR) 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​.

Returns

The stored pointer at index, or NULL if unset or on error​.

See also

cfg_getnptr

References CFGT_PTR, cfg_value_t::ptr, cfg_simple_t::ptr, cfg_opt_t::simple_value, cfg_opt_t::type, and cfg_opt_t::values​.

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

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

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_simple_t::string, cfg_opt_t::type, and cfg_opt_t::values​.

Returns the value of a CFGT_UINT16 (16-bit unsigned) 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​.

Returns

The value at index, or 0 if unset or on error​.

See also

cfg_getnuint16

References CFGT_UINT16, cfg_opt_t::simple_value, cfg_opt_t::type, cfg_value_t::u16, cfg_simple_t::u16, and cfg_opt_t::values​.

Returns the value of a CFGT_UINT32 (32-bit unsigned) 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​.

Returns

The value at index, or 0 if unset or on error​.

See also

cfg_getnuint32

References CFGT_UINT32, cfg_opt_t::simple_value, cfg_opt_t::type, cfg_value_t::u32, cfg_simple_t::u32, and cfg_opt_t::values​.

Returns the value of a CFGT_UINT64 (64-bit unsigned) 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​.

Returns

The value at index, or 0 if unset or on error​.

See also

cfg_getnuint64

References CFGT_UINT64, cfg_opt_t::simple_value, cfg_opt_t::type, cfg_value_t::u64, cfg_simple_t::u64, and cfg_opt_t::values​.

Returns the value of a CFGT_UINT8 (8-bit unsigned) 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​.

Returns

The value at index, or 0 if unset or on error​.

See also

cfg_getnuint8

References CFGT_UINT8, cfg_opt_t::simple_value, cfg_opt_t::type, cfg_value_t::u8, cfg_simple_t::u8, and cfg_opt_t::values​.

Return the string value of a key=value pair​.

Parameters

opt The option structure (eg, as returned from cfg_getnopt())

See also

cfg_opt_name

Returns

The string value for the option, or NULL if it's not a string​. This string must not be modified!

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 CFGF_TITLE, and cfg_opt_t::flags​.

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​.

References cfg_opt_t::name​.

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_FAIL, CFG_SUCCESS, CFGT_BOOL, CFGT_COMMENT, CFGT_FLOAT, CFGT_FUNC, CFGT_INT, CFGT_INT16, CFGT_INT32, CFGT_INT64, CFGT_INT8, CFGT_PTR, CFGT_RAWSEC, CFGT_SEC, CFGT_STR, CFGT_UINT16, CFGT_UINT32, CFGT_UINT64, CFGT_UINT8, and cfg_opt_t::type​.

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​.

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​.

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_FAIL, CFG_SUCCESS, CFGT_SEC, cfg_opt_t::nvalues, cfg_value_t::section, cfg_opt_t::type, and cfg_opt_t::values​.

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_FAIL, CFGF_NOCASE, CFGF_TITLE, cfg_opt_t::flags, and cfg_t::title​.

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​.

Annotate an option​.

Parameters

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

See also

cfg_setcomment

Returns

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

References CFG_FAIL, CFG_SUCCESS, CFGF_COMMENTS, CFGF_MODIFIED, cfg_opt_t::comment, and cfg_opt_t::flags​.

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_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGF_RESET, cfg_opt_t::flags, cfg_opt_t::nvalues, and cfg_opt_t::values​.

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_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGT_BOOL, cfg_opt_t::flags, and cfg_opt_t::type​.

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_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGT_FLOAT, cfg_opt_t::flags, cfg_value_t::fpnumber, and cfg_opt_t::type​.

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_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGT_INT, cfg_opt_t::flags, cfg_value_t::number, and cfg_opt_t::type​.

Set the value of a CFGT_INT16 (16-bit signed) option, given a cfg_opt_t pointer​.

Parameters

opt The option structure (eg, as returned from cfg_getopt())
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGT_INT16, cfg_opt_t::flags, cfg_value_t::i16, and cfg_opt_t::type​.

Set the value of a CFGT_INT32 (32-bit signed) option, given a cfg_opt_t pointer​.

Parameters

opt The option structure (eg, as returned from cfg_getopt())
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGT_INT32, cfg_opt_t::flags, cfg_value_t::i32, and cfg_opt_t::type​.

Set the value of a CFGT_INT64 (64-bit signed) option, given a cfg_opt_t pointer​.

Parameters

opt The option structure (eg, as returned from cfg_getopt())
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGT_INT64, cfg_opt_t::flags, cfg_value_t::i64, and cfg_opt_t::type​.

Set the value of a CFGT_INT8 (8-bit signed) option, given a cfg_opt_t pointer​.

Parameters

opt The option structure (eg, as returned from cfg_getopt())
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGT_INT8, cfg_opt_t::flags, cfg_value_t::i8, and cfg_opt_t::type​.

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_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGT_STR, cfg_opt_t::flags, cfg_value_t::string, and cfg_opt_t::type​.

Set the value of a CFGT_UINT16 (16-bit unsigned) option, given a cfg_opt_t pointer​.

Parameters

opt The option structure (eg, as returned from cfg_getopt())
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGT_UINT16, cfg_opt_t::flags, cfg_opt_t::type, and cfg_value_t::u16​.

Set the value of a CFGT_UINT32 (32-bit unsigned) option, given a cfg_opt_t pointer​.

Parameters

opt The option structure (eg, as returned from cfg_getopt())
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGT_UINT32, cfg_opt_t::flags, cfg_opt_t::type, and cfg_value_t::u32​.

Set the value of a CFGT_UINT64 (64-bit unsigned) option, given a cfg_opt_t pointer​.

Parameters

opt The option structure (eg, as returned from cfg_getopt())
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGT_UINT64, cfg_opt_t::flags, cfg_opt_t::type, and cfg_value_t::u64​.

Set the value of a CFGT_UINT8 (8-bit unsigned) option, given a cfg_opt_t pointer​.

Parameters

opt The option structure (eg, as returned from cfg_getopt())
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGT_UINT8, cfg_opt_t::flags, cfg_opt_t::type, and cfg_value_t::u8​.

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())

References cfg_opt_t::nvalues​.

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​.

References CFG_FILE_ERROR, cfg_t::filename, and cfg_t::path​.

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​.

References CFG_FAIL​.

Same as cfg_parse() above, but takes a character buffer as argument​. Diagnostics use cfg->filename for their `file:line` prefix​. Set it, to a heap-allocated string, before calling to make errors from an in-memory buffer point at the real source file; ownership transfers to the library, which frees it​. When left unset it defaults to '[buf]'​. This mirrors cfg_parse_fp()​.

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​.

References CFG_FILE_ERROR, CFG_PARSE_ERROR, CFG_SUCCESS, and cfg_t::filename​.

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​.

Diagnostics use cfg->filename for their `file:line` prefix​. Set it, to a heap-allocated string, before calling to name the source; ownership transfers to the library, which frees it​. When left unset it defaults to '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_PARSE_ERROR, CFG_SUCCESS, cfg_t::filename, and cfg_t::line​.

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​.

References CFGF_JSON_LISTS, and cfg_t::flags​.

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 CFGF_JSON_LISTS, and cfg_t::flags​.

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​.

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​.

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​.

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 containing 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​.

Install a user-defined error reporting function​.

Returns

The old error reporting function is returned​.

References cfg_t::errfunc​.

Install a user-defined print filter function​. This callback is called for each option when printing cfg, or something above cfg if cfg is a section in some parent cfg​. When cfg (or something above cfg) is printed, this filter is also inherited to child sections unless the child section has its own print filter​.

Parameters

cfg The configuration file context​.
pff The print filter callback function​.

Returns

The old print filter function is returned​.

See also

cfg_print_filter_func_t

References cfg_t::pff​.

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

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

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

Register a validating callback function for an option​. This callback is called for all cfg_set*() functions, although not cfg_opt_set*(), and can be used to check and modify a value/string *before* it is actually set​. The regular callbacks are run after the fact and are only called when parsing a buffer or file​.

Parameters

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

See also

cfg_validate_callback2_t

References cfg_t::flags, cfg_t::opts, and cfg_opt_t::validcb2​.

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​.

Annotate an option given its name​. All options can be annotated as long as the CFGF_COMMENTS flag is given to cfg_init()​.

When calling cfg_print(), annotations are saved as a C style one-liner comment before each option​.

When calling cfg_parse(), only one-liner comments preceding an option are read and used to annotate the option​.

Parameters

cfg The configuration file context​.
name The name of the option​.
comment The annotation

Returns

POSIX OK(0), or non-zero on failure​. This function will fail if memory for the new comment cannot be allocated​.

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​.

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​.

Set the value of a CFGT_INT16 (16-bit signed) option​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.

Returns

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

Set the value of a CFGT_INT32 (32-bit signed) option​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.

Returns

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

Set the value of a CFGT_INT64 (64-bit signed) option​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.

Returns

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

Set the value of a CFGT_INT8 (8-bit signed) option​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.

Returns

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

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_FAIL, CFG_SUCCESS, CFGF_LIST, and cfg_opt_t::flags​.

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_FAIL​.

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​.

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_FAIL, and cfg_opt_t::validcb2​.

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_FAIL, and cfg_opt_t::validcb2​.

Set a value of a CFGT_INT16 (16-bit signed) option at a given list index​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, and cfg_opt_t::validcb2​.

Set a value of a CFGT_INT32 (32-bit signed) option at a given list index​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, and cfg_opt_t::validcb2​.

Set a value of a CFGT_INT64 (64-bit signed) option at a given list index​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, and cfg_opt_t::validcb2​.

Set a value of a CFGT_INT8 (8-bit signed) option at a given list index​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, and cfg_opt_t::validcb2​.

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_FAIL, and cfg_opt_t::validcb2​.

Set a value of a CFGT_UINT16 (16-bit unsigned) option at a given list index​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, and cfg_opt_t::validcb2​.

Set a value of a CFGT_UINT32 (32-bit unsigned) option at a given list index​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, and cfg_opt_t::validcb2​.

Set a value of a CFGT_UINT64 (64-bit unsigned) option at a given list index​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, and cfg_opt_t::validcb2​.

Set a value of a CFGT_UINT8 (8-bit unsigned) option at a given list index​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.
index Index in the value array to modify; must be 0 unless CFGF_LIST is set​.

Returns

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

References CFG_FAIL, and cfg_opt_t::validcb2​.

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_SUCCESS, CFGF_DEFINIT, CFGF_IGNORE_UNKNOWN, CFGF_KEYSTRVAL, CFGF_LIST, CFGF_MODIFIED, CFGF_MULTI, CFGF_NO_TITLE_DUPES, CFGF_NOCASE, CFGF_RESET, CFGF_TITLE, CFGF_USE_INCLUDE_FUNCTION, CFGT_BOOL, CFGT_FLOAT, CFGT_INT, CFGT_INT16, CFGT_INT32, CFGT_INT64, CFGT_INT8, CFGT_PTR, CFGT_RAWSEC, CFGT_SEC, CFGT_STR, CFGT_UINT16, CFGT_UINT32, CFGT_UINT64, CFGT_UINT8, cfg_t::errfunc, cfg_t::filename, cfg_t::flags, cfg_opt_t::flags, cfg_value_t::fpnumber, cfg_value_t::i16, cfg_value_t::i32, cfg_value_t::i64, cfg_value_t::i8, 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_simple_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, cfg_value_t::u16, cfg_value_t::u32, cfg_value_t::u64, cfg_value_t::u8, and cfg_opt_t::values​.

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​.

Set the value of a CFGT_UINT16 (16-bit unsigned) option​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.

Returns

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

Set the value of a CFGT_UINT32 (32-bit unsigned) option​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.

Returns

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

Set the value of a CFGT_UINT64 (64-bit unsigned) option​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.

Returns

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

Set the value of a CFGT_UINT8 (8-bit unsigned) option​.

Parameters

cfg The configuration file context​.
name The name of the option​.
value The value to set​.

Returns

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

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​.

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​.

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​.