confuse.h(3)
✨ confuse.h 💅
okay so bestie, welcome to the manual page for confuse.h — she's a configuration file parser library, and she's iconic. 🎀 (this is the confuse.h(3) page from the Library Functions Manual, for the record, iykyk)
🌸 NAME 🌸
confuse.h — a configuration file parser library. that's it, that's the whole vibe. a whole library just for parsing config files, and she eats every single time 💖
✨ SYNOPSIS ✨
first things first, you gotta pull in the headers. all three of them. no skipping, bestie:
#include <stdio.h>
#include <stdarg.h>
#include <stdint.h>🦋 Data Structures 🦋
okay so here's the cast of characters — the structs and unions you're gonna be living with. main character energy, every one of them 👑
struct cfg_t— the data structure holding information about a 'section'. she holds the section lore fr frunion cfg_value_t— the data structure holding the value of a fundamental option value. one value, union-style, lowkey elegant ✨union cfg_simple_t— the data structure holding the pointer to a user provided variable, defined withCFG_SIMPLE_*. she's holding your pointer, bestie, treat her nice 🫶struct cfg_defvalue_t— the data structure holding the default value given by the initialization macros. defaults are giving safety net, and we stan 💛struct cfg_opt_t— the data structure holding information about an option. every option you ever define lives here, no cap 🔥
and that's just the setup, bestie — there's SO much more coming. stay tuned 💜
✨ Macros ✨
okay bestie, this is the part where confuse.h just dumps the entire starter pack on you 🎀 — every single #define you're ever gonna whisper at your config code. it's long, it's giving phone-book energy, but every one of them is iconic in its own lil way. let's go 💅
first up: the flags — these are the lil bits you sprinkle onto options to give them ✨personality✨:
#define CFGF_NONE (0)— Flags. the big nothing, the zero, the "I'm a totally normal option, leave me be" vibe.#define CFGF_MULTI (1 << 0)— this option can be specified multiple times! heads up tho: it only applies to sections.#define CFGF_LIST (1 << 1)— this option is a list.#define CFGF_NOCASE (1 << 2)— the configuration file gets read case-insensitively. uppercase, lowercase, who even cares 💅#define CFGF_TITLE (1 << 3)— this option has a title. and again, only applies to sections.#define CFGF_NODEFAULT (1 << 4)— this option has no default value. it starts empty, it starts fresh, main character energy.#define CFGF_NO_TITLE_DUPES (1 << 5)— multiple section titles have to be unique. if you duplicate one it raises an error 😭 and yep, 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. mystery options? never heard of her 🙈#define CFGF_DEPRECATED (1 << 9)— this option is deprecated and should be ignored. it's giving "we don't talk about bruno" 💀#define CFGF_DROP (1 << 10)— this option should be dropped after parsing. bye bestie 🫶#define CFGF_COMMENTS (1 << 11)— enables option annotation/comment support.#define CFGF_MODIFIED (1 << 12)— this option has been changed from its default value.#define CFGF_KEYSTRVAL (1 << 13)— the section has free-formkey=valuestring options that were created when the file was parsed.#define CFGF_USE_INCLUDE_FUNCTION (1 << 14)— adds aninclude()function to the section's options.#define CFGF_USE_INCLUDE_FUNCTIONno wait — that was the last one, keep scrolling.#define CFGF_JSON_LISTS (1 << 15)— accepts and prints JSON-style[ ]as an alternative to{ }for lists. so flexible, so bilingual, obsessed 🦋
and now the result codes, aka the "how did it go" squad:
#define CFG_SUCCESS 0— Success, all OK (POSIX'0'). the slay outcome ✨#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.
okay and now the big one — the initialization macros 🌈 every single type gets the same five-flavour treatment: plain, list, callback, list-with-callback, and the lil "simple" one. it's giving very much "same energy, different integer width" and honestly? the consistency ate.
#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 (and hey, peep the documentation forCFG_SIMPLE_STRfor more info).#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;svalueis anint64_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;svalueis auint32_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;svalueis auint64_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;svalueis anint8_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;svalueis anint16_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;svalueis anint32_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;svalueis auint8_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;svalueis auint16_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,
…and that's exactly where this part cuts off, mid-#define, bestie 😭💀 hold that thought, there's more coming and you are NOT ready 🫶
Picking up right where we left off — that last macro's expansion finishes like this:
CFGF_NONE, svalue, NULL)and that whole thing is the simple floating point option initializer — it sets up a 'simple' floating point option (go read the docs for CFG_SIMPLE_STR if you want the full tea on how the simple ones work). 💅
#define CFG_BOOL(name, def, flags)— expands to__CFG_BOOL(name, def, flags, NULL, NULL). This is how you initialize a boolean option. true/false girlies rise 🫶#define CFG_BOOL_LIST(name, def, flags)— expands to__CFG_BOOL_LIST(name, def, flags, NULL, NULL). Initializes a boolean list option (yes, a whole list of booleans, iconic).#define CFG_BOOL_CB(name, def, flags, cb)— expands to__CFG_BOOL(name, def, flags, NULL, cb). Initializes a boolean option that also has a value parsing callback.#define CFG_BOOL_LIST_CB(name, def, flags, cb)— expands to__CFG_BOOL_LIST(name, def, flags, NULL, cb). Same deal but for a boolean list, with a value parsing callback attached. 🎀#define CFG_SIMPLE_BOOL(name, svalue)— expands to__CFG_BOOL(name, cfg_false, CFGF_NONE, svalue, NULL). Initializes a 'simple' boolean option (again, see theCFG_SIMPLE_STRdocs for the deets).#define CFG_SEC(_name, _opts, _flags)— initializes a section. Structure? We love her. 🏗️#define CFG_FUNC(_name, _func)— initializes a function.#define CFG_PTR_CB(name, def, flags, parsecb, freecb)— expands to__CFG_PTR(name, def, flags, NULL, parsecb, freecb). Initializes a user-defined option — you bring the parse callback and the free callback, no cap.#define CFG_PTR_LIST_CB(name, def, flags, parsecb, freecb)— expands to__CFG_PTR(name, def, flags | CFGF_LIST, NULL, parsecb, freecb). Same energy, but it initializes a list of user-defined options. Note the| CFGF_LISTdoing the heavy lifting ✨#define CFG_END()— expands to{ .type = CFGT_NONE, }. Terminates the list of options. It's the "okay bye bestie" of your option array. 😭
🦋 Typedefs 🦋
The whole cast of characters, each one a lil type you can hold in your hand:
typedef enum cfg_type_t cfg_type_t— a fundamental option type. It's one of theCFGT_*values, pick your fighter.typedef union cfg_value_t cfg_value_t— a fundamental option value.typedef union cfg_simple_t cfg_simple_t— a pointer to a user variable, for theCFG_SIMPLE_*options.typedef struct cfg_opt_t cfg_opt_t— describes a single configuration option. One struct, one option, very demure.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. The backup plan. 💜typedef int cfg_flag_t— option flags, a bitwise OR ofCFGF_*values.typedef struct cfg_searchpath_t cfg_searchpath_t— an entry in the include search path. She's on the list, literally.typedef int(* cfg_func_t) (cfg_t *cfg, cfg_opt_t *opt, int argc, const char **argv)— the function prototype used byCFGT_FUNCoptions.typedef void(* cfg_print_func_t) (cfg_opt_t *opt, unsigned int index, FILE *fp)— the function prototype used by thecfg_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. Yes there's a sequel and yes it slaps. 🔥typedef void(* cfg_free_func_t) (void *value)— the user-defined memory release function forCFG_PTRvalues. Clean up after yourself, periodt.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.
🌈 Enumerations 🌈
enum cfg_type_t { }— fundamental option types. The whole taxonomy, bestie.enum cfg_bool_t— boolean values. It's giving true or false, nothing in between. 💀DLLIMPORT cfg_t *__export cfg_init (cfg_opt_t *opts, cfg_flag_t flags)— bestie, this is where it ALL begins 💖 it creates and initializes acfg_tstructure for you. newborn config context, so cute.DLLIMPORT int __export cfg_add_searchpath (cfg_t *cfg, const char *dir)— drop a searchpath directory into the configuration context 🫶 heads up tho: thatconst char*argument gets duplicated, and then freed as part of the usual context takedown. so it's a copy, not a hostage.DLLIMPORT char *__export cfg_searchpath (cfg_searchpath_t *path, const char *file)— hunts through the linked-list ofcfg_searchpath_tlooking for the file you asked for 🔍DLLIMPORT int __export cfg_parse (cfg_t *cfg, const char *filename)— parses a configuration file. the main event ✨DLLIMPORT int __export cfg_parse_fp (cfg_t *cfg, FILE *fp)— literallycfg_parse()above but it takes an already opened file as the argument. same energy, different input 🎀DLLIMPORT int __export cfg_parse_buf (cfg_t *cfg, const char *buf)— also same ascfg_parse()above, except this one takes a character buffer as the argument. buffer girlies rise 💅DLLIMPORT int __export cfg_free_value (cfg_opt_t *opt)— frees the memory that was allocated for the values of a given option. clean up after yourself, periodt 🧹DLLIMPORT int __export cfg_free (cfg_t *cfg)— frees a wholecfg_tcontext. bye bestie, you served 👑DLLIMPORT cfg_errfunc_t __export cfg_set_error_function (cfg_t *cfg, cfg_errfunc_t errfunc)— installs a user-defined error reporting function. your errors, your rules 💜DLLIMPORT void __export cfg_error (cfg_t *cfg, const char *fmt,...)— shows a parser error. it's giving "something went wrong" energy 😭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)— also returns the option comment. twins fr fr 🫶DLLIMPORT signed long __export cfg_opt_getnint (cfg_opt_t *opt, unsigned int index)— returns the value of an integer option, and you hand it acfg_opt_tpointer to do it.DLLIMPORT long int __export cfg_getnint (cfg_t *cfg, const char *name, unsigned int index)— the indexed version ofcfg_getint(), used for lists 📋DLLIMPORT long int __export cfg_getint (cfg_t *cfg, const char *name)— returns the value of an integer option. simple. iconic. no notes.DLLIMPORT int64_t __export cfg_opt_getnint64 (cfg_opt_t *opt, unsigned int index)— returns the value of aCFGT_INT64(that's 64-bit signed, for the record) option, given acfg_opt_tpointer 🔥DLLIMPORT int64_t __export cfg_getnint64 (cfg_t *cfg, const char *name, unsigned int index)— indexed version ofcfg_getint64(), used for lists.DLLIMPORT int64_t __export cfg_getint64 (cfg_t *cfg, const char *name)— returns the value of aCFGT_INT64(64-bit signed) option, same ascfg_getnint64()with index0.DLLIMPORT uint32_t __export cfg_opt_getnuint32 (cfg_opt_t *opt, unsigned int index)— returns the value of aCFGT_UINT32(32-bit unsigned) option, given acfg_opt_tpointer 💫DLLIMPORT uint32_t __export cfg_getnuint32 (cfg_t *cfg, const char *name, unsigned int index)— indexed version ofcfg_getuint32(), used for lists.DLLIMPORT uint32_t __export cfg_getuint32 (cfg_t *cfg, const char *name)— returns the value of aCFGT_UINT32(32-bit unsigned) option, same ascfg_getnuint32()with index0.DLLIMPORT uint64_t __export cfg_opt_getnuint64 (cfg_opt_t *opt, unsigned int index)— returns the value of aCFGT_UINT64(64-bit unsigned) option, given acfg_opt_tpointer 🌸DLLIMPORT uint64_t __export cfg_getnuint64 (cfg_t *cfg, const char *name, unsigned int index)— indexed version ofcfg_getuint64(), used for lists.DLLIMPORT uint64_t __export cfg_getuint64 (cfg_t *cfg, const char *name)— returns the value of aCFGT_UINT64(64-bit unsigned) option, same ascfg_getnuint64()with index0.DLLIMPORT int8_t __export cfg_opt_getnint8 (cfg_opt_t *opt, unsigned int index)— returns the value of aCFGT_INT8(8-bit signed) option, given acfg_opt_tpointer ✨DLLIMPORT int8_t __export cfg_getnint8 (cfg_t *cfg, const char *name, unsigned int index)— indexed version ofcfg_getint8(), used for lists.DLLIMPORT int8_t __export cfg_getint8 (cfg_t *cfg, const char *name)— returns the value of aCFGT_INT8(8-bit signed) option, same ascfg_getnint8()with index0.DLLIMPORT int16_t __export cfg_opt_getnint16 (cfg_opt_t *opt, unsigned int index)— returns the value of aCFGT_INT16(16-bit signed) option, given acfg_opt_tpointer 💖DLLIMPORT int16_t __export cfg_getnint16 (cfg_t *cfg, const char *name, unsigned int index)— indexed version ofcfg_getint16(), used for lists.DLLIMPORT int16_t __export cfg_getint16 (cfg_t *cfg, const char *name)— returns the value of aCFGT_INT16(16-bit signed) option, same ascfg_getnint16()with index0.DLLIMPORT int32_t __export cfg_opt_getnint32 (cfg_opt_t *opt, unsigned int index)— returns the value of aCFGT_INT32(32-bit signed) option, given acfg_opt_tpointer 🦋DLLIMPORT int32_t __export cfg_getnint32 (cfg_t *cfg, const char *name, unsigned int index)— indexed version ofcfg_getint32(), used for lists.DLLIMPORT int32_t __export cfg_getint32 (cfg_t *cfg, const char *name)— returns the value of aCFGT_INT32(32-bit signed) option, same ascfg_getnint32()with index0.DLLIMPORT uint8_t __export cfg_opt_getnuint8 (cfg_opt_t *opt, unsigned int index)— returns the value of aCFGT_UINT8(8-bit unsigned) option, given acfg_opt_tpointer 💅DLLIMPORT uint8_t __export cfg_getnuint8 (cfg_t *cfg, const char *name, unsigned int index)— indexed version ofcfg_getuint8(), used for lists.DLLIMPORT uint8_t __export cfg_getuint8 (cfg_t *cfg, const char *name)— returns the value of aCFGT_UINT8(8-bit unsigned) option, same ascfg_getnuint8()with index0.DLLIMPORT uint16_t __export cfg_opt_getnuint16 (cfg_opt_t *opt, unsigned int index)— returns the value of aCFGT_UINT16(16-bit unsigned) option, given acfg_opt_tpointer 🌈DLLIMPORT uint16_t __export cfg_getnuint16 (cfg_t *cfg, const char *name, unsigned int index)— indexed version ofcfg_getuint16(), used for lists.DLLIMPORT uint16_t __export cfg_getuint16 (cfg_t *cfg, const char *name)— returns the value of aCFGT_UINT16(16-bit unsigned) option, same ascfg_getnuint16()with index0.DLLIMPORT double __export cfg_opt_getnfloat (cfg_opt_t *opt, unsigned int index)— returns the value of a floating point option, given acfg_opt_tpointer 🍓DLLIMPORT double __export cfg_getnfloat (cfg_t *cfg, const char *name, unsigned int index)— indexed version ofcfg_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 acfg_opt_tpointer 🎀DLLIMPORT char *__export cfg_getnstr (cfg_t *cfg, const char *name, unsigned int index)— indexed version ofcfg_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 acfg_opt_tpointer 💜DLLIMPORT cfg_bool_t __export cfg_getnbool (cfg_t *cfg, const char *name, unsigned int index)— indexed version ofcfg_getbool(), used for lists.DLLIMPORT cfg_bool_t __export cfg_getbool (cfg_t *cfg, const char *name)— returns the value of a boolean option. true or false bestie, no in-between 💀DLLIMPORT void *__export cfg_opt_getnptr (cfg_opt_t *opt, unsigned int index)— returns the value of a user-defined (CFGT_PTR) option, given acfg_opt_tpointer ✨DLLIMPORT void *__export cfg_getnptr (cfg_t *cfg, const char *name, unsigned int index)— indexed version ofcfg_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 (that's a void pointer, iykyk).DLLIMPORT cfg_t *__export cfg_opt_getnsec (cfg_opt_t *opt, unsigned int index)— returns the value of a section option, given acfg_opt_tpointer 🫶DLLIMPORT cfg_t *__export cfg_getnsec (cfg_t *cfg, const char *name, unsigned int index)— indexed version ofcfg_getsec(), used for sections with theCFGF_MULTIflag set.DLLIMPORT cfg_t *__export cfg_opt_gettsec (cfg_opt_t *opt, const char *title)— returns the value of a section option, given acfg_opt_tpointer and the title.DLLIMPORT cfg_t *__export cfg_gettsec (cfg_t *cfg, const char *name, const char *title)— returns a section given the title, used for sections with theCFGF_TITLEflag 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)— returns the number of values this option has. count 'em 🔢DLLIMPORT unsigned int __export cfg_size (cfg_t *cfg, const char *name)— returns the number of values this option has. same vibe, different signature.DLLIMPORT const char *__export cfg_title (cfg_t *cfg)— returns the title of a section 🌸DLLIMPORT const char *__export cfg_getraw (cfg_t *cfg)— returns the verbatim body of a raw section (CFGT_RAWSEC). untouched, unbothered, exactly as written 💅DLLIMPORT const char *__export cfg_name (cfg_t *cfg)— returns the name of a section.DLLIMPORT const char *__export cfg_opt_name (cfg_opt_t *opt)— returns the name of an option.DLLIMPORT const char * cfg_opt_getstr (cfg_opt_t *opt)— returns the string value of akey=valuepair 🔑DLLIMPORT int __export cfg_include (cfg_t *cfg, cfg_opt_t *opt, int argc, const char **argv)— the predefined include-function. built-in bestie, already slaying ✨DLLIMPORT char *__export cfg_tilde_expand (const char *filename)— does tilde expansion on the filename, so~becomes$HOME🏠DLLIMPORT int __export cfg_parse_boolean (const char *s)— parses a boolean option string.DLLIMPORT cfg_opt_t * cfg_getnopt (cfg_t *cfg, unsigned int index)— returns the nth option in a file or section 📋DLLIMPORT cfg_opt_t *__export cfg_getopt (cfg_t *cfg, const char *name)— returns an option given it's name.DLLIMPORT cfg_value_t * cfg_setopt (cfg_t *cfg, cfg_opt_t *opt, const char *value)— sets an option, which means it creates an instance of an option 🎀DLLIMPORT int __export cfg_opt_setcomment (cfg_opt_t *opt, char *comment)— annotates an option. little note, big feelings 💖DLLIMPORT int __export cfg_setcomment (cfg_t *cfg, const char *name, char *comment)— annotates an option, given its name.DLLIMPORT int __export cfg_opt_setnint (cfg_opt_t *opt, long int value, unsigned int index)— sets a value of an integer option.DLLIMPORT int __export cfg_setint (cfg_t *cfg, const char *name, long int value)— sets 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)— sets 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)— sets the value of aCFGT_INT64(64-bit signed) option, given acfg_opt_tpointer 🫶DLLIMPORT int __export cfg_setint64 (cfg_t *cfg, const char *name, int64_t value)— sets the value of aCFGT_INT64(64-bit signed) option ✨DLLIMPORT int __export cfg_setnint64 (cfg_t *cfg, const char *name, int64_t value, unsigned int index)— sets a value of aCFGT_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)— sets the value of aCFGT_UINT32(32-bit unsigned) option, given acfg_opt_tpointer 🌸DLLIMPORT int __export cfg_setuint32 (cfg_t *cfg, const char *name, uint32_t value)— sets the value of aCFGT_UINT32(32-bit unsigned) option ⭐DLLIMPORT int __export cfg_setnuint32 (cfg_t *cfg, const char *name, uint32_t value, unsigned int index)— sets a value of aCFGT_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)— sets the value of aCFGT_UINT64(64-bit unsigned) option, given acfg_opt_tpointer 💖DLLIMPORT int __export cfg_setuint64 (cfg_t *cfg, const char *name, uint64_t value)— sets the value of aCFGT_UINT64(64-bit unsigned) option 🔥DLLIMPORT int __export cfg_setnuint64 (cfg_t *cfg, const char *name, uint64_t value, unsigned int index)— sets a value of aCFGT_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)— sets the value of aCFGT_INT8(8-bit signed) option, given acfg_opt_tpointer 🌈DLLIMPORT int __export cfg_setint8 (cfg_t *cfg, const char *name, int8_t value)— sets the value of aCFGT_INT8(8-bit signed) option 👑DLLIMPORT int __export cfg_setnint8 (cfg_t *cfg, const char *name, int8_t value, unsigned int index)— sets a value of aCFGT_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)— sets the value of aCFGT_INT16(16-bit signed) option, given acfg_opt_tpointer 🧚DLLIMPORT int __export cfg_setint16 (cfg_t *cfg, const char *name, int16_t value)— sets the value of aCFGT_INT16(16-bit signed) option 🍓DLLIMPORT int __export cfg_setnint16 (cfg_t *cfg, const char *name, int16_t value, unsigned int index)— sets a value of aCFGT_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)— sets the value of aCFGT_INT32(32-bit signed) option, given acfg_opt_tpointer 🫶DLLIMPORT int __export cfg_setint32 (cfg_t *cfg, const char *name, int32_t value)— sets the value of aCFGT_INT32(32-bit signed) option ✨DLLIMPORT int __export cfg_setnint32 (cfg_t *cfg, const char *name, int32_t value, unsigned int index)— sets a value of aCFGT_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)— sets the value of aCFGT_UINT8(8-bit unsigned) option, given acfg_opt_tpointer 🌸DLLIMPORT int __export cfg_setuint8 (cfg_t *cfg, const char *name, uint8_t value)— sets the value of aCFGT_UINT8(8-bit unsigned) option ⭐DLLIMPORT int __export cfg_setnuint8 (cfg_t *cfg, const char *name, uint8_t value, unsigned int index)— sets a value of aCFGT_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)— sets the value of aCFGT_UINT16(16-bit unsigned) option, given acfg_opt_tpointer 💖DLLIMPORT int __export cfg_setuint16 (cfg_t *cfg, const char *name, uint16_t value)— sets the value of aCFGT_UINT16(16-bit unsigned) option 🔥DLLIMPORT int __export cfg_setnuint16 (cfg_t *cfg, const char *name, uint16_t value, unsigned int index)— sets a value of aCFGT_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)— sets a value of a floating point option 🌈DLLIMPORT int __export cfg_setfloat (cfg_t *cfg, const char *name, double value)— sets 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)— sets 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)— sets a value of a boolean option 🧚DLLIMPORT int __export cfg_setbool (cfg_t *cfg, const char *name, cfg_bool_t value)— sets 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)— sets 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)— sets a value of a string option 🫶DLLIMPORT int __export cfg_setstr (cfg_t *cfg, const char *name, const char *value)— sets 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)— sets 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,...)— sets values for a list option 🌸DLLIMPORT int __export cfg_numopts (cfg_opt_t *opts)— counts the number of options in acfg_opt_tarray ⭐DLLIMPORT unsigned int __export cfg_num (cfg_t *cfg)— returns the number of options in a file or section 🦋DLLIMPORT int __export cfg_addlist (cfg_t *cfg, const char *name, unsigned int nvalues,...)— adds values for a list option 💖DLLIMPORT int cfg_opt_setmulti (cfg_t *cfg, cfg_opt_t *opt, unsigned int nvalues, char **values)— sets an option (creates an instance of an option) 🔥DLLIMPORT int cfg_setmulti (cfg_t *cfg, const char *name, unsigned int nvalues, char **values)— sets an option (creates an instance of an option) 🎀DLLIMPORT cfg_t * cfg_addtsec (cfg_t *cfg, const char *name, const char *title)— creates 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 acfg_opt_tpointer 👑DLLIMPORT int __export cfg_rmnsec (cfg_t *cfg, const char *name, unsigned int index)— the indexed version ofcfg_rmsec(), used forCFGF_MULTIsections 💜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 acfg_opt_tpointer 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 a section with theCFGF_TITLEflag set 💫DLLIMPORT int __export cfg_opt_nprint_var (cfg_opt_t *opt, unsigned int index, FILE *fp)— the default value print function 🫶DLLIMPORT int __export cfg_opt_print_indent (cfg_opt_t *opt, FILE *fp, int indent)— prints an option and its value to a file ✨DLLIMPORT int __export cfg_opt_print (cfg_opt_t *opt, FILE *fp)— prints an option and its value to a file 💅DLLIMPORT int __export cfg_print_indent (cfg_t *cfg, FILE *fp, int indent)— prints the options and values to a file 🌸DLLIMPORT int __export cfg_print (cfg_t *cfg, FILE *fp)— prints 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)— sets 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)— sets 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)— installs 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)— registers 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)— registers a validating callback function for an option 🌈
🌟 Variables 🌟
const char __export confuse_copyright []— the libConfuse copyright string 👑const char __export confuse_version []— the libConfuse version string 💜const char __export confuse_author []— the libConfuse author string 🧚
💖 Detailed Description 💖
A configuration file parser library. That's the whole thing, bestie — that's the vibe. 🍓
🧩 Macro Definition Documentation 🧩
Okay bestie, gather round, because these macros are literally the little Lego bricks you build your whole cfg_opt_t array out of. Get them right and everything slays. Get them wrong and… well, you'll see. 👑
CFG_END() 💅
Expands to this, exactly:
{ .type = CFGT_NONE, }This is the ✨terminator✨ of your option list — it's the \0 of the config world, no cap. It must be the very last initializer in the option list, or the vibes (and your program) will simply not be okay.
Examples where it shows up: addsec.c, cli.c, deprecated.c, env.c, ftpconf.c, nested.c, parsebuf.c, reread.c, and simple.c. She's in everything. Queen behaviour. 🎀
CFG_FUNC(_name, _func) 🦋
Expands to:
{ \
.name = _name, \
.type = CFGT_FUNC, \
.func = _func, \
}This one initializes a function. Yes, an actual callable function option, iconic.
Parameters:
_name— the name of the option._func— the callback function.
See also: cfg_func_t — go look at her, she's important.
Examples: ftpconf.c.
CFG_INT(name, def, flags) ⭐
Expands to:
__CFG_INT(name, def, flags, NULL, NULL)Initializes an integer option. Heads up though, the value is a C long int, so it's platform width — that means 32-bit on ILP32 platforms — and it's always signed. If you want a defined width, or you're feeling unsigned, go use CFG_INT8() ... CFG_INT64() or CFG_UINT8() ... CFG_UINT64() instead. We don't do guessing games with integer size here. 🙈
Examples: addsec.c, cli.c, deprecated.c, ftpconf.c, nested.c, parsebuf.c, and reread.c.
CFG_PTR_CB(name, def, flags, parsecb, freecb) 🔥
Expands to:
__CFG_PTR(name, def, flags, NULL, parsecb, freecb)Initializes a user-defined option. Important tea: CFG_PTR options can only be used together with a value parsing callback. No callback, no CFG_PTR, periodt.
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.
CFG_SEC(_name, _opts, _flags) 🌸
Expands to:
{ \
.name = _name, \
.type = CFGT_SEC, \
.flags = _flags, \
.subopts = _opts, \
}Initializes a section. Nested config? We love to see it. 🫶
Parameters:
_name— the name of the option._opts— array of options that are valid within this section._flags— flags. SpecifyCFGF_MULTIif it should be possible to have multiples of the same section, andCFGF_TITLEif the section(s) must have a title (which can then be used in thecfg_gettsec()function). Mix and match as your heart desires.
Examples: addsec.c, cli.c, env.c, ftpconf.c, nested.c, parsebuf.c, and reread.c.
CFG_SIMPLE_INT(name, svalue) 💜
Expands to:
__CFG_INT(name, 0, CFGF_NONE, svalue, NULL)Initializes a 'simple' integer option — and yes, the docs point you at CFG_SIMPLE_STR for the full explanation of what "simple" even means. But here's the big one: confuse uses long integers, so make absolutely sure that any pointer you provide for svalue points to a long int and not a normal int. If you don't… you will get strange problems on 64-bit architectures. And not the fun kind of strange. 😭
Examples: simple.c.
CFG_SIMPLE_STR(name, svalue) 🎀
Expands to:
__CFG_STR(name, NULL, CFGF_NONE, svalue, NULL)Initializes a 'simple' string option. So what's "simple"?? Basically (in lack of a better expression) simple options do not support lists of values or multiple sections. LibConfuse will store the value of a simple option in the user-defined location you specify with the value parameter in the initializer. Simple options are not stored in the cfg_t context — you only get a pointer. And sections can not be initialized as a 'simple' option. Sorry babe. 💔
Good news though: 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. Slay. ✨
Bad news: 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. So that's on you, bestie.
Parameters:
name— name of the option.svalue— pointer to a character pointer (achar **). This value must be initialized either toNULLor to amalloc()'ed string. You can't use this:
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.
CFGF_DEPRECATED — (1 << 9) 💀
This flag means the option is deprecated and should be ignored. It's giving "we're keeping you around for the lore but please move on."
Examples: deprecated.c.
CFGF_NONE — (0) 🌈
Flags. No flags. That's it. That's the whole vibe. Zero, nothing, nada.
Examples: addsec.c, cli.c, deprecated.c, ftpconf.c, nested.c, parsebuf.c, and reread.c.
🧚 Typedef Documentation 🧚
And now for the callbacks — the main characters of the confuse cinematic universe. 💖
cfg_callback_t 👑
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, don't get it twisted) used to parse a value. It can be used to override the internal parsing of a value.
Picture this: 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. Chef's kiss mapping. 😙
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 avoidpointer.
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().
cfg_errfunc_t 😭
typedef void(* cfg_errfunc_t) (cfg_t *cfg, const char *fmt, va_list ap)Error reporting function. That's the whole description, she's lowkey mysterious like that.
cfg_free_func_t 🍓
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. Reuse, recycle, release. ♻️
cfg_func_t 🔥
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, so any conversion to other types should be made in the callback function itself. And listen: 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. It's your data now, bestie. 💅
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.
cfg_print_filter_func_t 🌸
typedef int(* cfg_print_filter_func_t) (cfg_t *cfg, cfg_opt_t *opt)Print filter function — the bouncer at the door of your output. 🚪
Parameters:
cfg— The configuration file context thatoptbelongs 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().
cfg_print_func_t 🦋
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. Round trip, babes. ✈️
Except for functions, the print callback function should only print the value of the option, not the name and the equal sign — that part 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 fromcfg_getopt()).index— Index of the value to get. Zero based.fp— File stream to print to, usestdoutto print to the screen.
See also: cfg_print, cfg_set_print_func.
cfg_validate_callback2_t ⭐
typedef int(* cfg_validate_callback2_t) (cfg_t *cfg, cfg_opt_t *opt, void *value)Validating callback2 prototype. This callback function is called before an option is set using the cfg_set*() APIs. It's called only for strings, integers, and floats. Compared to the regular callback function, this one takes a value pointer argument which must be cast before use — but it 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. Little fixer-upper energy. 🔧
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().
cfg_validate_callback_t 🌈
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. It's 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. She's the final vibe check. ✅
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
Bestie, it's literally just booleans. Boolean values, that's the whole vibe. True/false girlies only. 💅
🌈 enum cfg_type_t
Okay so THIS one is the main character — it's the fundamental option types. Every option in your config has one of these little labels on it, iykyk. Here's the full roster, no skips:
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 🫙 (rawr, verbatim, untouched, iconic)CFGT_INT64— 64-bit signed integerCFGT_UINT32— 32-bit unsigned integerCFGT_UINT64— 64-bit unsigned integerCFGT_INT8— 8-bit signed integerCFGT_INT16— 16-bit signed integerCFGT_INT32— 32-bit signed integerCFGT_UINT8— 8-bit unsigned integerCFGT_UINT16— 16-bit unsigned integer
All the int sizes showed up and honestly? Slay. Every width accounted for, no gaps, periodt. 💖
🔥 FUNCTION DOCUMENTATION 🔥
🦋 DLLIMPORT int __export cfg_add_searchpath (cfg_t * cfg, const char * dir)
Adds a searchpath directory to the configuration context. The const char* argument gets duplicated, and then it gets freed as part of the usual context takedown — so don't you worry about it, she's handled. 💅
Every directory you add to the context this way will be searched for the file you specified in cfg_parse(), plus for those included. And all directories added with this function get 'tilde expanded' (yes, ~ girlies, you're seen 🏡).
Heads up bestie: the current directory is not added to the searchpath by default. Not me assuming otherwise. 🙈
Parameters
cfg— The configuration file context as returned fromcfg_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.
🎀 DLLIMPORT int __export cfg_addlist (cfg_t * cfg, const char * name, unsigned int nvalues, ...)
Adds values for a list option. The new values get appended to whatever values are already chilling in the list — nothing gets replaced, we're adding, we're growing, we're thriving. ✨
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 thenvaluesparameter.
Returns
POSIX OK(0), or non-zero on failure.
References CFG_FAIL, CFG_SUCCESS, CFGF_LIST, and cfg_opt_t::flags.
💜 DLLIMPORT cfg_t * cfg_addtsec (cfg_t * cfg, const char * name, const char * title)
Creates a new titled config section. Fancy. 👑
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.
😭 DLLIMPORT void __export cfg_error (cfg_t * cfg, const char * fmt, ...)
Shows a parser error. Any user-defined error reporting function gets called.
See also cfg_set_error_function
References cfg_t::errfunc, cfg_t::filename, and cfg_t::line.
🧚 DLLIMPORT int __export cfg_free (cfg_t * cfg)
Frees a cfg_t context. ALL the memory allocated by the cfg_t context structure is freed — and after that you can't use it in any further cfg_* calls. She's gone, bestie. Do not text her back. 💀
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.
🍓 DLLIMPORT int __export cfg_free_value (cfg_opt_t * opt)
Frees the memory allocated for the values of a given option. Only the values get freed, not the option itself — the option gets freed by cfg_free(). So like, values first, option later. Two separate events. Don't mix them up. 💅
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.
✅ 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. Like, don't do that. 🚫
💬 DLLIMPORT char *__export cfg_getcomment (cfg_t * cfg, const char * name)
Returns the option comment. This function can be used to extract option annotations from a config file.
Lowkey important: only comments preceding the option are read by cfg_parse(). Comments after it? Not your girl. 🙈
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.
🌊 DLLIMPORT double __export cfg_getfloat (cfg_t * cfg, const char * name)
Returns the value of a floating point option. Floaties, we love to see it. 💧
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 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. Basically the non-indexed twin. 🫶
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 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.
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.
🎯 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.
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.
🎯 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.
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.
🎯 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.
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.
🦋 DLLIMPORT cfg_bool_t __export cfg_getnbool (cfg_t * cfg, const char * name, unsigned int index)
Indexed version of cfg_getbool(), used for lists. Now with index energy. 🔢
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
🦋 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
🦋 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
🦋 DLLIMPORT int16_t __export cfg_getnint16 (cfg_t * cfg, const char * name, unsigned int index)
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
🦋 DLLIMPORT int32_t __export cfg_getnint32 (cfg_t * cfg, const char * name, unsigned int index)
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
🦋 DLLIMPORT int64_t __export cfg_getnint64 (cfg_t * cfg, const char * name, unsigned int index)
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
🦋 DLLIMPORT int8_t __export cfg_getnint8 (cfg_t * cfg, const char * name, unsigned int index)
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
👑 DLLIMPORT cfg_opt_t * cfg_getnopt (cfg_t * cfg, unsigned int index)
Return the nth option in a file or section. Digging through the lineup, one by one. 🕵️♀️
Parameters
cfg— The configuration file or section context.index— Option index.
See also cfg_num
References cfg_opt_t::name, and cfg_t::opts.
👉 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. Your values, your rules. 🫶
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
📂 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. Multi-section girlies, this one's for you. 💅
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
🦋 cfg_getnstr 🦋
okay so this is the indexed version of cfg_getstr(), and it's made for lists 💅 You want one specific string out of the pile, bestie? This is your girl.
DLLIMPORT char *__export cfg_getnstr (cfg_t * cfg, const char * name, unsigned int index)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
🌸 cfg_getnuint16 🌸
Indexed version of cfg_getuint16(), used for lists. Same vibe, but with a number attached 💜
DLLIMPORT uint16_t __export cfg_getnuint16 (cfg_t * cfg, const char * name, unsigned int index)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
🌸 cfg_getnuint32 🌸
Indexed version of cfg_getuint32(), used for lists. 32 whole bits of unsigned goodness, and you get to pick which one ✨
DLLIMPORT uint32_t __export cfg_getnuint32 (cfg_t * cfg, const char * name, unsigned int index)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
🌸 cfg_getnuint64 🌸
Indexed version of cfg_getuint64(), used for lists. Big number energy 👑
DLLIMPORT uint64_t __export cfg_getnuint64 (cfg_t * cfg, const char * name, unsigned int index)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
🍓 cfg_getnuint8 🍓
Indexed version of cfg_getuint8(), used for lists. Smol, but indexed 😌
DLLIMPORT uint8_t __export cfg_getnuint8 (cfg_t * cfg, const char * name, unsigned int index)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
💜 cfg_getopt 💜
Return an option given it's name. fr fr, just hand over the option itself 👑
DLLIMPORT cfg_opt_t *__export cfg_getopt (cfg_t * cfg, const char * name)Parameters
cfg— The configuration file context.name— The name of the option.
Returns
Returns a pointer to the option. But heads up: if the option isn't declared, libConfuse will print an error message and return 0. No option, no pointer, that's the rule 😭
🧚 cfg_getptr 🧚
Returns the value of a user-defined option (void pointer). Mystery type, void pointer, main character energy 💅
DLLIMPORT void *__export cfg_getptr (cfg_t * cfg, const char * name)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. So don't do that 🙈
⭐ cfg_getraw ⭐
Return the verbatim body of a raw section (CFGT_RAWSEC). Literally the raw tea, unedited 🌈
DLLIMPORT const char *__export cfg_getraw (cfg_t * cfg)Parameters
cfg— The raw section context.
Returns
Returns the captured body, or 0 if none. Do not modify. Like, hands off bestie, that's not yours 💀
References — cfg_t::raw
🎀 cfg_getsec 🎀
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. It's giving nested-context ✨
DLLIMPORT cfg_t *__export cfg_getsec (cfg_t * cfg, const char * name)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. periodt 💅
🦋 cfg_getstr 🦋
Returns the value of a string option. Strings, my beloved 💖
DLLIMPORT char *__export cfg_getstr (cfg_t * cfg, const char * name)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. no cap 🫶
👑 cfg_gettsec 👑
Return a section given the title, used for section with the CFGF_TITLE flag set. When your sections have names, this is how you call them by name 💜
DLLIMPORT cfg_t *__export cfg_gettsec (cfg_t * cfg, const char * name, const char * title)Parameters
cfg— The configuration file context.name— The name of the option.title— The title of this section. TheCFGF_TITLEflag must have been set for this option.
See also — cfg_getsec
🌈 cfg_getuint16 🌈
Returns the value of a CFGT_UINT16 (16-bit unsigned) option, same as cfg_getnuint16() with index 0. One and done ✨
DLLIMPORT uint16_t __export cfg_getuint16 (cfg_t * cfg, const char * name)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.
🌈 cfg_getuint32 🌈
Returns the value of a CFGT_UINT32 (32-bit unsigned) option, same as cfg_getnuint32() with index 0.
DLLIMPORT uint32_t __export cfg_getuint32 (cfg_t * cfg, const char * name)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.
🌈 cfg_getuint64 🌈
Returns the value of a CFGT_UINT64 (64-bit unsigned) option, same as cfg_getnuint64() with index 0. Sixty-four bits of slay 👑
DLLIMPORT uint64_t __export cfg_getuint64 (cfg_t * cfg, const char * name)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.
🌈 cfg_getuint8 🌈
Returns the value of a CFGT_UINT8 (8-bit unsigned) option, same as cfg_getnuint8() with index 0. Teeny tiny value 🍓
DLLIMPORT uint8_t __export cfg_getuint8 (cfg_t * cfg, const char * name)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.
🧚 cfg_include 🧚
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)Plug it in and it just works ✨
DLLIMPORT int __export cfg_include (cfg_t * cfg, cfg_opt_t * opt, int argc, const char ** argv)References — CFG_FAIL
💖 cfg_init 💖
Create and initialize a cfg_t structure. This is THE first function you call when setting up the parsing of a configuration file 🌈
DLLIMPORT cfg_t *__export cfg_init (cfg_opt_t * opts, cfg_flag_t flags)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. and bestie, you do not 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). Scope tea ☕
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 optionsflags— One or more flags (bitwise or'ed together). Currently onlyCFGF_NOCASEandCFGF_IGNORE_UNKNOWNare available. Use0if no flags are needed.
Returns
A configuration context structure. This pointer is passed to almost all other functions as the first parameter. Keep it close, you'll need it everywhere 💅
References — cfg_t::errfunc, cfg_t::filename, cfg_t::flags, cfg_t::line, cfg_t::name, and cfg_t::opts.
🎀 cfg_name 🎀
Return the name of a section.
DLLIMPORT const char *__export cfg_name (cfg_t * cfg)Parameters
cfg— The configuration file context.
Returns
Returns the title, or 0 if there is no title. This string should not be modified. Look but don't touch, periodt 💅
References — cfg_t::name
⭐ cfg_num ⭐
Return number of options in a file or section. Counting era ✨
DLLIMPORT unsigned int __export cfg_num (cfg_t * cfg)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
⭐ cfg_numopts ⭐
Count the number of options in a cfg_opt_t array.
DLLIMPORT int __export cfg_numopts (cfg_opt_t * opts)Parameters
opts— Acfg_opt_tarray, terminated byCFG_END().
Returns
The number of options in opts, excluding the terminating CFG_END(). (Yes bestie, the sentinel does NOT count 💅)
References — cfg_opt_t::name
🌸 cfg_opt_getcomment 🌸
Returns the option comment. The little note attached to the option 🎀
DLLIMPORT char *__export cfg_opt_getcomment (cfg_opt_t * opt)Parameters
opt— The option structure (eg, as returned fromcfg_getopt())
See also — cfg_getcomment
References — cfg_opt_t::comment
💜 cfg_opt_getnbool 💜
Returns the value of a boolean option, given a cfg_opt_t pointer. true or false, pick your fighter ✨
DLLIMPORT cfg_bool_t __export cfg_opt_getnbool (cfg_opt_t * opt, unsigned int index)Parameters
opt— The option structure (eg, as returned fromcfg_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.
🍓 cfg_opt_getnfloat 🍓
Returns the value of a floating point option, given a cfg_opt_t pointer. Floats, decimals, the whole vibe 🦋
DLLIMPORT double __export cfg_opt_getnfloat (cfg_opt_t * opt, unsigned int index)Parameters
opt— The option structure (eg, as returned fromcfg_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.
👑 cfg_opt_getnint 👑
Returns the value of an integer option, given a cfg_opt_t pointer. Whole numbers only, we don't do decimals here 💅
DLLIMPORT signed long __export cfg_opt_getnint (cfg_opt_t * opt, unsigned int index)Parameters
opt— The option structure (eg, as returned fromcfg_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.
🌈 cfg_opt_getnint16 🌈
Returns the value of a CFGT_INT16 (16-bit signed) option, given a cfg_opt_t pointer. Signed, sealed, sixteen bits 🍓
DLLIMPORT int16_t __export cfg_opt_getnint16 (cfg_opt_t * opt, unsigned int index)Parameters
opt— The option structure (eg, as returned fromcfg_getopt())index— Index of the value to get, zero based.
Returns
The value at index, or 0 if unset or on error. Default zero behavior, iykyk ✨
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.
🌈 cfg_opt_getnint32 🌈
Returns the value of a CFGT_INT32 (32-bit signed) option, given a cfg_opt_t pointer. Thirty-two bits of signed slay 👑
DLLIMPORT int32_t __export cfg_opt_getnint32 (cfg_opt_t * opt, unsigned int index)Parameters
opt— The option structure (eg, as returned fromcfg_getopt())index— Index of the value to get, zero based.
Returns — the value at index, or 0 if it's 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.
cfg_opt_getnint64
DLLIMPORT int64_t __export cfg_opt_getnint64 (cfg_opt_t * opt, unsigned int index)okay so this one grabs the value of a CFGT_INT64 (64-bit signed) option when you hand it a cfg_opt_t pointer. 💖
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())index— index of the value to get, zero based.
Returns — the value at index, or 0 if it's 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.
cfg_opt_getnint8
DLLIMPORT int8_t __export cfg_opt_getnint8 (cfg_opt_t * opt, unsigned int index)bestie this one is for your CFGT_INT8 (8-bit signed) option, given a cfg_opt_t pointer. ✨
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())index— index of the value to get, zero based.
Returns — the value at index, or 0 if it's 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.
cfg_opt_getnptr
DLLIMPORT void *__export cfg_opt_getnptr (cfg_opt_t * opt, unsigned int index)this one returns the value of a user-defined (CFGT_PTR) option, given a cfg_opt_t pointer. no cap. 👑
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())index— index of the value to get, zero based.
Returns — the stored pointer at index, or NULL if it's 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.
cfg_opt_getnsec
DLLIMPORT cfg_t *__export cfg_opt_getnsec (cfg_opt_t * opt, unsigned int index)this one gives you the value of a section option, given a cfg_opt_t pointer. it's giving section energy. 🎀
Parameters
opt— the option structure (eg, as returned fromcfg_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.
cfg_opt_getnstr
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 fromcfg_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.
cfg_opt_getnuint16
DLLIMPORT uint16_t __export cfg_opt_getnuint16 (cfg_opt_t * opt, unsigned int index)this one is for your CFGT_UINT16 (16-bit unsigned) option, given a cfg_opt_t pointer. 🌸
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())index— index of the value to get, zero based.
Returns — the value at index, or 0 if it's 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.
cfg_opt_getnuint32
DLLIMPORT uint32_t __export cfg_opt_getnuint32 (cfg_opt_t * opt, unsigned int index)CFGT_UINT32 (32-bit unsigned) option value, given a cfg_opt_t pointer. slay. 🔥
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())index— index of the value to get, zero based.
Returns — the value at index, or 0 if it's 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.
cfg_opt_getnuint64
DLLIMPORT uint64_t __export cfg_opt_getnuint64 (cfg_opt_t * opt, unsigned int index)CFGT_UINT64 (64-bit unsigned) option value, given a cfg_opt_t pointer. big numbers energy. 💜
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())index— index of the value to get, zero based.
Returns — the value at index, or 0 if it's 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.
cfg_opt_getnuint8
DLLIMPORT uint8_t __export cfg_opt_getnuint8 (cfg_opt_t * opt, unsigned int index)CFGT_UINT8 (8-bit unsigned) option value, given a cfg_opt_t pointer. tiny but mighty. 🦋
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())index— index of the value to get, zero based.
Returns — the value at index, or 0 if it's 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.
cfg_opt_getstr
DLLIMPORT const char * cfg_opt_getstr (cfg_opt_t * opt)returns the string value of a key=value pair. periodt. 💅
Parameters
opt— the option structure (eg, as returned fromcfg_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! 😭
cfg_opt_gettsec
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 fromcfg_getopt())title— the title of this section. theCFGF_TITLEflag must have been set for this option.
See also cfg_gettsec
References CFGF_TITLE, and cfg_opt_t::flags.
cfg_opt_name
DLLIMPORT const char *__export cfg_opt_name (cfg_opt_t * opt)returns the name of an option. iconic. ✨
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())
Returns — returns the title, or 0 if there is no title. this string should not be modified.
References cfg_opt_t::name.
cfg_opt_nprint_var
DLLIMPORT int __export cfg_opt_nprint_var (cfg_opt_t * opt, unsigned int index, FILE * fp)default value print function. prints 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 fromcfg_getopt())index— the index in the option value array that should be printedfp— 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.
cfg_opt_print
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 fromcfg_getopt())fp— file stream to print to.
See also cfg_print_func_t
Returns — POSIX OK(0), or non-zero on failure.
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.
cfg_opt_rmnsec
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. bye bye section. 👋
Parameters
opt— the option structure (eg, as returned fromcfg_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.
cfg_opt_rmtsec
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 fromcfg_getopt())title— the title of this section. theCFGF_TITLEflag 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.
cfg_opt_set_print_func
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. main character energy. 👑
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())pf— the print function callback.
See also cfg_print_func_t
References cfg_opt_t::pf.
cfg_opt_setcomment
DLLIMPORT int __export cfg_opt_setcomment (cfg_opt_t * opt, char * comment)annotate an option. add a little note bestie. 📝
Parameters
opt— the option structure (eg, as returned fromcfg_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.
cfg_opt_setmulti
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_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGF_RESET, cfg_opt_t::flags, cfg_opt_t::nvalues, and cfg_opt_t::values.
cfg_opt_setnbool
DLLIMPORT int __export cfg_opt_setnbool (cfg_opt_t * opt, cfg_bool_t value, unsigned int index)set a value of a boolean option. true or false bestie. 💖
Parameters
opt— the option structure (eg, as returned fromcfg_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 theCFGF_LISTflag set.
⚠️ warning: settingindex>0on an option that doesn't haveCFGF_LISTis an error. don't do it. 💀
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.
cfg_opt_setnfloat
DLLIMPORT int __export cfg_opt_setnfloat (cfg_opt_t * opt, double value, unsigned int index)set a value of a floating point option. 🌸
opt— the option struct, like the one you get back fromcfg_getopt()🫶value— the value you're setting it to.index— which slot in the option value array you're modifying. And bestie, listen: setting values with indices bigger than 0 on an option that does not have theCFGF_LISTflag set? That's an error. Don't do it. 🚫
Returns
POSIX OK(0), or non-zero if it flopped. 😭
References CFG_FAIL, CFG_SUCCESS, CFGF_MODIFIED, CFGT_FLOAT, cfg_opt_t::flags, cfg_value_t::fpnumber, and cfg_opt_t::type.
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 fromcfg_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 theCFGF_LISTflag 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.
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. 💅
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())value— the value to set.index— index in the value array to modify; must be0unlessCFGF_LISTis 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.
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. 🌸
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())value— the value to set.index— index in the value array to modify; must be0unlessCFGF_LISTis 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.
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. ⭐
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())value— the value to set.index— index in the value array to modify; must be0unlessCFGF_LISTis 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.
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. 🎀
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())value— the value to set.index— index in the value array to modify; must be0unlessCFGF_LISTis 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.
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 fromcfg_getopt())value— the value to set. Memory for the string is allocated and the value is copied. Any previous string value is freed. (so the library is handling the memory for you, no cap 💖)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 theCFGF_LISTflag 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.
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. 💜
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())value— the value to set.index— index in the value array to modify; must be0unlessCFGF_LISTis 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.
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. 🌈
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())value— the value to set.index— index in the value array to modify; must be0unlessCFGF_LISTis 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.
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. 🔥
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())value— the value to set.index— index in the value array to modify; must be0unlessCFGF_LISTis 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.
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. 🍓
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())value— the value to set.index— index in the value array to modify; must be0unlessCFGF_LISTis 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.
DLLIMPORT unsigned int __export cfg_opt_size (cfg_opt_t * opt)
Returns how many values this option has. Bestie, important detail: if no default value was given for the option and nothing was found in the config file, you get 0 back — meaning the option value isn't set at all. 🙈
Parameters
opt— the option structure (eg, as returned fromcfg_getopt())
References cfg_opt_t::nvalues.
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 config file has been initialized (with cfg_init()) and parsed (with cfg_parse()), you can read the values with the cfg_getXXX functions.
Parameters
cfg— the configuration file context as returned fromcfg_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.
DLLIMPORT int __export cfg_parse_boolean (const char * s)
Parse a boolean option string. The accepted 'true' values are 'true', 'on' and 'yes', and the 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.
DLLIMPORT int __export cfg_parse_buf (cfg_t * cfg, const char * buf)
Same as cfg_parse() above, but it takes a character buffer as the argument instead of a file. 🫶 Diagnostics use cfg->filename for their file:line prefix. So set it — to a heap-allocated string — before calling, so that errors coming from an in-memory buffer actually point at the real source file; ownership transfers to the library, which frees it. If you leave it unset it defaults to '[buf]'. This mirrors cfg_parse_fp().
Parameters
cfg— the configuration file context as returned fromcfg_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.
DLLIMPORT int __export cfg_parse_fp (cfg_t * cfg, FILE * fp)
Same as cfg_parse() above, but it takes an already opened file as the 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. If you leave it unset it defaults to 'FILE'.
Parameters
cfg— the configuration file context as returned fromcfg_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.
DLLIMPORT int __export cfg_print (cfg_t * cfg, FILE * fp)
Print the options and values to a file. 💅 Heads up though: 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. Which means — if you parse a configuration file, you can't expect the output from this function to be identical to the initial file. It's giving ✨glow up✨ not ✨photocopy✨.
Parameters
cfg— the configuration file context.fp— file stream to print to, usestdoutto 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.
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 CFGF_JSON_LISTS, and cfg_t::flags.
DLLIMPORT int __export cfg_rmnsec (cfg_t * cfg, const char * name, unsigned int index)
The 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.
cfg_rmsec
DLLIMPORT int __export cfg_rmsec (cfg_t * cfg, const char * name)okay so this one removes and frees a config section 💅 and bestie it's literally the exact same thing as calling cfg_rmnsec with index 0. that's it, that's the whole function.
cfg— the configuration file context.name— the name of the section.
Returns: POSIX OK(0), or non-zero on failure. 🫶
cfg_rmtsec
DLLIMPORT int __export cfg_rmtsec (cfg_t * cfg, const char * name, const char * title)removes and frees a section given the title — this is the one you reach for when your section has the CFGF_TITLE flag set, iykyk 🎀
cfg— the configuration file context.name— the name of the section.title— the title of this section. theCFGF_TITLEflag must have been set for this option, fr fr.
See also: cfg_rmsec
Returns: POSIX OK(0), or non-zero on failure.
cfg_searchpath
DLLIMPORT char *__export cfg_searchpath (cfg_searchpath_t * path, const char * file)walks the linked-list of cfg_searchpath_t looking for the file you asked for 🔍 and if the return value isn't NULL, it's freshly allocated so you have to free it. no cap, the caller owns that memory.
path— the linked list ofcfg_searchpath_tstructs, each one holding a directory to be searched.file— the file for which to search.
Returns: if the file is found on the searchpath, you get the full path to the file back. if it's not found, NULL comes home instead. 🙈
cfg_set_error_function
DLLIMPORT cfg_errfunc_t __export cfg_set_error_function (cfg_t * cfg, cfg_errfunc_t errfunc)installs a user-defined error reporting function — your own little error-handling main character ✨
Returns: the old error reporting function gets handed back to you.
References: cfg_t::errfunc.
cfg_set_print_filter_func
DLLIMPORT cfg_print_filter_func_t __export cfg_set_print_filter_func (cfg_t * cfg, cfg_print_filter_func_t pff)installs a user-defined print filter function 🎀 this callback gets called for each option when printing cfg, or something above cfg if cfg is a section in some parent cfg. and here's the tea: when cfg (or something above cfg) is printed, this filter is also inherited to child sections — unless that child section has its own print filter. messy family dynamics honestly 💀
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.
cfg_set_print_func
DLLIMPORT cfg_print_func_t __export cfg_set_print_func (cfg_t * cfg, const char * name, cfg_print_func_t pf)sets a print callback function for an option, found by its name 🖨️✨
cfg— the configuration file context.name— the name of the option.pf— the print callback function.
See also: cfg_print_func_t
cfg_set_validate_func
DLLIMPORT cfg_validate_callback_t __export cfg_set_validate_func (cfg_t * cfg, const char * name, cfg_validate_callback_t vf)registers a validating callback function for an option 👑
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.
cfg_set_validate_func2
DLLIMPORT cfg_validate_callback2_t __export cfg_set_validate_func2 (cfg_t * cfg, const char * name, cfg_validate_callback2_t vf)registers a validating callback function for an option, but make it version 2 🌈 this callback gets called for all cfg_set*() functions — although not cfg_opt_set*() — and it can check and modify a value/string before it's actually set. the regular callbacks run after the fact and are only called when parsing a buffer or file. timing is everything bestie 💅
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.
cfg_setbool
DLLIMPORT int __export cfg_setbool (cfg_t * cfg, const char * name, cfg_bool_t value)sets the value of a boolean option, by name ✅
cfg— the configuration file context.name— the name of the option.value— the value to set. if the option is a list (theCFGF_LISTflag is set), only the first value (with index0) is set. that's just how it is 🫶
Returns: POSIX OK(0), or non-zero on failure.
cfg_setcomment
DLLIMPORT int __export cfg_setcomment (cfg_t * cfg, const char * name, char * comment)annotates an option by name 📝 and listen, all options can be annotated — as long as the CFGF_COMMENTS flag was given to cfg_init(). no flag, no comment, periodt.
when you call cfg_print(), annotations are saved as a C style one-liner comment before each option.
when you call cfg_parse(), only one-liner comments preceding an option are read and used to annotate that option. (so don't go putting them after, it won't hit.)
cfg— the configuration file context.name— the name of the option.comment— the annotation.
Returns: POSIX OK(0), or non-zero on failure. and heads up: this function will fail if memory for the new comment can't be allocated 😭
cfg_setfloat
DLLIMPORT int __export cfg_setfloat (cfg_t * cfg, const char * name, double value)sets the value of a floating point option, by name 🍓
cfg— the configuration file context.name— the name of the option.value— the value to set. if the option is a list (theCFGF_LISTflag is set), only the first value (with index0) is set.
Returns: POSIX OK(0), or non-zero on failure.
cfg_setint
DLLIMPORT int __export cfg_setint (cfg_t * cfg, const char * name, long int value)sets the value of an integer option, by name 🔢
cfg— the configuration file context.name— the name of the option.value— the value to set. if the option is a list (theCFGF_LISTflag is set), only the first value (with index0) is set.
Returns: POSIX OK(0), or non-zero on failure.
cfg_setint16
DLLIMPORT int __export cfg_setint16 (cfg_t * cfg, const char * name, int16_t value)sets the value of a CFGT_INT16 (16-bit signed) option ✨
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.
cfg_setint32
DLLIMPORT int __export cfg_setint32 (cfg_t * cfg, const char * name, int32_t value)sets the value of a CFGT_INT32 (32-bit signed) option ✨
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.
cfg_setint64
DLLIMPORT int __export cfg_setint64 (cfg_t * cfg, const char * name, int64_t value)sets the value of a CFGT_INT64 (64-bit signed) option — big number energy 🔥
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.
cfg_setint8
DLLIMPORT int __export cfg_setint8 (cfg_t * cfg, const char * name, int8_t value)sets the value of a CFGT_INT8 (8-bit signed) option — tiny but mighty 🧚
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.
cfg_setlist
DLLIMPORT int __export cfg_setlist (cfg_t * cfg, const char * name, unsigned int nvalues, ...)sets values for a list option 📋 and all existing values are replaced with the new ones. out with the old, in with the new, slay.
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 thenvaluesparameter. mismatch = bad vibes 💀
Returns: POSIX OK(0), or non-zero on failure.
References: CFG_FAIL, CFG_SUCCESS, CFGF_LIST, and cfg_opt_t::flags.
cfg_setmulti
DLLIMPORT int cfg_setmulti (cfg_t * cfg, const char * name, unsigned int nvalues, char ** values)set an option (create an instance of an option) 🫶
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.
cfg_setnbool
DLLIMPORT int __export cfg_setnbool (cfg_t * cfg, const char * name, cfg_bool_t value, unsigned int index)sets a value of a boolean option, given its name and index 🎯
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. and it is an error to set values with indices larger than0for options without theCFGF_LISTflag set. so don't. 🙈
Returns: POSIX OK(0), or non-zero on failure.
cfg_setnfloat
DLLIMPORT int __export cfg_setnfloat (cfg_t * cfg, const char * name, double value, unsigned int index)sets a value of a floating point option, given its name and index 🎯
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 than0for options without theCFGF_LISTflag set.
Returns: POSIX OK(0), or non-zero on failure.
References: CFG_FAIL, and cfg_opt_t::validcb2.
cfg_setnint
DLLIMPORT int __export cfg_setnint (cfg_t * cfg, const char * name, long int value, unsigned int index)sets a value of an integer option, given its name and index 🎯
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 than0for options without theCFGF_LISTflag set.
Returns: POSIX OK(0), or non-zero on failure.
References: CFG_FAIL, and cfg_opt_t::validcb2.
cfg_setnint16
DLLIMPORT int __export cfg_setnint16 (cfg_t * cfg, const char * name, int16_t value, unsigned int index)sets a value of a CFGT_INT16 (16-bit signed) option at a given list index 🎀
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 be0unlessCFGF_LISTis set.
Returns: POSIX OK(0), or non-zero on failure.
References: CFG_FAIL, and cfg_opt_t::validcb2.
cfg_setnint32
DLLIMPORT int __export cfg_setnint32 (cfg_t * cfg, const char * name, int32_t value, unsigned int index)sets a value of a CFGT_INT32 (32-bit signed) option at a given list index 🎀
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 be0unlessCFGF_LISTis set.
Returns: POSIX OK(0), or non-zero on failure.
References: CFG_FAIL, and cfg_opt_t::validcb2.
DLLIMPORT int __export cfg_setnint64 (cfg_t * cfg, const char * name, int64_t value, unsigned int index)— sets a value on aCFGT_INT64(that's the 64-bit signed one, bestie) option at a specific 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 be0unlessCFGF_LISTis set. no cap,0or nothing.
Returns: POSIX OK(0), or non-zero on failure. 😭
References CFG_FAIL, and cfg_opt_t::validcb2.
DLLIMPORT int __export cfg_setnint8 (cfg_t * cfg, const char * name, int8_t value, unsigned int index)— sets a value on aCFGT_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 be0unlessCFGF_LISTis set.
Returns: POSIX OK(0), or non-zero on failure.
References CFG_FAIL, and cfg_opt_t::validcb2.
DLLIMPORT int __export cfg_setnstr (cfg_t * cfg, const char * name, const char * value, unsigned int index)— okay so the doc says "Set a value of a boolean option given its name and index" but bestie it's literally calledcfg_setnstrand it takes aconst char * value, so it's giving string, not bool 🙈 anyway here's what it does 💖
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. (yes, "privious", the original said it, I'm not fixing it, that's the vibe ✨)index— the index in the option value array that should be modified. It is an error to set values with indices larger than0for options without theCFGF_LISTflag set. so like, don't. 🚫
Returns: POSIX OK(0), or non-zero on failure.
References CFG_FAIL, and cfg_opt_t::validcb2.
DLLIMPORT int __export cfg_setnuint16 (cfg_t * cfg, const char * name, uint16_t value, unsigned int index)— sets a value on aCFGT_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 be0unlessCFGF_LISTis set.
Returns: POSIX OK(0), or non-zero on failure.
References CFG_FAIL, and cfg_opt_t::validcb2.
DLLIMPORT int __export cfg_setnuint32 (cfg_t * cfg, const char * name, uint32_t value, unsigned int index)— sets a value on aCFGT_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 be0unlessCFGF_LISTis set.
Returns: POSIX OK(0), or non-zero on failure.
References CFG_FAIL, and cfg_opt_t::validcb2.
DLLIMPORT int __export cfg_setnuint64 (cfg_t * cfg, const char * name, uint64_t value, unsigned int index)— sets a value on aCFGT_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 be0unlessCFGF_LISTis set.
Returns: POSIX OK(0), or non-zero on failure.
References CFG_FAIL, and cfg_opt_t::validcb2.
DLLIMPORT int __export cfg_setnuint8 (cfg_t * cfg, const char * name, uint8_t value, unsigned int index)— sets a value on aCFGT_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 be0unlessCFGF_LISTis set.
Returns: POSIX OK(0), or non-zero on failure.
References CFG_FAIL, and cfg_opt_t::validcb2.
DLLIMPORT cfg_value_t * cfg_setopt (cfg_t * cfg, cfg_opt_t * opt, const char * value)— sets an option, which lowkey means creating an instance of an option. main character energy 👑
Parameters:
cfg— the configuration file context.opt— the option definition.value— the initial value for the option.
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. that's the whole guest list, literally the whole group chat 💀
DLLIMPORT int __export cfg_setstr (cfg_t * cfg, const char * name, const char * value)— sets 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 (theCFGF_LISTflag is set), only the first value (with index0) is set. so like, index0only, periodt.
Returns: POSIX OK(0), or non-zero on failure.
DLLIMPORT int __export cfg_setuint16 (cfg_t * cfg, const char * name, uint16_t value)— sets the value of aCFGT_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.
DLLIMPORT int __export cfg_setuint32 (cfg_t * cfg, const char * name, uint32_t value)— sets the value of aCFGT_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.
DLLIMPORT int __export cfg_setuint64 (cfg_t * cfg, const char * name, uint64_t value)— sets the value of aCFGT_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.
DLLIMPORT int __export cfg_setuint8 (cfg_t * cfg, const char * name, uint8_t value)— sets the value of aCFGT_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.
DLLIMPORT unsigned int __export cfg_size (cfg_t * cfg, const char * name)— returns 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,0will be returned (ie, the option value is not set at all). zero, bestie. it's giving empty 🫥
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. so yeah, ints/floats/bools are always invited to the party, strings and lists can ghost 🌸
Parameters:
cfg— the configuration file context.name— the name of the option.
DLLIMPORT char *__export cfg_tilde_expand (const char * filename)— does tilde expansion (~->$HOME) on the filename. cute little glow-up for your paths ✨
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. ⚠️ you own that memory, bestie, free it or it's a leak, no cap.
DLLIMPORT const char *__export cfg_title (cfg_t * cfg)— returns the title of a section 👑
Parameters:
cfg— the configuration file context.
Returns: the title, or 0 if there is no title. This string should not be modified. like, look but don't touch 💅
References cfg_t::title.
💖 Author 💖
Generated automatically by Doxygen for libConfuse from the source code. yeah, a robot wrote it, but I translated it into feelings 🫶
okay that's the whole page, bestie!! it was libConfuse, Version 3.4, dated confuse.h(3) — thanks for reading all 12 parts with me, you're literally an icon, go free your strings and slay 💖✨🎀🦋🌸
📦 where this page comes from
- fedora 43: libconfuse 3.4-1.fc43 · ISC
- fedora 43: libconfuse 3.4-1.fc43 · ISC
- fedora 44: libconfuse 3.4-1.fc44 · ISC
- fedora 44: libconfuse 3.4-1.fc44 · ISC
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms