--- embedaddon/confuse/doc/man/man3/confuse.h.3 2017/01/24 14:48:55 1.1.1.1 +++ embedaddon/confuse/doc/man/man3/confuse.h.3 2021/03/17 00:49:17 1.1.1.2 @@ -1,16 +1,15 @@ -.TH "confuse.h" 3 "21 Feb 2010" "Version 2.7" "confuse" \" -*- nroff -*- +.TH "confuse.h" 3 "Thu Jun 25 2020" "Version 3.3" "confuse" \" -*- nroff -*- .ad l .nh .SH NAME -confuse.h \- A configuration file parser library. +confuse.h \- A configuration file parser library\&. -.PP .SH SYNOPSIS .br .PP -\fC#include \fP +\fC#include \fP .br -\fC#include \fP +\fC#include \fP .br .SS "Data Structures" @@ -19,195 +18,231 @@ confuse.h \- A configuration file parser library. .ti -1c .RI "struct \fBcfg_t\fP" .br -.RI "\fIData structure holding information about a 'section'. \fP" +.RI "Data structure holding information about a 'section'\&. " .ti -1c .RI "union \fBcfg_value_t\fP" .br -.RI "\fIData structure holding the value of a fundamental option value. \fP" +.RI "Data structure holding the value of a fundamental option value\&. " .ti -1c +.RI "union \fBcfg_simple_t\fP" +.br +.RI "Data structure holding the pointer to a user provided variable defined with CFG_SIMPLE_*\&. " +.ti -1c .RI "struct \fBcfg_defvalue_t\fP" .br -.RI "\fIData structure holding the default value given by the initialization macros. \fP" +.RI "Data structure holding the default value given by the initialization macros\&. " .ti -1c .RI "struct \fBcfg_opt_t\fP" .br -.RI "\fIData structure holding information about an option. \fP" +.RI "Data structure holding information about an option\&. " .in -1c -.SS "Defines" +.SS "Macros" .in +1c .ti -1c -.RI "#define \fBCFGF_NONE\fP 0" +.RI "#define \fBCFGF_NONE\fP (0)" .br -.RI "\fIFlags. \fP" +.RI "Flags\&. " .ti -1c -.RI "#define \fBCFGF_MULTI\fP 1" +.RI "#define \fBCFGF_MULTI\fP (1 << 0)" .br -.RI "\fIoption may be specified multiple times (only applies to sections) \fP" +.RI "option may be specified multiple times (only applies to sections) " .ti -1c -.RI "#define \fBCFGF_LIST\fP 2" +.RI "#define \fBCFGF_LIST\fP (1 << 1)" .br -.RI "\fIoption is a list \fP" +.RI "option is a list " .ti -1c -.RI "#define \fBCFGF_NOCASE\fP 4" +.RI "#define \fBCFGF_NOCASE\fP (1 << 2)" .br -.RI "\fIconfiguration file is case insensitive \fP" +.RI "configuration file is case insensitive " .ti -1c -.RI "#define \fBCFGF_TITLE\fP 8" +.RI "#define \fBCFGF_TITLE\fP (1 << 3)" .br -.RI "\fIoption has a title (only applies to sections) \fP" +.RI "option has a title (only applies to sections) " .ti -1c -.RI "#define \fBCFGF_NODEFAULT\fP 16" +.RI "#define \fBCFGF_NODEFAULT\fP (1 << 4)" .br -.RI "\fIoption has no default value \fP" +.RI "option has no default value " .ti -1c -.RI "#define \fBCFGF_NO_TITLE_DUPES\fP 32" +.RI "#define \fBCFGF_NO_TITLE_DUPES\fP (1 << 5)" .br -.RI "\fImultiple section titles must be unique (duplicates raises an error, only applies to sections) \fP" +.RI "multiple section titles must be unique (duplicates raises an error, only applies to sections) " .ti -1c +.RI "#define \fBCFGF_IGNORE_UNKNOWN\fP (1 << 8)" +.br +.RI "ignore unknown options in configuration files " +.ti -1c +.RI "#define \fBCFGF_DEPRECATED\fP (1 << 9)" +.br +.RI "option is deprecated and should be ignored\&. " +.ti -1c +.RI "#define \fBCFGF_DROP\fP (1 << 10)" +.br +.RI "option should be dropped after parsing " +.ti -1c +.RI "#define \fBCFGF_COMMENTS\fP (1 << 11)" +.br +.RI "Enable option annotation/comments support\&. " +.ti -1c +.RI "#define \fBCFGF_MODIFIED\fP (1 << 12)" +.br +.RI "option has been changed from its default value " +.ti -1c +.RI "#define \fBCFGF_KEYSTRVAL\fP (1 << 13)" +.br +.RI "section has free-form key=value string options created when parsing file " +.ti -1c .RI "#define \fBCFG_SUCCESS\fP 0" .br -.RI "\fIReturn codes from \fBcfg_parse()\fP. \fP" +.RI "Return codes from \fBcfg_parse()\fP, \fBcfg_parse_boolean()\fP, and cfg_set*() functions\&. " .ti -1c -.RI "#define \fBCFG_STR\fP(name, def, flags) __CFG_STR(name, def, flags, 0, 0)" +.RI "#define \fBCFG_STR\fP(name, def, flags) __CFG_STR(name, def, flags, 0, 0)" .br -.RI "\fIInitialize a string option. \fP" +.RI "Initialize a string option\&. " .ti -1c -.RI "#define \fBCFG_STR_LIST\fP(name, def, flags) __CFG_STR_LIST(name, def, flags, 0, 0)" +.RI "#define \fBCFG_STR_LIST\fP(name, def, flags) __CFG_STR_LIST(name, def, flags, 0, 0)" .br -.RI "\fIInitialize a string list option. \fP" +.RI "Initialize a string list option\&. " .ti -1c -.RI "#define \fBCFG_STR_CB\fP(name, def, flags, cb) __CFG_STR(name, def, flags, 0, cb)" +.RI "#define \fBCFG_STR_CB\fP(name, def, flags, cb) __CFG_STR(name, def, flags, 0, cb)" .br -.RI "\fIInitialize a string option with a value parsing callback. \fP" +.RI "Initialize a string option with a value parsing callback\&. " .ti -1c -.RI "#define \fBCFG_STR_LIST_CB\fP(name, def, flags, cb) __CFG_STR_LIST(name, def, flags, 0, cb)" +.RI "#define \fBCFG_STR_LIST_CB\fP(name, def, flags, cb) __CFG_STR_LIST(name, def, flags, 0, cb)" .br -.RI "\fIInitialize a string list option with a value parsing callback. \fP" +.RI "Initialize a string list option with a value parsing callback\&. " .ti -1c -.RI "#define \fBCFG_SIMPLE_STR\fP(name, svalue) __CFG_STR(name, 0, CFGF_NONE, svalue, 0)" +.RI "#define \fBCFG_SIMPLE_STR\fP(name, svalue) __CFG_STR(name, 0, \fBCFGF_NONE\fP, svalue, 0)" .br -.RI "\fIInitialize a 'simple' string option. \fP" +.RI "Initialize a 'simple' string option\&. " .ti -1c -.RI "#define \fBCFG_INT\fP(name, def, flags) __CFG_INT(name, def, flags, 0, 0)" +.RI "#define \fBCFG_INT\fP(name, def, flags) __CFG_INT(name, def, flags, 0, 0)" .br -.RI "\fIInitialize an integer option. \fP" +.RI "Initialize an integer option\&. " .ti -1c -.RI "#define \fBCFG_INT_LIST\fP(name, def, flags) __CFG_INT_LIST(name, def, flags, 0, 0)" +.RI "#define \fBCFG_INT_LIST\fP(name, def, flags) __CFG_INT_LIST(name, def, flags, 0, 0)" .br -.RI "\fIInitialize an integer list option. \fP" +.RI "Initialize an integer list option\&. " .ti -1c -.RI "#define \fBCFG_INT_CB\fP(name, def, flags, cb) __CFG_INT(name, def, flags, 0, cb)" +.RI "#define \fBCFG_INT_CB\fP(name, def, flags, cb) __CFG_INT(name, def, flags, 0, cb)" .br -.RI "\fIInitialize an integer option with a value parsing callback. \fP" +.RI "Initialize an integer option with a value parsing callback\&. " .ti -1c -.RI "#define \fBCFG_INT_LIST_CB\fP(name, def, flags, cb) __CFG_INT_LIST(name, def, flags, 0, cb)" +.RI "#define \fBCFG_INT_LIST_CB\fP(name, def, flags, cb) __CFG_INT_LIST(name, def, flags, 0, cb)" .br -.RI "\fIInitialize an integer list option with a value parsing callback. \fP" +.RI "Initialize an integer list option with a value parsing callback\&. " .ti -1c -.RI "#define \fBCFG_SIMPLE_INT\fP(name, svalue) __CFG_INT(name, 0, CFGF_NONE, svalue, 0)" +.RI "#define \fBCFG_SIMPLE_INT\fP(name, svalue) __CFG_INT(name, 0, \fBCFGF_NONE\fP, svalue, 0)" .br -.RI "\fIInitialize a 'simple' integer option (see documentation for CFG_SIMPLE_STR for more information). \fP" +.RI "Initialize a 'simple' integer option (see documentation for CFG_SIMPLE_STR for more information)\&. " .ti -1c -.RI "#define \fBCFG_FLOAT\fP(name, def, flags) __CFG_FLOAT(name, def, flags, 0, 0)" +.RI "#define \fBCFG_FLOAT\fP(name, def, flags) __CFG_FLOAT(name, def, flags, 0, 0)" .br -.RI "\fIInitialize a floating point option. \fP" +.RI "Initialize a floating point option\&. " .ti -1c -.RI "#define \fBCFG_FLOAT_LIST\fP(name, def, flags) __CFG_FLOAT_LIST(name, def, flags, 0, 0)" +.RI "#define \fBCFG_FLOAT_LIST\fP(name, def, flags) __CFG_FLOAT_LIST(name, def, flags, 0, 0)" .br -.RI "\fIInitialize a floating point list option. \fP" +.RI "Initialize a floating point list option\&. " .ti -1c -.RI "#define \fBCFG_FLOAT_CB\fP(name, def, flags, cb) __CFG_FLOAT(name, def, flags, 0, cb)" +.RI "#define \fBCFG_FLOAT_CB\fP(name, def, flags, cb) __CFG_FLOAT(name, def, flags, 0, cb)" .br -.RI "\fIInitialize a floating point option with a value parsing callback. \fP" +.RI "Initialize a floating point option with a value parsing callback\&. " .ti -1c -.RI "#define \fBCFG_FLOAT_LIST_CB\fP(name, def, flags, cb) __CFG_FLOAT_LIST(name, def, flags, 0, cb)" +.RI "#define \fBCFG_FLOAT_LIST_CB\fP(name, def, flags, cb) __CFG_FLOAT_LIST(name, def, flags, 0, cb)" .br -.RI "\fIInitialize a floating point list option with a value parsing callback. \fP" +.RI "Initialize a floating point list option with a value parsing callback\&. " .ti -1c -.RI "#define \fBCFG_SIMPLE_FLOAT\fP(name, svalue) __CFG_FLOAT(name, 0, CFGF_NONE, svalue, 0)" +.RI "#define \fBCFG_SIMPLE_FLOAT\fP(name, svalue) __CFG_FLOAT(name, 0, \fBCFGF_NONE\fP, svalue, 0)" .br -.RI "\fIInitialize a 'simple' floating point option (see documentation for CFG_SIMPLE_STR for more information). \fP" +.RI "Initialize a 'simple' floating point option (see documentation for CFG_SIMPLE_STR for more information)\&. " .ti -1c -.RI "#define \fBCFG_BOOL\fP(name, def, flags) __CFG_BOOL(name, def, flags, 0, 0)" +.RI "#define \fBCFG_BOOL\fP(name, def, flags) __CFG_BOOL(name, def, flags, 0, 0)" .br -.RI "\fIInitialize a boolean option. \fP" +.RI "Initialize a boolean option\&. " .ti -1c -.RI "#define \fBCFG_BOOL_LIST\fP(name, def, flags) __CFG_BOOL_LIST(name, def, flags, 0, 0)" +.RI "#define \fBCFG_BOOL_LIST\fP(name, def, flags) __CFG_BOOL_LIST(name, def, flags, 0, 0)" .br -.RI "\fIInitialize a boolean list option. \fP" +.RI "Initialize a boolean list option\&. " .ti -1c -.RI "#define \fBCFG_BOOL_CB\fP(name, def, flags, cb) __CFG_BOOL(name, def, flags, 0, cb)" +.RI "#define \fBCFG_BOOL_CB\fP(name, def, flags, cb) __CFG_BOOL(name, def, flags, 0, cb)" .br -.RI "\fIInitialize a boolean option with a value parsing callback. \fP" +.RI "Initialize a boolean option with a value parsing callback\&. " .ti -1c -.RI "#define \fBCFG_BOOL_LIST_CB\fP(name, def, flags, cb) __CFG_BOOL_LIST(name, def, flags, 0, cb)" +.RI "#define \fBCFG_BOOL_LIST_CB\fP(name, def, flags, cb) __CFG_BOOL_LIST(name, def, flags, 0, cb)" .br -.RI "\fIInitialize a boolean list option with a value parsing callback. \fP" +.RI "Initialize a boolean list option with a value parsing callback\&. " .ti -1c -.RI "#define \fBCFG_SIMPLE_BOOL\fP(name, svalue) __CFG_BOOL(name, cfg_false, CFGF_NONE, svalue, 0)" +.RI "#define \fBCFG_SIMPLE_BOOL\fP(name, svalue) __CFG_BOOL(name, cfg_false, \fBCFGF_NONE\fP, svalue, 0)" .br -.RI "\fIInitialize a 'simple' boolean option (see documentation for CFG_SIMPLE_STR for more information). \fP" +.RI "Initialize a 'simple' boolean option (see documentation for CFG_SIMPLE_STR for more information)\&. " .ti -1c -.RI "#define \fBCFG_SEC\fP(name, opts, flags) {name,CFGT_SEC,0,0,flags,opts,{0,0,cfg_false,0,0},0,0,0,0,0,0}" +.RI "#define \fBCFG_SEC\fP(name, opts, flags) {name,0,\fBCFGT_SEC\fP,0,0,flags,opts,{0,0,cfg_false,0,0},0,{0},0,0,0,0,0}" .br -.RI "\fIInitialize a section. \fP" +.RI "Initialize a section\&. " .ti -1c -.RI "#define \fBCFG_FUNC\fP(name, func) {name,CFGT_FUNC,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},func,0,0,0,0,0}" +.RI "#define \fBCFG_FUNC\fP(name, func) {name,0,\fBCFGT_FUNC\fP,0,0,\fBCFGF_NONE\fP,0,{0,0,cfg_false,0,0},func,{0},0,0,0,0,0}" .br -.RI "\fIInitialize a function. \fP" +.RI "Initialize a function\&. " .ti -1c -.RI "#define \fBCFG_PTR_CB\fP(name, def, flags, parsecb, freecb) __CFG_PTR(name, def, flags, 0, parsecb, freecb)" +.RI "#define \fBCFG_PTR_CB\fP(name, def, flags, parsecb, freecb) __CFG_PTR(name, def, flags, 0, parsecb, freecb)" .br -.RI "\fIInitialize a user-defined option. \fP" +.RI "Initialize a user-defined option\&. " .ti -1c -.RI "#define \fBCFG_PTR_LIST_CB\fP(name, def, flags, parsecb, freecb) __CFG_PTR(name, def, flags | CFGF_LIST, 0, parsecb, freecb)" +.RI "#define \fBCFG_PTR_LIST_CB\fP(name, def, flags, parsecb, freecb) __CFG_PTR(name, def, flags | \fBCFGF_LIST\fP, 0, parsecb, freecb)" .br -.RI "\fIInitialize a list of user-defined options. \fP" +.RI "Initialize a list of user-defined options\&. " .ti -1c -.RI "#define \fBCFG_END\fP() {0,CFGT_NONE,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},0,0,0,0,0,0}" +.RI "#define \fBCFG_END\fP() {0,0,CFGT_NONE,0,0,\fBCFGF_NONE\fP,0,{0,0,cfg_false,0,0},0,{0},0,0,0,0,0}" .br -.RI "\fITerminate list of options. \fP" +.RI "Terminate list of options\&. " .in -1c .SS "Typedefs" .in +1c .ti -1c -.RI "typedef int(* \fBcfg_func_t\fP )(\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, int argc, const char **argv)" +.RI "typedef int(* \fBcfg_func_t\fP) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, int argc, const char **argv)" .br -.RI "\fIFunction prototype used by CFGT_FUNC options. \fP" +.RI "Function prototype used by CFGT_FUNC options\&. " .ti -1c -.RI "typedef void(* \fBcfg_print_func_t\fP )(\fBcfg_opt_t\fP *opt, unsigned int index, FILE *fp)" +.RI "typedef void(* \fBcfg_print_func_t\fP) (\fBcfg_opt_t\fP *opt, unsigned int index, FILE *fp)" .br -.RI "\fIFunction prototype used by the cfg_print_ functions. \fP" +.RI "Function prototype used by the cfg_print_ functions\&. " .ti -1c -.RI "typedef int(* \fBcfg_callback_t\fP )(\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, const char *value, void *result)" +.RI "typedef int(* \fBcfg_callback_t\fP) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, const char *value, void *result)" .br -.RI "\fIValue parsing callback prototype. \fP" +.RI "Value parsing callback prototype\&. " .ti -1c -.RI "typedef int(* \fBcfg_validate_callback_t\fP )(\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt)" +.RI "typedef int(* \fBcfg_validate_callback_t\fP) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt)" .br -.RI "\fIValidating callback prototype. \fP" +.RI "Validating callback prototype\&. " .ti -1c -.RI "typedef void(* \fBcfg_free_func_t\fP )(void *value)" +.RI "typedef int(* \fBcfg_validate_callback2_t\fP) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, void *value)" .br -.RI "\fIUser-defined memory release function for CFG_PTR values. \fP" +.RI "Validating callback2 prototype\&. " .ti -1c -.RI "typedef void(* \fBcfg_errfunc_t\fP )(\fBcfg_t\fP *cfg, const char *fmt, va_list ap)" +.RI "typedef void(* \fBcfg_free_func_t\fP) (void *value)" .br -.RI "\fIError reporting function. \fP" +.RI "User-defined memory release function for CFG_PTR values\&. " +.ti -1c +.RI "typedef void(* \fBcfg_errfunc_t\fP) (\fBcfg_t\fP *cfg, const char *fmt, va_list ap)" +.br +.RI "Error reporting function\&. " +.ti -1c +.RI "typedef int(* \fBcfg_print_filter_func_t\fP) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt)" +.br +.RI "Print filter function\&. " .in -1c .SS "Enumerations" .in +1c .ti -1c -.RI "enum \fBcfg_type_t\fP { , \fBCFGT_INT\fP, \fBCFGT_FLOAT\fP, \fBCFGT_STR\fP, \fBCFGT_BOOL\fP, \fBCFGT_SEC\fP, \fBCFGT_FUNC\fP, \fBCFGT_PTR\fP }" +.RI "enum \fBcfg_type_t\fP { , \fBCFGT_INT\fP, \fBCFGT_FLOAT\fP, \fBCFGT_STR\fP, \fBCFGT_BOOL\fP, \fBCFGT_SEC\fP, \fBCFGT_FUNC\fP, \fBCFGT_PTR\fP, \fBCFGT_COMMENT\fP }" .br -.RI "\fIFundamental option types. \fP" +.RI "Fundamental option types\&. " .ti -1c .RI "enum \fBcfg_bool_t\fP " .br -.RI "\fIBoolean values. \fP" +.RI "Boolean values\&. " .in -1c .SS "Functions" @@ -215,280 +250,355 @@ confuse.h \- A configuration file parser library. .ti -1c .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_init\fP (\fBcfg_opt_t\fP *opts, cfg_flag_t flags)" .br -.RI "\fICreate and initialize a \fBcfg_t\fP structure. \fP" +.RI "Create and initialize a \fBcfg_t\fP structure\&. " .ti -1c +.RI "DLLIMPORT int __export \fBcfg_add_searchpath\fP (\fBcfg_t\fP *cfg, const char *dir)" +.br +.RI "Add a searchpath directory to the configuration context, the const char* argument will be duplicated and then freed as part of the usual context takedown\&. " +.ti -1c +.RI "DLLIMPORT char *__export \fBcfg_searchpath\fP (cfg_searchpath_t *path, const char *file)" +.br +.RI "Search the linked-list of cfg_searchpath_t for the specified file\&. " +.ti -1c .RI "DLLIMPORT int __export \fBcfg_parse\fP (\fBcfg_t\fP *cfg, const char *filename)" .br -.RI "\fIParse a configuration file. \fP" +.RI "Parse a configuration file\&. " .ti -1c .RI "DLLIMPORT int __export \fBcfg_parse_fp\fP (\fBcfg_t\fP *cfg, FILE *fp)" .br -.RI "\fISame as \fBcfg_parse()\fP above, but takes an already opened file as argument. \fP" +.RI "Same as \fBcfg_parse()\fP above, but takes an already opened file as argument\&. " .ti -1c .RI "DLLIMPORT int __export \fBcfg_parse_buf\fP (\fBcfg_t\fP *cfg, const char *buf)" .br -.RI "\fISame as \fBcfg_parse()\fP above, but takes a character buffer as argument. \fP" +.RI "Same as \fBcfg_parse()\fP above, but takes a character buffer as argument\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_free_value\fP (\fBcfg_opt_t\fP *opt)" +.RI "DLLIMPORT int __export \fBcfg_free_value\fP (\fBcfg_opt_t\fP *opt)" .br -.RI "\fIFree the memory allocated for the values of a given option. \fP" +.RI "Free the memory allocated for the values of a given option\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_free\fP (\fBcfg_t\fP *cfg)" +.RI "DLLIMPORT int __export \fBcfg_free\fP (\fBcfg_t\fP *cfg)" .br -.RI "\fIFree a \fBcfg_t\fP context. \fP" +.RI "Free a \fBcfg_t\fP context\&. " .ti -1c .RI "DLLIMPORT \fBcfg_errfunc_t\fP __export \fBcfg_set_error_function\fP (\fBcfg_t\fP *cfg, \fBcfg_errfunc_t\fP errfunc)" .br -.RI "\fIInstall a user-defined error reporting function. \fP" +.RI "Install a user-defined error reporting function\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_error\fP (\fBcfg_t\fP *cfg, const char *fmt,...)" +.RI "DLLIMPORT void __export \fBcfg_error\fP (\fBcfg_t\fP *cfg, const char *fmt,\&.\&.\&.)" .br -.RI "\fIShow a parser error. \fP" +.RI "Show a parser error\&. " .ti -1c +.RI "DLLIMPORT char *__export \fBcfg_opt_getcomment\fP (\fBcfg_opt_t\fP *opt)" +.br +.RI "Returns the option comment\&. " +.ti -1c +.RI "DLLIMPORT char *__export \fBcfg_getcomment\fP (\fBcfg_t\fP *cfg, const char *name)" +.br +.RI "Returns the option comment\&. " +.ti -1c .RI "DLLIMPORT signed long __export \fBcfg_opt_getnint\fP (\fBcfg_opt_t\fP *opt, unsigned int index)" .br -.RI "\fIReturns the value of an integer option, given a \fBcfg_opt_t\fP pointer. \fP" +.RI "Returns the value of an integer option, given a \fBcfg_opt_t\fP pointer\&. " .ti -1c .RI "DLLIMPORT long int __export \fBcfg_getnint\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)" .br -.RI "\fIIndexed version of \fBcfg_getint()\fP, used for lists. \fP" +.RI "Indexed version of \fBcfg_getint()\fP, used for lists\&. " .ti -1c .RI "DLLIMPORT long int __export \fBcfg_getint\fP (\fBcfg_t\fP *cfg, const char *name)" .br -.RI "\fIReturns the value of an integer option. \fP" +.RI "Returns the value of an integer option\&. " .ti -1c .RI "DLLIMPORT double __export \fBcfg_opt_getnfloat\fP (\fBcfg_opt_t\fP *opt, unsigned int index)" .br -.RI "\fIReturns the value of a floating point option, given a \fBcfg_opt_t\fP pointer. \fP" +.RI "Returns the value of a floating point option, given a \fBcfg_opt_t\fP pointer\&. " .ti -1c .RI "DLLIMPORT double __export \fBcfg_getnfloat\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)" .br -.RI "\fIIndexed version of \fBcfg_getfloat()\fP, used for lists. \fP" +.RI "Indexed version of \fBcfg_getfloat()\fP, used for lists\&. " .ti -1c .RI "DLLIMPORT double __export \fBcfg_getfloat\fP (\fBcfg_t\fP *cfg, const char *name)" .br -.RI "\fIReturns the value of a floating point option. \fP" +.RI "Returns the value of a floating point option\&. " .ti -1c .RI "DLLIMPORT char *__export \fBcfg_opt_getnstr\fP (\fBcfg_opt_t\fP *opt, unsigned int index)" .br -.RI "\fIReturns the value of a string option, given a \fBcfg_opt_t\fP pointer. \fP" +.RI "Returns the value of a string option, given a \fBcfg_opt_t\fP pointer\&. " .ti -1c .RI "DLLIMPORT char *__export \fBcfg_getnstr\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)" .br -.RI "\fIIndexed version of \fBcfg_getstr()\fP, used for lists. \fP" +.RI "Indexed version of \fBcfg_getstr()\fP, used for lists\&. " .ti -1c .RI "DLLIMPORT char *__export \fBcfg_getstr\fP (\fBcfg_t\fP *cfg, const char *name)" .br -.RI "\fIReturns the value of a string option. \fP" +.RI "Returns the value of a string option\&. " .ti -1c .RI "DLLIMPORT \fBcfg_bool_t\fP __export \fBcfg_opt_getnbool\fP (\fBcfg_opt_t\fP *opt, unsigned int index)" .br -.RI "\fIReturns the value of a boolean option, given a \fBcfg_opt_t\fP pointer. \fP" +.RI "Returns the value of a boolean option, given a \fBcfg_opt_t\fP pointer\&. " .ti -1c .RI "DLLIMPORT \fBcfg_bool_t\fP __export \fBcfg_getnbool\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)" .br -.RI "\fIIndexed version of \fBcfg_getbool()\fP, used for lists. \fP" +.RI "Indexed version of \fBcfg_getbool()\fP, used for lists\&. " .ti -1c .RI "DLLIMPORT \fBcfg_bool_t\fP __export \fBcfg_getbool\fP (\fBcfg_t\fP *cfg, const char *name)" .br -.RI "\fIReturns the value of a boolean option. \fP" +.RI "Returns the value of a boolean option\&. " .ti -1c .RI "DLLIMPORT void *__export \fBcfg_getptr\fP (\fBcfg_t\fP *cfg, const char *name)" .br -.RI "\fIReturns the value of a user-defined option (void pointer). \fP" +.RI "Returns the value of a user-defined option (void pointer)\&. " .ti -1c .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_opt_getnsec\fP (\fBcfg_opt_t\fP *opt, unsigned int index)" .br -.RI "\fIReturns the value of a section option, given a \fBcfg_opt_t\fP pointer. \fP" +.RI "Returns the value of a section option, given a \fBcfg_opt_t\fP pointer\&. " .ti -1c .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_getnsec\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)" .br -.RI "\fIIndexed version of \fBcfg_getsec()\fP, used for sections with the CFGF_MULTI flag set. \fP" +.RI "Indexed version of \fBcfg_getsec()\fP, used for sections with the CFGF_MULTI flag set\&. " .ti -1c .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_opt_gettsec\fP (\fBcfg_opt_t\fP *opt, const char *title)" .br -.RI "\fIReturns the value of a section option, given a \fBcfg_opt_t\fP pointer and the title. \fP" +.RI "Returns the value of a section option, given a \fBcfg_opt_t\fP pointer and the title\&. " .ti -1c .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_gettsec\fP (\fBcfg_t\fP *cfg, const char *name, const char *title)" .br -.RI "\fIReturn a section given the title, used for section with the CFGF_TITLE flag set. \fP" +.RI "Return a section given the title, used for section with the CFGF_TITLE flag set\&. " .ti -1c .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_getsec\fP (\fBcfg_t\fP *cfg, const char *name)" .br -.RI "\fIReturns the value of a section option. \fP" +.RI "Returns the value of a section option\&. " .ti -1c .RI "DLLIMPORT unsigned int __export \fBcfg_opt_size\fP (\fBcfg_opt_t\fP *opt)" .br -.RI "\fIReturn the number of values this option has. \fP" +.RI "Return the number of values this option has\&. " .ti -1c .RI "DLLIMPORT unsigned int __export \fBcfg_size\fP (\fBcfg_t\fP *cfg, const char *name)" .br -.RI "\fIReturn the number of values this option has. \fP" +.RI "Return the number of values this option has\&. " .ti -1c -.RI "DLLIMPORT const char *__export \fBcfg_title\fP (\fBcfg_t\fP *cfg)" +.RI "const DLLIMPORT char *__export \fBcfg_title\fP (\fBcfg_t\fP *cfg)" .br -.RI "\fIReturn the title of a section. \fP" +.RI "Return the title of a section\&. " .ti -1c -.RI "DLLIMPORT const char *__export \fBcfg_name\fP (\fBcfg_t\fP *cfg)" +.RI "const DLLIMPORT char *__export \fBcfg_name\fP (\fBcfg_t\fP *cfg)" .br -.RI "\fIReturn the name of a section. \fP" +.RI "Return the name of a section\&. " .ti -1c -.RI "DLLIMPORT const char *__export \fBcfg_opt_name\fP (\fBcfg_opt_t\fP *opt)" +.RI "const DLLIMPORT char *__export \fBcfg_opt_name\fP (\fBcfg_opt_t\fP *opt)" .br -.RI "\fIReturn the name of an option. \fP" +.RI "Return the name of an option\&. " .ti -1c +.RI "const DLLIMPORT char * \fBcfg_opt_getstr\fP (\fBcfg_opt_t\fP *opt)" +.br +.RI "Return the string value of a key=value pair\&. " +.ti -1c .RI "DLLIMPORT int __export \fBcfg_include\fP (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, int argc, const char **argv)" .br -.RI "\fIPredefined include-function. \fP" +.RI "Predefined include-function\&. " .ti -1c .RI "DLLIMPORT char *__export \fBcfg_tilde_expand\fP (const char *filename)" .br -.RI "\fIDoes tilde expansion (~ -> $HOME) on the filename. \fP" +.RI "Does tilde expansion (~ -> $HOME) on the filename\&. " .ti -1c .RI "DLLIMPORT int __export \fBcfg_parse_boolean\fP (const char *s)" .br -.RI "\fIParse a boolean option string. \fP" +.RI "Parse a boolean option string\&. " .ti -1c +.RI "DLLIMPORT \fBcfg_opt_t\fP * \fBcfg_getnopt\fP (\fBcfg_t\fP *cfg, unsigned int index)" +.br +.RI "Return the nth option in a file or section\&. " +.ti -1c .RI "DLLIMPORT \fBcfg_opt_t\fP *__export \fBcfg_getopt\fP (\fBcfg_t\fP *cfg, const char *name)" .br -.RI "\fIReturn an option given it's name. \fP" +.RI "Return an option given it's name\&. " .ti -1c -.RI "DLLIMPORT \fBcfg_value_t\fP * \fBcfg_setopt\fP (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, char *value)" +.RI "DLLIMPORT \fBcfg_value_t\fP * \fBcfg_setopt\fP (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, const char *value)" .br -.RI "\fISet an option (create an instance of an option). \fP" +.RI "Set an option (create an instance of an option)\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_opt_setnint\fP (\fBcfg_opt_t\fP *opt, long int value, unsigned int index)" +.RI "DLLIMPORT int __export \fBcfg_opt_setcomment\fP (\fBcfg_opt_t\fP *opt, char *comment)" .br -.RI "\fISet a value of an integer option. \fP" +.RI "Annotate an option\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_setint\fP (\fBcfg_t\fP *cfg, const char *name, long int value)" +.RI "DLLIMPORT int __export \fBcfg_setcomment\fP (\fBcfg_t\fP *cfg, const char *name, char *comment)" .br -.RI "\fISet the value of an integer option given its name. \fP" +.RI "Annotate an option given its name\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_setnint\fP (\fBcfg_t\fP *cfg, const char *name, long int value, unsigned int index)" +.RI "DLLIMPORT int __export \fBcfg_opt_setnint\fP (\fBcfg_opt_t\fP *opt, long int value, unsigned int index)" .br -.RI "\fISet a value of an integer option given its name and index. \fP" +.RI "Set a value of an integer option\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_opt_setnfloat\fP (\fBcfg_opt_t\fP *opt, double value, unsigned int index)" +.RI "DLLIMPORT int __export \fBcfg_setint\fP (\fBcfg_t\fP *cfg, const char *name, long int value)" .br -.RI "\fISet a value of a floating point option. \fP" +.RI "Set the value of an integer option given its name\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_setfloat\fP (\fBcfg_t\fP *cfg, const char *name, double value)" +.RI "DLLIMPORT int __export \fBcfg_setnint\fP (\fBcfg_t\fP *cfg, const char *name, long int value, unsigned int index)" .br -.RI "\fISet the value of a floating point option given its name. \fP" +.RI "Set a value of an integer option given its name and index\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_setnfloat\fP (\fBcfg_t\fP *cfg, const char *name, double value, unsigned int index)" +.RI "DLLIMPORT int __export \fBcfg_opt_setnfloat\fP (\fBcfg_opt_t\fP *opt, double value, unsigned int index)" .br -.RI "\fISet a value of a floating point option given its name and index. \fP" +.RI "Set a value of a floating point option\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_opt_setnbool\fP (\fBcfg_opt_t\fP *opt, \fBcfg_bool_t\fP value, unsigned int index)" +.RI "DLLIMPORT int __export \fBcfg_setfloat\fP (\fBcfg_t\fP *cfg, const char *name, double value)" .br -.RI "\fISet a value of a boolean option. \fP" +.RI "Set the value of a floating point option given its name\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_setbool\fP (\fBcfg_t\fP *cfg, const char *name, \fBcfg_bool_t\fP value)" +.RI "DLLIMPORT int __export \fBcfg_setnfloat\fP (\fBcfg_t\fP *cfg, const char *name, double value, unsigned int index)" .br -.RI "\fISet the value of a boolean option given its name. \fP" +.RI "Set a value of a floating point option given its name and index\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_setnbool\fP (\fBcfg_t\fP *cfg, const char *name, \fBcfg_bool_t\fP value, unsigned int index)" +.RI "DLLIMPORT int __export \fBcfg_opt_setnbool\fP (\fBcfg_opt_t\fP *opt, \fBcfg_bool_t\fP value, unsigned int index)" .br -.RI "\fISet a value of a boolean option given its name and index. \fP" +.RI "Set a value of a boolean option\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_opt_setnstr\fP (\fBcfg_opt_t\fP *opt, const char *value, unsigned int index)" +.RI "DLLIMPORT int __export \fBcfg_setbool\fP (\fBcfg_t\fP *cfg, const char *name, \fBcfg_bool_t\fP value)" .br -.RI "\fISet a value of a string option. \fP" +.RI "Set the value of a boolean option given its name\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_setstr\fP (\fBcfg_t\fP *cfg, const char *name, const char *value)" +.RI "DLLIMPORT int __export \fBcfg_setnbool\fP (\fBcfg_t\fP *cfg, const char *name, \fBcfg_bool_t\fP value, unsigned int index)" .br -.RI "\fISet the value of a string option given its name. \fP" +.RI "Set a value of a boolean option given its name and index\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_setnstr\fP (\fBcfg_t\fP *cfg, const char *name, const char *value, unsigned int index)" +.RI "DLLIMPORT int __export \fBcfg_opt_setnstr\fP (\fBcfg_opt_t\fP *opt, const char *value, unsigned int index)" .br -.RI "\fISet a value of a boolean option given its name and index. \fP" +.RI "Set a value of a string option\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_setlist\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int nvalues,...)" +.RI "DLLIMPORT int __export \fBcfg_setstr\fP (\fBcfg_t\fP *cfg, const char *name, const char *value)" .br -.RI "\fISet values for a list option. \fP" +.RI "Set the value of a string option given its name\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_addlist\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int nvalues,...)" +.RI "DLLIMPORT int __export \fBcfg_setnstr\fP (\fBcfg_t\fP *cfg, const char *name, const char *value, unsigned int index)" .br -.RI "\fIAdd values for a list option. \fP" +.RI "Set a value of a boolean option given its name and index\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_opt_nprint_var\fP (\fBcfg_opt_t\fP *opt, unsigned int index, FILE *fp)" +.RI "DLLIMPORT int __export \fBcfg_setlist\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int nvalues,\&.\&.\&.)" .br -.RI "\fIDefault value print function. \fP" +.RI "Set values for a list option\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_opt_print_indent\fP (\fBcfg_opt_t\fP *opt, FILE *fp, int indent)" +.RI "DLLIMPORT unsigned int __export \fBcfg_num\fP (\fBcfg_t\fP *cfg)" .br -.RI "\fIPrint an option and its value to a file. \fP" +.RI "Return number of options in a file or section\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_opt_print\fP (\fBcfg_opt_t\fP *opt, FILE *fp)" +.RI "DLLIMPORT int __export \fBcfg_addlist\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int nvalues,\&.\&.\&.)" .br -.RI "\fIPrint an option and its value to a file. \fP" +.RI "Add values for a list option\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_print_indent\fP (\fBcfg_t\fP *cfg, FILE *fp, int indent)" +.RI "DLLIMPORT int \fBcfg_opt_setmulti\fP (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, unsigned int nvalues, char **values)" .br -.RI "\fIPrint the options and values to a file. \fP" +.RI "Set an option (create an instance of an option)\&. " .ti -1c -.RI "DLLIMPORT void __export \fBcfg_print\fP (\fBcfg_t\fP *cfg, FILE *fp)" +.RI "DLLIMPORT int \fBcfg_setmulti\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int nvalues, char **values)" .br -.RI "\fIPrint the options and values to a file. \fP" +.RI "Set an option (create an instance of an option)\&. " .ti -1c +.RI "DLLIMPORT \fBcfg_t\fP * \fBcfg_addtsec\fP (\fBcfg_t\fP *cfg, const char *name, const char *title)" +.br +.RI "Create a new titled config section\&. " +.ti -1c +.RI "DLLIMPORT int __export \fBcfg_opt_rmnsec\fP (\fBcfg_opt_t\fP *opt, unsigned int index)" +.br +.RI "Removes and frees a config section, given a \fBcfg_opt_t\fP pointer\&. " +.ti -1c +.RI "DLLIMPORT int __export \fBcfg_rmnsec\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)" +.br +.RI "Indexed version of \fBcfg_rmsec()\fP, used for CFGF_MULTI sections\&. " +.ti -1c +.RI "DLLIMPORT int __export \fBcfg_rmsec\fP (\fBcfg_t\fP *cfg, const char *name)" +.br +.RI "Removes and frees a config section\&. " +.ti -1c +.RI "DLLIMPORT int __export \fBcfg_opt_rmtsec\fP (\fBcfg_opt_t\fP *opt, const char *title)" +.br +.RI "Removes and frees a config section, given a \fBcfg_opt_t\fP pointer and the title\&. " +.ti -1c +.RI "DLLIMPORT int __export \fBcfg_rmtsec\fP (\fBcfg_t\fP *cfg, const char *name, const char *title)" +.br +.RI "Removes and frees a section given the title, used for section with the CFGF_TITLE flag set\&. " +.ti -1c +.RI "DLLIMPORT int __export \fBcfg_opt_nprint_var\fP (\fBcfg_opt_t\fP *opt, unsigned int index, FILE *fp)" +.br +.RI "Default value print function\&. " +.ti -1c +.RI "DLLIMPORT int __export \fBcfg_opt_print_indent\fP (\fBcfg_opt_t\fP *opt, FILE *fp, int indent)" +.br +.RI "Print an option and its value to a file\&. " +.ti -1c +.RI "DLLIMPORT int __export \fBcfg_opt_print\fP (\fBcfg_opt_t\fP *opt, FILE *fp)" +.br +.RI "Print an option and its value to a file\&. " +.ti -1c +.RI "DLLIMPORT int __export \fBcfg_print_indent\fP (\fBcfg_t\fP *cfg, FILE *fp, int indent)" +.br +.RI "Print the options and values to a file\&. " +.ti -1c +.RI "DLLIMPORT int __export \fBcfg_print\fP (\fBcfg_t\fP *cfg, FILE *fp)" +.br +.RI "Print the options and values to a file\&. " +.ti -1c .RI "DLLIMPORT \fBcfg_print_func_t\fP __export \fBcfg_opt_set_print_func\fP (\fBcfg_opt_t\fP *opt, \fBcfg_print_func_t\fP pf)" .br -.RI "\fISet a print callback function for an option. \fP" +.RI "Set a print callback function for an option\&. " .ti -1c .RI "DLLIMPORT \fBcfg_print_func_t\fP __export \fBcfg_set_print_func\fP (\fBcfg_t\fP *cfg, const char *name, \fBcfg_print_func_t\fP pf)" .br -.RI "\fISet a print callback function for an option given its name. \fP" +.RI "Set a print callback function for an option given its name\&. " .ti -1c +.RI "DLLIMPORT \fBcfg_print_filter_func_t\fP __export \fBcfg_set_print_filter_func\fP (\fBcfg_t\fP *cfg, \fBcfg_print_filter_func_t\fP pff)" +.br +.RI "Install a user-defined print filter function\&. " +.ti -1c .RI "DLLIMPORT \fBcfg_validate_callback_t\fP __export \fBcfg_set_validate_func\fP (\fBcfg_t\fP *cfg, const char *name, \fBcfg_validate_callback_t\fP vf)" .br -.RI "\fIRegister a validating callback function for an option. \fP" +.RI "Register a validating callback function for an option\&. " +.ti -1c +.RI "DLLIMPORT \fBcfg_validate_callback2_t\fP __export \fBcfg_set_validate_func2\fP (\fBcfg_t\fP *cfg, const char *name, \fBcfg_validate_callback2_t\fP vf)" +.br +.RI "Register a validating callback function for an option\&. " .in -1c .SH "Detailed Description" .PP -A configuration file parser library. +A configuration file parser library\&. -.SH "Define Documentation" +.SH "Macro Definition Documentation" .PP -.SS "#define CFG_END() {0,CFGT_NONE,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},0,0,0,0,0,0}" +.SS "#define CFG_END() {0,0,CFGT_NONE,0,0,\fBCFGF_NONE\fP,0,{0,0,cfg_false,0,0},0,{0},0,0,0,0,0}" + .PP -Terminate list of options. +Terminate list of options\&. This must be the last initializer in the option list\&. .PP -This must be the last initializer in the option list. -.PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP, \fBreread.c\fP, and \fBsimple.c\fP. -.SS "#define CFG_FUNC(name, func) {name,CFGT_FUNC,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},func,0,0,0,0,0}" +\fBftpconf\&.c\fP, \fBreread\&.c\fP, and \fBsimple\&.c\fP\&. +.SS "#define CFG_FUNC(name, func) {name,0,\fBCFGT_FUNC\fP,0,0,\fBCFGF_NONE\fP,0,{0,0,cfg_false,0,0},func,{0},0,0,0,0,0}" + .PP -Initialize a function. +Initialize a function\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIname\fP The name of the option .br -\fIfunc\fP The callback function. +\fIfunc\fP The callback function\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_func_t\fP .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP. +\fBftpconf\&.c\fP\&. .SS "#define CFG_PTR_CB(name, def, flags, parsecb, freecb) __CFG_PTR(name, def, flags, 0, parsecb, freecb)" + .PP -Initialize a user-defined option. +Initialize a user-defined option\&. CFG_PTR options can only be used together with a value parsing callback\&. .PP -CFG_PTR options can only be used together with a value parsing callback. -.PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIname\fP The name of the option .br @@ -501,17 +611,18 @@ CFG_PTR options can only be used together with a value \fIfreecb\fP Memory release function .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_callback_t\fP, \fBcfg_free_func_t\fP .RE .PP -.SS "#define CFG_SEC(name, opts, flags) {name,CFGT_SEC,0,0,flags,opts,{0,0,cfg_false,0,0},0,0,0,0,0,0}" +.SS "#define CFG_SEC(name, opts, flags) {name,0,\fBCFGT_SEC\fP,0,0,flags,opts,{0,0,cfg_false,0,0},0,{0},0,0,0,0,0}" + .PP -Initialize a section. +Initialize a section\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIname\fP The name of the option .br @@ -522,60 +633,64 @@ Initialize a section. .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP, and \fBreread.c\fP. -.SS "#define CFG_SIMPLE_STR(name, svalue) __CFG_STR(name, 0, CFGF_NONE, svalue, 0)" +\fBftpconf\&.c\fP, and \fBreread\&.c\fP\&. +.SS "#define CFG_SIMPLE_INT(name, svalue) __CFG_INT(name, 0, \fBCFGF_NONE\fP, svalue, 0)" + .PP -Initialize a 'simple' string option. +Initialize a 'simple' integer option (see documentation for CFG_SIMPLE_STR for more information)\&. Note that confuse uses long integers, so make sure that any pointer you provide for svalue points to a long int rather than a normal int\&. Otherwise, you will have strange problems on 64-bit architectures\&. .PP -'Simple' options (in lack of a better expression) does not support lists of values or multiple sections. LibConfuse will store the value of a simple option in the user-defined location specified by the value parameter in the initializer. Simple options are not stored in the \fBcfg_t\fP context, only a pointer. Sections can not be initialized as a 'simple' option. +\fBExamples\fP +.in +1c +\fBsimple\&.c\fP\&. +.SS "#define CFG_SIMPLE_STR(name, svalue) __CFG_STR(name, 0, \fBCFGF_NONE\fP, svalue, 0)" + .PP -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. +Initialize a 'simple' string option\&. 'Simple' options (in lack of a better expression) does not support lists of values or multiple sections\&. LibConfuse will store the value of a simple option in the user-defined location specified by the value parameter in the initializer\&. Simple options are not stored in the \fBcfg_t\fP context, only a pointer\&. Sections can not be initialized as a 'simple' option\&. .PP -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. +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\&. .PP -\fBParameters:\fP +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\&. +.PP +\fBParameters\fP .RS 4 \fIname\fP name of the option .br -\fIsvalue\fP pointer to a character pointer (a char **). This value must be initalized either to NULL or to a malloc()'ed string. You can't use +\fIsvalue\fP pointer to a character pointer (a char **)\&. This value must be initalized either to NULL or to a malloc()'ed string\&. You can't use .PP .nf - char *user = 'joe'; - ... - \fBcfg_opt_t\fP opts[] = { - CFG_SIMPLE_STR('user', &user), - ... - +char *user = 'joe'; +\&.\&.\&. +\fBcfg_opt_t\fP opts[] = { + CFG_SIMPLE_STR('user', &user), +\&.\&.\&. .fi .PP - 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: + 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: .PP .nf - char *user = strdup('joe'); - ... - \fBcfg_opt_t\fP opts[] = { - CFG_SIMPLE_STR('user', &user), - ... - +char *user = strdup('joe'); +\&.\&.\&. +\fBcfg_opt_t\fP opts[] = { + CFG_SIMPLE_STR('user', &user), +\&.\&.\&. .fi .PP Alternatively, the default value can be set after the opts struct is defined, as in: .PP .nf - char *user = 0; - ... - \fBcfg_opt_t\fP opts[] = { - CFG_SIMPLE_STR('user', &user), - ... - user = strdup('joe'); - cfg = cfg_init(opts, 0); - cfg_parse(cfg, filename); - +char *user = 0; +\&.\&.\&. +\fBcfg_opt_t\fP opts[] = { + CFG_SIMPLE_STR('user', &user), +\&.\&.\&. +user = strdup('joe'); +cfg = cfg_init(opts, 0); +cfg_parse(cfg, filename); .fi .PP @@ -583,130 +698,163 @@ libConfuse doesn't support handling default values for .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBsimple.c\fP. +\fBsimple\&.c\fP\&. .SS "#define CFG_SUCCESS 0" + .PP -Return codes from \fBcfg_parse()\fP. +Return codes from \fBcfg_parse()\fP, \fBcfg_parse_boolean()\fP, and cfg_set*() functions\&. .PP +\fBExamples\fP +.in +1c +\fBftpconf\&.c\fP, and \fBreread\&.c\fP\&. +.SS "#define CFGF_DEPRECATED (1 << 9)" .PP -\fBExamples: \fP -.in +1c -\fBftpconf.c\fP. -.PP -Referenced by cfg_parse_buf(), and cfg_parse_fp(). -.SS "#define CFGF_NONE 0" -.PP -Flags. -.PP +option is deprecated and should be ignored\&. +.SS "#define CFGF_NONE (0)" .PP -\fBExamples: \fP +Flags\&. +.PP +\fBExamples\fP .in +1c -\fBftpconf.c\fP, and \fBreread.c\fP. +\fBftpconf\&.c\fP, and \fBreread\&.c\fP\&. .SH "Typedef Documentation" .PP -.SS "typedef int(* \fBcfg_callback_t\fP)(\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, const char *value, void *result)" +.SS "typedef int(* cfg_callback_t) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, const char *value, void *result)" + .PP -Value parsing callback prototype. +Value parsing callback prototype\&. This is a callback function (different from the one registered with the CFG_FUNC initializer) used to parse a value\&. This can be used to override the internal parsing of a value\&. .PP -This is a callback function (different from the one registered with the CFG_FUNC initializer) used to parse a value. This can be used to override the internal parsing of a value. +Suppose you want an integer option that only can have certain values, for example 1, 2 and 3, and these should be written in the configuration file as 'yes', 'no' and 'maybe'\&. The callback function would be called with the found value ('yes', 'no' or 'maybe') as a string, and the result should be stored in the result parameter\&. .PP -Suppose you want an integer option that only can have certain values, for example 1, 2 and 3, and these should be written in the configuration file as 'yes', 'no' and 'maybe'. The callback function would be called with the found value ('yes', 'no' or 'maybe') as a string, and the result should be stored in the result parameter. -.PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIopt\fP The option. +\fIopt\fP The option\&. .br -\fIvalue\fP The value found in the configuration file. +\fIvalue\fP The value found in the configuration file\&. .br -\fIresult\fP Pointer to storage for the result, cast to a void pointer. +\fIresult\fP Pointer to storage for the result, cast to a void pointer\&. .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -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 \fBcfg_error()\fP. +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 \fBcfg_error()\fP\&. .RE .PP -.SS "typedef void(* \fBcfg_errfunc_t\fP)(\fBcfg_t\fP *cfg, const char *fmt, va_list ap)" +.SS "typedef void(* cfg_errfunc_t) (\fBcfg_t\fP *cfg, const char *fmt, va_list ap)" + .PP -Error reporting function. +Error reporting function\&. +.SS "typedef void(* cfg_free_func_t) (void *value)" + .PP +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\&. +.SS "typedef int(* cfg_func_t) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, int argc, const char **argv)" -.SS "typedef void(* \fBcfg_free_func_t\fP)(void *value)" .PP -User-defined memory release function for CFG_PTR values. +Function prototype used by CFGT_FUNC options\&. This is a callback function, registered with the CFG_FUNC initializer\&. Each time libConfuse finds a function, the registered callback function is called (parameters are passed as strings, any conversion to other types should be made in the callback function)\&. libConfuse does not support any storage of the data found; these are passed as parameters to the callback, and it's the responsibility of the callback function to do whatever it should do with the data\&. .PP -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. -.SS "typedef int(* \fBcfg_func_t\fP)(\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, int argc, const char **argv)" -.PP -Function prototype used by CFGT_FUNC options. -.PP -This is a callback function, registered with the CFG_FUNC initializer. Each time libConfuse finds a function, the registered callback function is called (parameters are passed as strings, any conversion to other types should be made in the callback function). libConfuse does not support any storage of the data found; these are passed as parameters to the callback, and it's the responsibility of the callback function to do whatever it should do with the data. -.PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIopt\fP The option. +\fIopt\fP The option\&. .br -\fIargc\fP Number of arguments passed. The callback function is responsible for checking that the correct number of arguments are passed. +\fIargc\fP Number of arguments passed\&. The callback function is responsible for checking that the correct number of arguments are passed\&. .br -\fIargv\fP Arguments as an array of character strings. +\fIargv\fP Arguments as an array of character strings\&. .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -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 \fBcfg_error()\fP. +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 \fBcfg_error()\fP\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBCFG_FUNC\fP .RE .PP -.SS "typedef void(* \fBcfg_print_func_t\fP)(\fBcfg_opt_t\fP *opt, unsigned int index, FILE *fp)" +.SS "typedef int(* cfg_print_filter_func_t) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt)" + .PP -Function prototype used by the cfg_print_ functions. +Print filter function\&. .PP -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. +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context that opt belongs to\&. +.br +\fIopt\fP The configuration option that is about to be printed, or not\&. +.RE .PP -Except for functions, the print callback function should only print the value of the option, not the name and the equal sign (that is handled by the cfg_opt_print function). For function options however, the name and the parenthesis must be printed by this function. The value to print can be accessed with the cfg_opt_get functions. +\fBReturns\fP +.RS 4 +Zero if opt should be printed, non-zero if it should be filtered out\&. +.RE .PP -\fBParameters:\fP +\fBSee also\fP .RS 4 +\fBcfg_set_print_filter_func()\fP +.RE +.PP + +.SS "typedef void(* cfg_print_func_t) (\fBcfg_opt_t\fP *opt, unsigned int index, FILE *fp)" + +.PP +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\&. +.PP +Except for functions, the print callback function should only print the value of the option, not the name and the equal sign (that is handled by the cfg_opt_print function)\&. For function options however, the name and the parenthesis must be printed by this function\&. The value to print can be accessed with the cfg_opt_get functions\&. +.PP +\fBParameters\fP +.RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .br -\fIindex\fP Index of the value to get. Zero based. +\fIindex\fP Index of the value to get\&. Zero based\&. .br -\fIfp\fP File stream to print to, use stdout to print to the screen. +\fIfp\fP File stream to print to, use stdout to print to the screen\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_print\fP, \fBcfg_set_print_func\fP .RE .PP -.SS "typedef int(* \fBcfg_validate_callback_t\fP)(\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt)" +.SS "typedef int(* cfg_validate_callback2_t) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, void *value)" + .PP -Validating callback prototype. +Validating callback2 prototype\&. This callback function is called before an option is set using the cfg_set*() APIs\&. The function is called only for strings, integers, and floats\&. Compared to the regular callback function this takes a value pointer argument which must be casted before use, but can also be used to correct a value before it is set, e\&.g\&. when a too large value is set this can be used to set the MAX\&. .PP -This callback function is called after an option has been parsed and set. The function is called for both fundamental values (strings, integers etc) as well as lists and sections. This can for example be used to validate that all required options in a section has been set to sane values. +\fBReturns\fP +.RS 4 +On success, 0 should be returned\&. All other values indicates an error, and the cfg_set*() function will return without setting the value\&. +.RE .PP -\fBReturns:\fP +\fBSee also\fP .RS 4 -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 \fBcfg_error()\fP. +\fBcfg_set_validate_func2()\fP .RE .PP -\fBSee also:\fP + +.SS "typedef int(* cfg_validate_callback_t) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt)" + +.PP +Validating callback prototype\&. This callback function is called after an option has been parsed and set\&. The function is called for both fundamental values (strings, integers etc) as well as lists and sections\&. This can for example be used to validate that all required options in a section has been set to sane values\&. +.PP +\fBReturns\fP .RS 4 +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 \fBcfg_error()\fP\&. +.RE +.PP +\fBSee also\fP +.RS 4 \fBcfg_set_validate_func\fP .RE .PP @@ -714,15 +862,15 @@ On success, 0 should be returned. All other values ind .SH "Enumeration Type Documentation" .PP .SS "enum \fBcfg_bool_t\fP" -.PP -Boolean values. -.PP +.PP +Boolean values\&. .SS "enum \fBcfg_type_t\fP" + .PP -Fundamental option types. +Fundamental option types\&. .PP -\fBEnumerator: \fP +\fBEnumerator\fP .in +1c .TP \fB\fICFGT_INT \fP\fP @@ -745,1073 +893,1564 @@ function .TP \fB\fICFGT_PTR \fP\fP pointer to user-defined value +.TP +\fB\fICFGT_COMMENT \fP\fP +comment/annotation .SH "Function Documentation" .PP -.SS "DLLIMPORT void __export cfg_addlist (\fBcfg_t\fP * cfg, const char * name, unsigned int nvalues, ...)" +.SS "DLLIMPORT int __export cfg_add_searchpath (\fBcfg_t\fP * cfg, const char * dir)" + .PP -Add values for a list option. +Add a searchpath directory to the configuration context, the const char* argument will be duplicated and then freed as part of the usual context takedown\&. All directories added to the context in this manner will be searched for the file specified in \fBcfg_parse()\fP, and for those included\&. All directories added with this function will be 'tilde expanded'\&. Note that the current directory is not added to the searchpath by default\&. .PP -The new values are appended to any current values in the list. +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context as returned from \fBcfg_init()\fP\&. +.br +\fIdir\fP Directory to be added to the search path\&. +.RE .PP -\fBParameters:\fP +\fBReturns\fP .RS 4 -\fIcfg\fP The configuration file context. +On success, CFG_SUCCESS, on failure (which can only be caused by a failed malloc()), CFG_PARSE_ERROR\&. +.RE +.PP + +.SS "DLLIMPORT int __export cfg_addlist (\fBcfg_t\fP * cfg, const char * name, unsigned int nvalues, \&.\&.\&.)" + +.PP +Add values for a list option\&. The new values are appended to any current values in the list\&. +.PP +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fInvalues\fP Number of values to add. +\fInvalues\fP Number of values to add\&. .br -\fI...\fP The values to add, the type must match the type of the option and the number of values must be equal to the nvalues parameter. +\fI\&.\&.\&.\fP The values to add, the type must match the type of the option and the number of values must be equal to the nvalues parameter\&. .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP +.SS "DLLIMPORT \fBcfg_t\fP* cfg_addtsec (\fBcfg_t\fP * cfg, const char * name, const char * title)" + .PP -References CFGF_LIST, and cfg_opt_t::flags. -.SS "DLLIMPORT void __export cfg_error (\fBcfg_t\fP * cfg, const char * fmt, ...)" +Create a new titled config section\&. .PP -Show a parser error. +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context\&. +.br +\fIname\fP The name of the option\&. +.br +\fItitle\fP The title of this section\&. +.RE .PP -Any user-defined error reporting function is called. +\fBReturns\fP +.RS 4 +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\&. +.RE .PP -\fBSee also:\fP + +.SS "DLLIMPORT void __export cfg_error (\fBcfg_t\fP * cfg, const char * fmt, \&.\&.\&.)" + +.PP +Show a parser error\&. Any user-defined error reporting function is called\&. +.PP +\fBSee also\fP .RS 4 \fBcfg_set_error_function\fP .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP. +\fBftpconf\&.c\fP\&. +.SS "DLLIMPORT int __export cfg_free (\fBcfg_t\fP * cfg)" + .PP -References cfg_t::errfunc, cfg_t::filename, and cfg_t::line. -.SS "DLLIMPORT void __export cfg_free (\fBcfg_t\fP * cfg)" +Free a \fBcfg_t\fP context\&. All memory allocated by the \fBcfg_t\fP context structure are freed, and can't be used in any further cfg_* calls\&. .PP -Free a \fBcfg_t\fP context. +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE .PP -All memory allocated by the \fBcfg_t\fP context structure are freed, and can't be used in any further cfg_* calls. + .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP, \fBreread.c\fP, and \fBsimple.c\fP. +\fBftpconf\&.c\fP, \fBreread\&.c\fP, and \fBsimple\&.c\fP\&. +.SS "DLLIMPORT int __export cfg_free_value (\fBcfg_opt_t\fP * opt)" + .PP -References cfg_t::filename, cfg_t::name, cfg_opt_t::name, cfg_t::opts, and cfg_t::title. -.SS "DLLIMPORT void __export cfg_free_value (\fBcfg_opt_t\fP * opt)" +Free the memory allocated for the values of a given option\&. Only the values are freed, not the option itself (it is freed by \fBcfg_free()\fP)\&. .PP -Free the memory allocated for the values of a given option. +\fBSee also\fP +.RS 4 +\fBcfg_free()\fP +.RE .PP -Only the values are freed, not the option itself (it is freed by \fBcfg_free()\fP). -.PP -\fBSee also:\fP +\fBReturns\fP .RS 4 -\fBcfg_free()\fP +POSIX OK(0), or non-zero on failure\&. .RE .PP -.PP -References CFGT_PTR, CFGT_SEC, CFGT_STR, cfg_opt_t::freecb, cfg_opt_t::nvalues, cfg_value_t::ptr, cfg_value_t::section, cfg_value_t::string, cfg_opt_t::type, and cfg_opt_t::values. .SS "DLLIMPORT \fBcfg_bool_t\fP __export cfg_getbool (\fBcfg_t\fP * cfg, const char * name)" + .PP -Returns the value of a boolean option. +Returns the value of a boolean option\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding \fBcfg_opt_t\fP structure is returned. It is an error to try to get an option that isn't declared. +The requested value is returned\&. If the option was not set in the configuration file, the default value given in the corresponding \fBcfg_opt_t\fP structure is returned\&. It is an error to try to get an option that isn't declared\&. .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP. +\fBftpconf\&.c\fP\&. +.SS "DLLIMPORT char* __export cfg_getcomment (\fBcfg_t\fP * cfg, const char * name)" + +.PP +Returns the option comment\&. This function can be used to extract option annotations from a config file\&. Only comments preceding the option are read by \fBcfg_parse()\fP\&. +.PP +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context\&. +.br +\fIname\fP The name of the option\&. +.RE +.PP +\fBSee also\fP +.RS 4 +\fBcfg_setcomment\fP +.RE +.PP +\fBReturns\fP +.RS 4 +The comment for this option, or NULL if unset +.RE +.PP + .SS "DLLIMPORT double __export cfg_getfloat (\fBcfg_t\fP * cfg, const char * name)" + .PP -Returns the value of a floating point option. +Returns the value of a floating point option\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding \fBcfg_opt_t\fP structure is returned. It is an error to try to get an option that isn't declared. +The requested value is returned\&. If the option was not set in the configuration file, the default value given in the corresponding \fBcfg_opt_t\fP structure is returned\&. It is an error to try to get an option that isn't declared\&. .RE .PP .SS "DLLIMPORT long int __export cfg_getint (\fBcfg_t\fP * cfg, const char * name)" + .PP -Returns the value of an integer option. +Returns the value of an integer option\&. This is the same as calling cfg_getnint with index 0\&. .PP -This is the same as calling cfg_getnint with index 0. -.PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding \fBcfg_opt_t\fP structure is returned. It is an error to try to get an option that isn't declared. +The requested value is returned\&. If the option was not set in the configuration file, the default value given in the corresponding \fBcfg_opt_t\fP structure is returned\&. It is an error to try to get an option that isn't declared\&. .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP, and \fBreread.c\fP. +\fBftpconf\&.c\fP, and \fBreread\&.c\fP\&. .SS "DLLIMPORT \fBcfg_bool_t\fP __export cfg_getnbool (\fBcfg_t\fP * cfg, const char * name, unsigned int index)" + .PP -Indexed version of \fBcfg_getbool()\fP, used for lists. +Indexed version of \fBcfg_getbool()\fP, used for lists\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIindex\fP Index of the value to get. Zero based. +\fIindex\fP Index of the value to get\&. Zero based\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_getbool\fP .RE .PP .SS "DLLIMPORT double __export cfg_getnfloat (\fBcfg_t\fP * cfg, const char * name, unsigned int index)" + .PP -Indexed version of \fBcfg_getfloat()\fP, used for lists. +Indexed version of \fBcfg_getfloat()\fP, used for lists\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIindex\fP Index of the value to get. Zero based. +\fIindex\fP Index of the value to get\&. Zero based\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_getfloat\fP .RE .PP .SS "DLLIMPORT long int __export cfg_getnint (\fBcfg_t\fP * cfg, const char * name, unsigned int index)" + .PP -Indexed version of \fBcfg_getint()\fP, used for lists. +Indexed version of \fBcfg_getint()\fP, used for lists\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIindex\fP Index of the value to get. Zero based. +\fIindex\fP Index of the value to get\&. Zero based\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_getint\fP .RE .PP +.SS "DLLIMPORT \fBcfg_opt_t\fP* cfg_getnopt (\fBcfg_t\fP * cfg, unsigned int index)" + +.PP +Return the nth option in a file or section\&. +.PP +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file or section context +.br +\fIindex\fP Option index +.RE +.PP +\fBSee also\fP +.RS 4 +\fBcfg_num\fP +.RE +.PP + .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_getnsec (\fBcfg_t\fP * cfg, const char * name, unsigned int index)" + .PP -Indexed version of \fBcfg_getsec()\fP, used for sections with the CFGF_MULTI flag set. +Indexed version of \fBcfg_getsec()\fP, used for sections with the CFGF_MULTI flag set\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIindex\fP Index of the section to get. Zero based. +\fIindex\fP Index of the section to get\&. Zero based\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_getsec\fP .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP, and \fBreread.c\fP. +\fBftpconf\&.c\fP, and \fBreread\&.c\fP\&. .SS "DLLIMPORT char* __export cfg_getnstr (\fBcfg_t\fP * cfg, const char * name, unsigned int index)" + .PP -Indexed version of \fBcfg_getstr()\fP, used for lists. +Indexed version of \fBcfg_getstr()\fP, used for lists\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIindex\fP Index of the value to get. Zero based. +\fIindex\fP Index of the value to get\&. Zero based\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_getstr\fP .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP. +\fBftpconf\&.c\fP\&. .SS "DLLIMPORT \fBcfg_opt_t\fP* __export cfg_getopt (\fBcfg_t\fP * cfg, const char * name)" + .PP -Return an option given it's name. +Return an option given it's name\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -Returns a pointer to the option. If the option isn't declared, libConfuse will print an error message and return 0. +Returns a pointer to the option\&. If the option isn't declared, libConfuse will print an error message and return 0\&. .RE .PP -.PP -References CFGF_NOCASE, cfg_t::flags, cfg_opt_t::name, cfg_t::name, and cfg_t::opts. .SS "DLLIMPORT void* __export cfg_getptr (\fBcfg_t\fP * cfg, const char * name)" + .PP -Returns the value of a user-defined option (void pointer). +Returns the value of a user-defined option (void pointer)\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding \fBcfg_opt_t\fP structure is returned. It is an error to try to get an option that isn't declared. +The requested value is returned\&. If the option was not set in the configuration file, the default value given in the corresponding \fBcfg_opt_t\fP structure is returned\&. It is an error to try to get an option that isn't declared\&. .RE .PP .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_getsec (\fBcfg_t\fP * cfg, const char * name)" + .PP -Returns the value of a section option. +Returns the value of a section option\&. The returned value is another \fBcfg_t\fP structure that can be used in following calls to cfg_getint, cfg_getstr or other get-functions\&. .PP -The returned value is another \fBcfg_t\fP structure that can be used in following calls to cfg_getint, cfg_getstr or other get-functions. -.PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -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. +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\&. .RE .PP .SS "DLLIMPORT char* __export cfg_getstr (\fBcfg_t\fP * cfg, const char * name)" + .PP -Returns the value of a string option. +Returns the value of a string option\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding \fBcfg_opt_t\fP structure is returned. It is an error to try to get an option that isn't declared. +The requested value is returned\&. If the option was not set in the configuration file, the default value given in the corresponding \fBcfg_opt_t\fP structure is returned\&. It is an error to try to get an option that isn't declared\&. .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP, and \fBreread.c\fP. +\fBftpconf\&.c\fP, and \fBreread\&.c\fP\&. .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_gettsec (\fBcfg_t\fP * cfg, const char * name, const char * title)" + .PP -Return a section given the title, used for section with the CFGF_TITLE flag set. +Return a section given the title, used for section with the CFGF_TITLE flag set\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fItitle\fP The title of this section. The CFGF_TITLE flag must have been set for this option. +\fItitle\fP The title of this section\&. The CFGF_TITLE flag must have been set for this option\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_getsec\fP .RE .PP .SS "DLLIMPORT int __export cfg_include (\fBcfg_t\fP * cfg, \fBcfg_opt_t\fP * opt, int argc, const char ** argv)" + .PP -Predefined include-function. +Predefined include-function\&. This function can be used in the options passed to \fBcfg_init()\fP to specify a function for including other configuration files in the parsing\&. For example: CFG_FUNC('include', &cfg_include) .PP -This function can be used in the options passed to \fBcfg_init()\fP to specify a function for including other configuration files in the parsing. For example: CFG_FUNC('include', &cfg_include) -.PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP. +\fBftpconf\&.c\fP\&. .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_init (\fBcfg_opt_t\fP * opts, cfg_flag_t flags)" + .PP -Create and initialize a \fBcfg_t\fP structure. +Create and initialize a \fBcfg_t\fP structure\&. This should be the first function called when setting up the parsing of a configuration file\&. The options passed in the first parameter is initialized using the CFG_* initializers\&. The last option in the option array must be \fBCFG_END()\fP, unless you like segmentation faults\&. .PP -This should be the first function called when setting up the parsing of a configuration file. The options passed in the first parameter is initialized using the CFG_* initializers. The last option in the option array must be \fBCFG_END()\fP, unless you like segmentation faults. +The options must no longer be defined in the same scope as where the cfg_xxx functions are used (since version 2\&.3)\&. .PP -The options must no longer be defined in the same scope as where the cfg_xxx functions are used (since version 2.3). +CFGF_IGNORE_UNKNOWN can be specified to use the '__unknown' option whenever an unknown option is parsed\&. Be sure to define an '__unknown' option in each scope that unknown parameters are allowed\&. .PP -\fBParameters:\fP +Call setlocale() before calling this function to localize handling of types, LC_CTYPE, and messages, LC_MESSAGES, since version 2\&.9: +.PP +.nf + + setlocale(LC_MESSAGES, ''); + setlocale(LC_CTYPE, ''); +.fi +.PP + +.PP +\fBParameters\fP .RS 4 \fIopts\fP An arrary of options .br -\fIflags\fP One or more flags (bitwise or'ed together). Currently only CFGF_NOCASE is available. Use 0 if no flags are needed. +\fIflags\fP One or more flags (bitwise or'ed together)\&. Currently only CFGF_NOCASE and CFGF_IGNORE_UNKNOWN are available\&. Use 0 if no flags are needed\&. .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -A configuration context structure. This pointer is passed to almost all other functions as the first parameter. +A configuration context structure\&. This pointer is passed to almost all other functions as the first parameter\&. .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP, \fBreread.c\fP, and \fBsimple.c\fP. +\fBftpconf\&.c\fP, \fBreread\&.c\fP, and \fBsimple\&.c\fP\&. +.SS "const DLLIMPORT char* __export cfg_name (\fBcfg_t\fP * cfg)" + .PP -References cfg_t::errfunc, cfg_t::filename, cfg_t::flags, cfg_t::line, cfg_t::name, and cfg_t::opts. -.SS "DLLIMPORT const char* __export cfg_name (\fBcfg_t\fP * cfg)" +Return the name of a section\&. .PP -Return the name of a section. -.PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -Returns the title, or 0 if there is no title. This string should not be modified. +Returns the title, or 0 if there is no title\&. This string should not be modified\&. .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP. +\fBftpconf\&.c\fP\&. +.SS "DLLIMPORT unsigned int __export cfg_num (\fBcfg_t\fP * cfg)" + .PP -References cfg_t::name. +Return number of options in a file or section\&. +.PP +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file or section context +.RE +.PP +When a file has been parsed this function returns the number of options/settings the file, or a sub-section, has\&. +.PP +\fBReturns\fP +.RS 4 +Number of options in a config file or section\&. +.RE +.PP + +.SS "DLLIMPORT char* __export cfg_opt_getcomment (\fBcfg_opt_t\fP * opt)" + +.PP +Returns the option comment\&. +.PP +\fBParameters\fP +.RS 4 +\fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) +.RE +.PP +\fBSee also\fP +.RS 4 +\fBcfg_getcomment\fP +.RE +.PP + .SS "DLLIMPORT \fBcfg_bool_t\fP __export cfg_opt_getnbool (\fBcfg_opt_t\fP * opt, unsigned int index)" + .PP -Returns the value of a boolean option, given a \fBcfg_opt_t\fP pointer. +Returns the value of a boolean option, given a \fBcfg_opt_t\fP pointer\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .br -\fIindex\fP Index of the value to get. Zero based. +\fIindex\fP Index of the value to get\&. Zero based\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_getnbool\fP .RE .PP -.PP -References cfg_value_t::boolean, CFGT_BOOL, cfg_opt_t::simple_value, cfg_opt_t::type, and cfg_opt_t::values. .SS "DLLIMPORT double __export cfg_opt_getnfloat (\fBcfg_opt_t\fP * opt, unsigned int index)" + .PP -Returns the value of a floating point option, given a \fBcfg_opt_t\fP pointer. +Returns the value of a floating point option, given a \fBcfg_opt_t\fP pointer\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .br -\fIindex\fP Index of the value to get. Zero based. +\fIindex\fP Index of the value to get\&. Zero based\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_getnfloat\fP .RE .PP -.PP -References CFGT_FLOAT, cfg_value_t::fpnumber, cfg_opt_t::simple_value, cfg_opt_t::type, and cfg_opt_t::values. .SS "DLLIMPORT signed long __export cfg_opt_getnint (\fBcfg_opt_t\fP * opt, unsigned int index)" + .PP -Returns the value of an integer option, given a \fBcfg_opt_t\fP pointer. +Returns the value of an integer option, given a \fBcfg_opt_t\fP pointer\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .br -\fIindex\fP Index of the value to get. Zero based. +\fIindex\fP Index of the value to get\&. Zero based\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_getnint\fP .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP. -.PP -References CFGT_INT, cfg_value_t::number, cfg_opt_t::simple_value, cfg_opt_t::type, and cfg_opt_t::values. +\fBftpconf\&.c\fP\&. .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_opt_getnsec (\fBcfg_opt_t\fP * opt, unsigned int index)" + .PP -Returns the value of a section option, given a \fBcfg_opt_t\fP pointer. +Returns the value of a section option, given a \fBcfg_opt_t\fP pointer\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .br -\fIindex\fP Index of the value to get. Zero based. +\fIindex\fP Index of the value to get\&. Zero based\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_getnsec\fP .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP. -.PP -References CFGT_SEC, cfg_value_t::section, cfg_opt_t::type, and cfg_opt_t::values. +\fBftpconf\&.c\fP\&. .SS "DLLIMPORT char* __export cfg_opt_getnstr (\fBcfg_opt_t\fP * opt, unsigned int index)" + .PP -Returns the value of a string option, given a \fBcfg_opt_t\fP pointer. +Returns the value of a string option, given a \fBcfg_opt_t\fP pointer\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .br -\fIindex\fP Index of the value to get. Zero based. +\fIindex\fP Index of the value to get\&. Zero based\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_getnstr\fP .RE .PP +.SS "const DLLIMPORT char* cfg_opt_getstr (\fBcfg_opt_t\fP * opt)" + .PP -References CFGT_STR, cfg_opt_t::simple_value, cfg_value_t::string, cfg_opt_t::type, and cfg_opt_t::values. +Return the string value of a key=value pair\&. +.PP +\fBParameters\fP +.RS 4 +\fIopt\fP The option structure (eg, as returned from \fBcfg_getnopt()\fP) +.RE +.PP +\fBSee also\fP +.RS 4 +\fBcfg_opt_name\fP +.RE +.PP +\fBReturns\fP +.RS 4 +The string value for the option, or NULL if it's not a string\&. This string must not be modified! +.RE +.PP + .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_opt_gettsec (\fBcfg_opt_t\fP * opt, const char * title)" + .PP -Returns the value of a section option, given a \fBcfg_opt_t\fP pointer and the title. +Returns the value of a section option, given a \fBcfg_opt_t\fP pointer and the title\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .br -\fItitle\fP The title of this section. The CFGF_TITLE flag must have been set for this option. +\fItitle\fP The title of this section\&. The CFGF_TITLE flag must have been set for this option\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_gettsec\fP .RE .PP +.SS "const DLLIMPORT char* __export cfg_opt_name (\fBcfg_opt_t\fP * opt)" + .PP -References CFGF_NOCASE, CFGF_TITLE, cfg_opt_t::flags, and cfg_t::title. -.SS "DLLIMPORT const char* __export cfg_opt_name (\fBcfg_opt_t\fP * opt)" +Return the name of an option\&. .PP -Return the name of an option. -.PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -Returns the title, or 0 if there is no title. This string should not be modified. +Returns the title, or 0 if there is no title\&. This string should not be modified\&. .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP. +\fBftpconf\&.c\fP\&. +.SS "DLLIMPORT int __export cfg_opt_nprint_var (\fBcfg_opt_t\fP * opt, unsigned int index, FILE * fp)" + .PP -References cfg_opt_t::name. -.SS "DLLIMPORT void __export cfg_opt_nprint_var (\fBcfg_opt_t\fP * opt, unsigned int index, FILE * fp)" +Default value print function\&. Print only the value of a given option\&. Does not handle sections or functions\&. Use cfg_opt_print to print the whole assignment ('option += value'), or cfg_print to print the whole config file\&. .PP -Default value print function. -.PP -Print only the value of a given option. Does not handle sections or functions. Use cfg_opt_print to print the whole assignment ('option = value'), or cfg_print to print the whole config file. -.PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .br \fIindex\fP The index in the option value array that should be printed .br -\fIfp\fP File stream to print to. +\fIfp\fP File stream to print to\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 -\fBcfg_print\fP, \fBcfg_opt_print\fP +\fBcfg_print\fP, \fBcfg_opt_print\fP .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP +.SS "DLLIMPORT int __export cfg_opt_print (\fBcfg_opt_t\fP * opt, FILE * fp)" + .PP -References CFGT_BOOL, CFGT_FLOAT, CFGT_FUNC, CFGT_INT, CFGT_PTR, CFGT_SEC, CFGT_STR, and cfg_opt_t::type. -.SS "DLLIMPORT void __export cfg_opt_print (\fBcfg_opt_t\fP * 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\&. .PP -Print an option and its value to a file. +\fBParameters\fP +.RS 4 +\fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) +.br +\fIfp\fP File stream to print to\&. +.RE .PP -If a print callback function is specified for the option, it is used instead of cfg_opt_nprint_var. +\fBSee also\fP +.RS 4 +\fBcfg_print_func_t\fP +.RE .PP -\fBParameters:\fP +\fBReturns\fP .RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP + +.SS "DLLIMPORT int __export cfg_opt_print_indent (\fBcfg_opt_t\fP * opt, FILE * fp, int indent)" + +.PP +Print an option and its value to a file\&. Same as cfg_opt_print, but with the indentation level specified\&. +.PP +\fBSee also\fP +.RS 4 +\fBcfg_opt_print\fP +.RE +.PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP + +.SS "DLLIMPORT int __export cfg_opt_rmnsec (\fBcfg_opt_t\fP * opt, unsigned int index)" + +.PP +Removes and frees a config section, given a \fBcfg_opt_t\fP pointer\&. +.PP +\fBParameters\fP +.RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .br -\fIfp\fP File stream to print to. +\fIindex\fP Index of the section to remove\&. Zero based\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 -\fBcfg_print_func_t\fP +\fBcfg_rmnsec\fP .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP -.SS "DLLIMPORT void __export cfg_opt_print_indent (\fBcfg_opt_t\fP * opt, FILE * fp, int indent)" +.SS "DLLIMPORT int __export cfg_opt_rmtsec (\fBcfg_opt_t\fP * opt, const char * title)" + .PP -Print an option and its value to a file. +Removes and frees a config section, given a \fBcfg_opt_t\fP pointer and the title\&. .PP -Same as cfg_opt_print, but with the indentation level specified. +\fBParameters\fP +.RS 4 +\fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) +.br +\fItitle\fP The title of this section\&. The CFGF_TITLE flag must have been set for this option\&. +.RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 -\fBcfg_opt_print\fP +\fBcfg_rmtsec\fP .RE .PP - +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE .PP -References CFGF_LIST, CFGF_TITLE, CFGT_FUNC, CFGT_SEC, CFGT_STR, cfg_opt_t::flags, cfg_opt_t::name, cfg_opt_t::nvalues, cfg_opt_t::pf, cfg_opt_t::simple_value, cfg_value_t::string, cfg_opt_t::type, and cfg_opt_t::values. + .SS "DLLIMPORT \fBcfg_print_func_t\fP __export cfg_opt_set_print_func (\fBcfg_opt_t\fP * opt, \fBcfg_print_func_t\fP pf)" + .PP -Set a print callback function for an option. +Set a print callback function for an option\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .br -\fIpf\fP The print function callback. +\fIpf\fP The print function callback\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_print_func_t\fP .RE .PP +.SS "DLLIMPORT int __export cfg_opt_setcomment (\fBcfg_opt_t\fP * opt, char * comment)" + .PP -References cfg_opt_t::pf. -.SS "DLLIMPORT void __export cfg_opt_setnbool (\fBcfg_opt_t\fP * opt, \fBcfg_bool_t\fP value, unsigned int index)" +Annotate an option\&. .PP -Set a value of a boolean option. -.PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .br -\fIvalue\fP The value to set. -.br -\fIindex\fP The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set. +\fIcomment\fP The annotation .RE .PP +\fBSee also\fP +.RS 4 +\fBcfg_setcomment\fP +.RE +.PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP +.SS "DLLIMPORT int cfg_opt_setmulti (\fBcfg_t\fP * cfg, \fBcfg_opt_t\fP * opt, unsigned int nvalues, char ** values)" + .PP -References cfg_value_t::boolean, CFGT_BOOL, and cfg_opt_t::type. -.SS "DLLIMPORT void __export cfg_opt_setnfloat (\fBcfg_opt_t\fP * opt, double value, unsigned int index)" +Set an option (create an instance of an option)\&. .PP -Set a value of a floating point option. +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context\&. +.br +\fIopt\fP The option definition\&. +.br +\fInvalues\fP The number of values to set for the option\&. +.br +\fIvalues\fP The value(s) for the option\&. +.RE .PP -\fBParameters:\fP +\fBReturns\fP .RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP + +.SS "DLLIMPORT int __export cfg_opt_setnbool (\fBcfg_opt_t\fP * opt, \fBcfg_bool_t\fP value, unsigned int index)" + +.PP +Set a value of a boolean option\&. +.PP +\fBParameters\fP +.RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .br -\fIvalue\fP The value to set. +\fIvalue\fP The value to set\&. .br -\fIindex\fP The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set. +\fIindex\fP The index in the option value array that should be modified\&. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set\&. .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP +.SS "DLLIMPORT int __export cfg_opt_setnfloat (\fBcfg_opt_t\fP * opt, double value, unsigned int index)" + .PP -References CFGT_FLOAT, cfg_value_t::fpnumber, and cfg_opt_t::type. -.SS "DLLIMPORT void __export cfg_opt_setnint (\fBcfg_opt_t\fP * opt, long int value, unsigned int index)" +Set a value of a floating point option\&. .PP -Set a value of an integer option. -.PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .br -\fIvalue\fP The value to set. +\fIvalue\fP The value to set\&. .br -\fIindex\fP The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set. +\fIindex\fP The index in the option value array that should be modified\&. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set\&. .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP +.SS "DLLIMPORT int __export cfg_opt_setnint (\fBcfg_opt_t\fP * opt, long int value, unsigned int index)" + .PP -References CFGT_INT, cfg_value_t::number, and cfg_opt_t::type. -.SS "DLLIMPORT void __export cfg_opt_setnstr (\fBcfg_opt_t\fP * opt, const char * value, unsigned int index)" +Set a value of an integer option\&. .PP -Set a value of a string option. -.PP -\fBParameters:\fP +\fBParameters\fP .RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .br -\fIvalue\fP The value to set. Memory for the string is allocated and the value is copied. Any previous string value is freed. +\fIvalue\fP The value to set\&. .br -\fIindex\fP The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set. +\fIindex\fP The index in the option value array that should be modified\&. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set\&. .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP +.SS "DLLIMPORT int __export cfg_opt_setnstr (\fBcfg_opt_t\fP * opt, const char * value, unsigned int index)" + .PP -References CFGT_STR, cfg_value_t::string, and cfg_opt_t::type. -.SS "DLLIMPORT unsigned int __export cfg_opt_size (\fBcfg_opt_t\fP * opt)" +Set a value of a string option\&. .PP -Return the number of values this option has. +\fBParameters\fP +.RS 4 +\fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) +.br +\fIvalue\fP The value to set\&. Memory for the string is allocated and the value is copied\&. Any previous string value is freed\&. +.br +\fIindex\fP The index in the option value array that should be modified\&. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set\&. +.RE .PP -If no default value is given for the option and no value was found in the config file, 0 will be returned (ie, the option value is not set at all). +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE .PP -\fBParameters:\fP + +.SS "DLLIMPORT unsigned int __export cfg_opt_size (\fBcfg_opt_t\fP * opt)" + +.PP +Return the number of values this option has\&. If no default value is given for the option and no value was found in the config file, 0 will be returned (ie, the option value is not set at all)\&. +.PP +\fBParameters\fP .RS 4 \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP) .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP. -.PP -References cfg_opt_t::nvalues. +\fBftpconf\&.c\fP\&. .SS "DLLIMPORT int __export cfg_parse (\fBcfg_t\fP * cfg, const char * filename)" + .PP -Parse a configuration file. +Parse a configuration file\&. Tilde expansion is performed on the filename before it is opened\&. After a configuration file has been initialized (with \fBcfg_init()\fP) and parsed (with \fBcfg_parse()\fP), the values can be read with the cfg_getXXX functions\&. .PP -Tilde expansion is performed on the filename before it is opened. After a configuration file has been initialized (with \fBcfg_init()\fP) and parsed (with \fBcfg_parse()\fP), the values can be read with the cfg_getXXX functions. -.PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context as returned from \fBcfg_init()\fP. +\fIcfg\fP The configuration file context as returned from \fBcfg_init()\fP\&. .br -\fIfilename\fP The name of the file to parse. +\fIfilename\fP The name of the file to parse\&. .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -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 \fBcfg_error()\fP was called with a descriptive error message. +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 \fBcfg_error()\fP was called with a descriptive error message\&. .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP, \fBreread.c\fP, and \fBsimple.c\fP. -.PP -References cfg_t::filename. +\fBftpconf\&.c\fP, \fBreread\&.c\fP, and \fBsimple\&.c\fP\&. .SS "DLLIMPORT int __export cfg_parse_boolean (const char * s)" + .PP -Parse a boolean option string. +Parse a boolean option string\&. Accepted 'true' values are 'true', 'on' and 'yes', and accepted 'false' values are 'false', 'off' and 'no'\&. .PP -Accepted 'true' values are 'true', 'on' and 'yes', and accepted 'false' values are 'false', 'off' and 'no'. -.PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -Returns 1 or 0 (true/false) if the string was parsed correctly, or -1 if an error occurred. +Returns 1 or 0 (true/false) if the string was parsed correctly, or -1 if an error occurred\&. .RE .PP .SS "DLLIMPORT int __export cfg_parse_buf (\fBcfg_t\fP * cfg, const char * buf)" + .PP -Same as \fBcfg_parse()\fP above, but takes a character buffer as argument. +Same as \fBcfg_parse()\fP above, but takes a character buffer as argument\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context as returned from \fBcfg_init()\fP. +\fIcfg\fP The configuration file context as returned from \fBcfg_init()\fP\&. .br -\fIbuf\fP A zero-terminated string with configuration directives. +\fIbuf\fP A zero-terminated string with configuration directives\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 -\fBcfg_parse()\fP +\fBcfg_parse()\fP .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBreread.c\fP. -.PP -References CFG_SUCCESS, cfg_t::filename, and cfg_t::line. +\fBreread\&.c\fP\&. .SS "DLLIMPORT int __export cfg_parse_fp (\fBcfg_t\fP * cfg, FILE * fp)" + .PP -Same as \fBcfg_parse()\fP above, but takes an already opened file as argument. +Same as \fBcfg_parse()\fP above, but takes an already opened file as argument\&. Reading begins at the current position\&. After parsing, the position is not reset\&. The caller is responsible for closing the file\&. .PP -Reading begins at the current position. After parsing, the position is not reset. The caller is responsible for closing the file. +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context as returned from \fBcfg_init()\fP\&. +.br +\fIfp\fP An open file stream\&. +.RE .PP -\fBParameters:\fP +\fBSee also\fP .RS 4 -\fIcfg\fP The configuration file context as returned from \fBcfg_init()\fP. +\fBcfg_parse()\fP +.RE +.PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP + +.SS "DLLIMPORT int __export cfg_print (\fBcfg_t\fP * cfg, FILE * fp)" + +.PP +Print the options and values to a file\&. Note that options in any included file are expanded and printed directly to the file\&. Option values given with environment variables in the parsed input are also printed expanded\&. This means that if you parse a configuration file you can't expect that the output from this function is identical to the initial file\&. +.PP +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context\&. .br -\fIfp\fP An open file stream. +\fIfp\fP File stream to print to, use stdout to print to the screen\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 -\fBcfg_parse()\fP +\fBcfg_print_func_t\fP, \fBcfg_set_print_func\fP .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP .PP -References CFG_SUCCESS, cfg_t::filename, and cfg_t::line. -.SS "DLLIMPORT void __export cfg_print (\fBcfg_t\fP * cfg, FILE * fp)" +\fBExamples\fP +.in +1c +\fBsimple\&.c\fP\&. +.SS "DLLIMPORT int __export cfg_print_indent (\fBcfg_t\fP * cfg, FILE * fp, int indent)" + .PP -Print the options and values to a file. +Print the options and values to a file\&. Same as cfg_print, but with the indentation level specified\&. .PP -Note that options in any included file are expanded and printed directly to the file. Option values given with environment variables in the parsed input are also printed expanded. This means that if you parse a configuration file you can't expect that the output from this function is identical to the initial file. +\fBSee also\fP +.RS 4 +\fBcfg_print\fP +.RE .PP -\fBParameters:\fP +\fBReturns\fP .RS 4 -\fIcfg\fP The configuration file context. +POSIX OK(0), or non-zero on failure\&. +.RE +.PP + +.SS "DLLIMPORT int __export cfg_rmnsec (\fBcfg_t\fP * cfg, const char * name, unsigned int index)" + +.PP +Indexed version of \fBcfg_rmsec()\fP, used for CFGF_MULTI sections\&. +.PP +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context\&. .br -\fIfp\fP File stream to print to, use stdout to print to the screen. +\fIname\fP The name of the section\&. +.br +\fIindex\fP Index of the section to remove\&. Zero based\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 -\fBcfg_print_func_t\fP, \fBcfg_set_print_func\fP +\fBcfg_rmsec\fP .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP +.SS "DLLIMPORT int __export cfg_rmsec (\fBcfg_t\fP * cfg, const char * name)" + .PP -\fBExamples: \fP -.in +1c -\fBsimple.c\fP. -.SS "DLLIMPORT void __export cfg_print_indent (\fBcfg_t\fP * cfg, FILE * fp, int indent)" +Removes and frees a config section\&. This is the same as calling cfg_rmnsec with index 0\&. .PP -Print the options and values to a file. +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context\&. +.br +\fIname\fP The name of the section\&. +.RE .PP -Same as cfg_print, but with the indentation level specified. +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE .PP -\fBSee also:\fP + +.SS "DLLIMPORT int __export cfg_rmtsec (\fBcfg_t\fP * cfg, const char * name, const char * title)" + +.PP +Removes and frees a section given the title, used for section with the CFGF_TITLE flag set\&. +.PP +\fBParameters\fP .RS 4 -\fBcfg_print\fP +\fIcfg\fP The configuration file context\&. +.br +\fIname\fP The name of the section\&. +.br +\fItitle\fP The title of this section\&. The CFGF_TITLE flag must have been set for this option\&. .RE .PP +\fBSee also\fP +.RS 4 +\fBcfg_rmsec\fP +.RE +.PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP +.SS "DLLIMPORT char* __export cfg_searchpath (cfg_searchpath_t * path, const char * file)" + .PP -References cfg_opt_t::name, and cfg_t::opts. +Search the linked-list of cfg_searchpath_t for the specified file\&. If not NULL, the return value is freshly allocated and and should be freed by the caller\&. +.PP +\fBParameters\fP +.RS 4 +\fIpath\fP The linked list of cfg_searchpath_t structs, each containg a directory to be searched +.br +\fIfile\fP The file for which to search +.RE +.PP +\fBReturns\fP +.RS 4 +If the file is found on the searchpath then the full path to the file is returned\&. If not found, NULL is returned\&. +.RE +.PP + .SS "DLLIMPORT \fBcfg_errfunc_t\fP __export cfg_set_error_function (\fBcfg_t\fP * cfg, \fBcfg_errfunc_t\fP errfunc)" + .PP -Install a user-defined error reporting function. +Install a user-defined error reporting function\&. .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -The old error reporting function is returned. +The old error reporting function is returned\&. .RE .PP +.SS "DLLIMPORT \fBcfg_print_filter_func_t\fP __export cfg_set_print_filter_func (\fBcfg_t\fP * cfg, \fBcfg_print_filter_func_t\fP pff)" + .PP -References cfg_t::errfunc. +Install a user-defined print filter function\&. This callback is called for each option when printing cfg, or something above cfg if cfg is a section in some parent cfg\&. When cfg (or something above cfg) is printed, this filter is also inherited to child sections unless the child section has its own print filter\&. +.PP +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context\&. +.br +\fIpff\fP The print filter callback function\&. +.RE +.PP +\fBReturns\fP +.RS 4 +The old print filter function is returned\&. +.RE +.PP +\fBSee also\fP +.RS 4 +\fBcfg_print_filter_func_t\fP +.RE +.PP + .SS "DLLIMPORT \fBcfg_print_func_t\fP __export cfg_set_print_func (\fBcfg_t\fP * cfg, const char * name, \fBcfg_print_func_t\fP pf)" + .PP -Set a print callback function for an option given its name. +Set a print callback function for an option given its name\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIpf\fP The print callback function. +\fIpf\fP The print callback function\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_print_func_t\fP .RE .PP .SS "DLLIMPORT \fBcfg_validate_callback_t\fP __export cfg_set_validate_func (\fBcfg_t\fP * cfg, const char * name, \fBcfg_validate_callback_t\fP vf)" + .PP -Register a validating callback function for an option. +Register a validating callback function for an option\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIvf\fP The validating callback function. +\fIvf\fP The validating callback function\&. .RE .PP -\fBSee also:\fP +\fBSee also\fP .RS 4 \fBcfg_validate_callback_t\fP .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP. +\fBftpconf\&.c\fP\&. +.SS "DLLIMPORT \fBcfg_validate_callback2_t\fP __export cfg_set_validate_func2 (\fBcfg_t\fP * cfg, const char * name, \fBcfg_validate_callback2_t\fP vf)" + .PP -References cfg_t::flags, cfg_t::opts, and cfg_opt_t::validcb. -.SS "DLLIMPORT void __export cfg_setbool (\fBcfg_t\fP * cfg, const char * name, \fBcfg_bool_t\fP value)" +Register a validating callback function for an option\&. This callback is called for all cfg_set*() functions, although not cfg_opt_set*(), and can be used to check and modify a value/string *before* it is actually set\&. The regular callbacks are run after the fact and are only called when parsing a buffer or file\&. .PP -Set the value of a boolean option given its name. +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context\&. +.br +\fIname\fP The name of the option\&. +.br +\fIvf\fP The validating callback function\&. +.RE .PP -\fBParameters:\fP +\fBSee also\fP .RS 4 -\fIcfg\fP The configuration file context. +\fBcfg_validate_callback2_t\fP +.RE +.PP + +.SS "DLLIMPORT int __export cfg_setbool (\fBcfg_t\fP * cfg, const char * name, \fBcfg_bool_t\fP value)" + +.PP +Set the value of a boolean option given its name\&. +.PP +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIvalue\fP The value to set. If the option is a list (the CFGF_LIST flag is set), only the first value (with index 0) is set. +\fIvalue\fP The value to set\&. If the option is a list (the CFGF_LIST flag is set), only the first value (with index 0) is set\&. .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP -.SS "DLLIMPORT void __export cfg_setfloat (\fBcfg_t\fP * cfg, const char * name, double value)" +.SS "DLLIMPORT int __export cfg_setcomment (\fBcfg_t\fP * cfg, const char * name, char * comment)" + .PP -Set the value of a floating point option given its name. +Annotate an option given its name\&. All options can be annotated as long as the CFGF_COMMENTS flag is given to \fBcfg_init()\fP\&. .PP -\fBParameters:\fP +When calling \fBcfg_print()\fP, annotations are saved as a C style one-liner comment before each option\&. +.PP +When calling \fBcfg_parse()\fP, only one-liner comments preceding an option are read and used to annotate the option\&. +.PP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIvalue\fP The value to set. If the option is a list (the CFGF_LIST flag is set), only the first value (with index 0) is set. +\fIcomment\fP The annotation .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. This function will fail if memory for the new comment cannot be allocated\&. +.RE +.PP -.SS "DLLIMPORT void __export cfg_setint (\fBcfg_t\fP * cfg, const char * name, long int value)" +.SS "DLLIMPORT int __export cfg_setfloat (\fBcfg_t\fP * cfg, const char * name, double value)" + .PP -Set the value of an integer option given its name. +Set the value of a floating point option given its name\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIvalue\fP The value to set. If the option is a list (the CFGF_LIST flag is set), only the first value (with index 0) is set. +\fIvalue\fP The value to set\&. If the option is a list (the CFGF_LIST flag is set), only the first value (with index 0) is set\&. .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP -.SS "DLLIMPORT void __export cfg_setlist (\fBcfg_t\fP * cfg, const char * name, unsigned int nvalues, ...)" +.SS "DLLIMPORT int __export cfg_setint (\fBcfg_t\fP * cfg, const char * name, long int value)" + .PP -Set values for a list option. +Set the value of an integer option given its name\&. .PP -All existing values are replaced with the new ones. +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context\&. +.br +\fIname\fP The name of the option\&. +.br +\fIvalue\fP The value to set\&. If the option is a list (the CFGF_LIST flag is set), only the first value (with index 0) is set\&. +.RE .PP -\fBParameters:\fP +\fBReturns\fP .RS 4 -\fIcfg\fP The configuration file context. +POSIX OK(0), or non-zero on failure\&. +.RE +.PP + +.SS "DLLIMPORT int __export cfg_setlist (\fBcfg_t\fP * cfg, const char * name, unsigned int nvalues, \&.\&.\&.)" + +.PP +Set values for a list option\&. All existing values are replaced with the new ones\&. +.PP +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fInvalues\fP Number of values to set. +\fInvalues\fP Number of values to set\&. .br -\fI...\fP The values to set, the type must match the type of the option and the number of values must be equal to the nvalues parameter. +\fI\&.\&.\&.\fP The values to set, the type must match the type of the option and the number of values must be equal to the nvalues parameter\&. .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP +.SS "DLLIMPORT int cfg_setmulti (\fBcfg_t\fP * cfg, const char * name, unsigned int nvalues, char ** values)" + .PP -References CFGF_LIST, and cfg_opt_t::flags. -.SS "DLLIMPORT void __export cfg_setnbool (\fBcfg_t\fP * cfg, const char * name, \fBcfg_bool_t\fP value, unsigned int index)" +Set an option (create an instance of an option)\&. .PP -Set a value of a boolean option given its name and index. -.PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIvalue\fP The value to set. +\fInvalues\fP The number of values to set for the option\&. .br -\fIindex\fP The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set. +\fIvalues\fP The value(s) for the option\&. .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP -.SS "DLLIMPORT void __export cfg_setnfloat (\fBcfg_t\fP * cfg, const char * name, double value, unsigned int index)" +.SS "DLLIMPORT int __export cfg_setnbool (\fBcfg_t\fP * cfg, const char * name, \fBcfg_bool_t\fP value, unsigned int index)" + .PP -Set a value of a floating point option given its name and index. +Set a value of a boolean option given its name and index\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIvalue\fP The value to set. +\fIvalue\fP The value to set\&. .br -\fIindex\fP The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set. +\fIindex\fP The index in the option value array that should be modified\&. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set\&. .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP -.SS "DLLIMPORT void __export cfg_setnint (\fBcfg_t\fP * cfg, const char * name, long int value, unsigned int index)" +.SS "DLLIMPORT int __export cfg_setnfloat (\fBcfg_t\fP * cfg, const char * name, double value, unsigned int index)" + .PP -Set a value of an integer option given its name and index. +Set a value of a floating point option given its name and index\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIvalue\fP The value to set. +\fIvalue\fP The value to set\&. .br -\fIindex\fP The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set. +\fIindex\fP The index in the option value array that should be modified\&. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set\&. .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP -.SS "DLLIMPORT void __export cfg_setnstr (\fBcfg_t\fP * cfg, const char * name, const char * value, unsigned int index)" +.SS "DLLIMPORT int __export cfg_setnint (\fBcfg_t\fP * cfg, const char * name, long int value, unsigned int index)" + .PP -Set a value of a boolean option given its name and index. +Set a value of an integer option given its name and index\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIvalue\fP The value to set. Memory for the string is allocated and the value is copied. Any privious string value is freed. +\fIvalue\fP The value to set\&. .br -\fIindex\fP The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set. +\fIindex\fP The index in the option value array that should be modified\&. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set\&. .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP -.SS "DLLIMPORT \fBcfg_value_t\fP* cfg_setopt (\fBcfg_t\fP * cfg, \fBcfg_opt_t\fP * opt, char * value)" +.SS "DLLIMPORT int __export cfg_setnstr (\fBcfg_t\fP * cfg, const char * name, const char * value, unsigned int index)" + .PP -Set an option (create an instance of an option). +Set a value of a boolean option given its name and index\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIopt\fP The option definition. +\fIname\fP The name of the option\&. .br -\fIvalue\fP The initial value for the option. +\fIvalue\fP The value to set\&. Memory for the string is allocated and the value is copied\&. Any privious string value is freed\&. +.br +\fIindex\fP The index in the option value array that should be modified\&. It is an error to set values with indices larger than 0 for options without the CFGF_LIST flag set\&. .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -Returns a pointer to the value object. +POSIX OK(0), or non-zero on failure\&. .RE .PP +.SS "DLLIMPORT \fBcfg_value_t\fP* cfg_setopt (\fBcfg_t\fP * cfg, \fBcfg_opt_t\fP * opt, const char * value)" + .PP -References cfg_value_t::boolean, CFGF_LIST, CFGF_MULTI, CFGF_NO_TITLE_DUPES, CFGF_NOCASE, CFGF_TITLE, CFGT_BOOL, CFGT_FLOAT, CFGT_INT, CFGT_PTR, CFGT_SEC, CFGT_STR, cfg_t::errfunc, cfg_t::filename, cfg_t::flags, cfg_opt_t::flags, cfg_value_t::fpnumber, cfg_t::line, cfg_t::name, cfg_opt_t::name, cfg_value_t::number, cfg_opt_t::nvalues, cfg_t::opts, cfg_opt_t::parsecb, cfg_value_t::ptr, cfg_value_t::section, cfg_opt_t::simple_value, cfg_value_t::string, cfg_opt_t::subopts, cfg_t::title, cfg_opt_t::type, and cfg_opt_t::values. -.SS "DLLIMPORT void __export cfg_setstr (\fBcfg_t\fP * cfg, const char * name, const char * value)" +Set an option (create an instance of an option)\&. .PP -Set the value of a string option given its name. +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context\&. +.br +\fIopt\fP The option definition\&. +.br +\fIvalue\fP The initial value for the option\&. +.RE .PP -\fBParameters:\fP +\fBReturns\fP .RS 4 -\fIcfg\fP The configuration file context. +Returns a pointer to the value object\&. +.RE +.PP + +.SS "DLLIMPORT int __export cfg_setstr (\fBcfg_t\fP * cfg, const char * name, const char * value)" + +.PP +Set the value of a string option given its name\&. +.PP +\fBParameters\fP +.RS 4 +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .br -\fIvalue\fP The value to set. Memory for the string is allocated and the value is copied. Any previous string value is freed. If the option is a list (the CFGF_LIST flag is set), only the first value (with index 0) is set. +\fIvalue\fP The value to set\&. Memory for the string is allocated and the value is copied\&. Any previous string value is freed\&. If the option is a list (the CFGF_LIST flag is set), only the first value (with index 0) is set\&. .RE .PP +\fBReturns\fP +.RS 4 +POSIX OK(0), or non-zero on failure\&. +.RE +.PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBsimple.c\fP. +\fBsimple\&.c\fP\&. .SS "DLLIMPORT unsigned int __export cfg_size (\fBcfg_t\fP * cfg, const char * name)" + .PP -Return the number of values this option has. +Return the number of values this option has\&. If no default value is given for the option and no value was found in the config file, 0 will be returned (ie, the option value is not set at all)\&. .PP -If no default value is given for the option and no value was found in the config file, 0 will be returned (ie, the option value is not set at all). +Note that there is no way to *not* specify a default value for integers, floats and booleans\&. Ie, they always have default values (since 0 or NULL is a valid integer/float/boolean value)\&. Only strings and lists may have no default value\&. .PP -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. -.PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .br -\fIname\fP The name of the option. +\fIname\fP The name of the option\&. .RE .PP .PP -\fBExamples: \fP +\fBExamples\fP .in +1c -\fBftpconf.c\fP, and \fBreread.c\fP. +\fBftpconf\&.c\fP, and \fBreread\&.c\fP\&. .SS "DLLIMPORT char* __export cfg_tilde_expand (const char * filename)" + .PP -Does tilde expansion (~ -> $HOME) on the filename. +Does tilde expansion (~ -> $HOME) on the filename\&. .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -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. +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\&. .RE .PP -.SS "DLLIMPORT const char* __export cfg_title (\fBcfg_t\fP * cfg)" +.SS "const DLLIMPORT char* __export cfg_title (\fBcfg_t\fP * cfg)" + .PP -Return the title of a section. +Return the title of a section\&. .PP -\fBParameters:\fP +\fBParameters\fP .RS 4 -\fIcfg\fP The configuration file context. +\fIcfg\fP The configuration file context\&. .RE .PP -\fBReturns:\fP +\fBReturns\fP .RS 4 -Returns the title, or 0 if there is no title. This string should not be modified. +Returns the title, or 0 if there is no title\&. This string should not be modified\&. .RE .PP -.PP -References cfg_t::title. .SH "Author" .PP -Generated automatically by Doxygen for confuse from the source code. +Generated automatically by Doxygen for confuse from the source code\&.