Annotation of embedaddon/confuse/doc/man/man3/confuse.h.3, revision 1.1.1.2
1.1.1.2 ! misho 1: .TH "confuse.h" 3 "Thu Jun 25 2020" "Version 3.3" "confuse" \" -*- nroff -*-
1.1 misho 2: .ad l
3: .nh
4: .SH NAME
1.1.1.2 ! misho 5: confuse.h \- A configuration file parser library\&.
1.1 misho 6:
7: .SH SYNOPSIS
8: .br
9: .PP
1.1.1.2 ! misho 10: \fC#include <stdio\&.h>\fP
1.1 misho 11: .br
1.1.1.2 ! misho 12: \fC#include <stdarg\&.h>\fP
1.1 misho 13: .br
14:
15: .SS "Data Structures"
16:
17: .in +1c
18: .ti -1c
19: .RI "struct \fBcfg_t\fP"
20: .br
1.1.1.2 ! misho 21: .RI "Data structure holding information about a 'section'\&. "
1.1 misho 22: .ti -1c
23: .RI "union \fBcfg_value_t\fP"
24: .br
1.1.1.2 ! misho 25: .RI "Data structure holding the value of a fundamental option value\&. "
! 26: .ti -1c
! 27: .RI "union \fBcfg_simple_t\fP"
! 28: .br
! 29: .RI "Data structure holding the pointer to a user provided variable defined with CFG_SIMPLE_*\&. "
1.1 misho 30: .ti -1c
31: .RI "struct \fBcfg_defvalue_t\fP"
32: .br
1.1.1.2 ! misho 33: .RI "Data structure holding the default value given by the initialization macros\&. "
1.1 misho 34: .ti -1c
35: .RI "struct \fBcfg_opt_t\fP"
36: .br
1.1.1.2 ! misho 37: .RI "Data structure holding information about an option\&. "
1.1 misho 38: .in -1c
1.1.1.2 ! misho 39: .SS "Macros"
1.1 misho 40:
41: .in +1c
42: .ti -1c
1.1.1.2 ! misho 43: .RI "#define \fBCFGF_NONE\fP (0)"
! 44: .br
! 45: .RI "Flags\&. "
! 46: .ti -1c
! 47: .RI "#define \fBCFGF_MULTI\fP (1 << 0)"
! 48: .br
! 49: .RI "option may be specified multiple times (only applies to sections) "
! 50: .ti -1c
! 51: .RI "#define \fBCFGF_LIST\fP (1 << 1)"
! 52: .br
! 53: .RI "option is a list "
! 54: .ti -1c
! 55: .RI "#define \fBCFGF_NOCASE\fP (1 << 2)"
! 56: .br
! 57: .RI "configuration file is case insensitive "
! 58: .ti -1c
! 59: .RI "#define \fBCFGF_TITLE\fP (1 << 3)"
! 60: .br
! 61: .RI "option has a title (only applies to sections) "
! 62: .ti -1c
! 63: .RI "#define \fBCFGF_NODEFAULT\fP (1 << 4)"
! 64: .br
! 65: .RI "option has no default value "
! 66: .ti -1c
! 67: .RI "#define \fBCFGF_NO_TITLE_DUPES\fP (1 << 5)"
1.1 misho 68: .br
1.1.1.2 ! misho 69: .RI "multiple section titles must be unique (duplicates raises an error, only applies to sections) "
1.1 misho 70: .ti -1c
1.1.1.2 ! misho 71: .RI "#define \fBCFGF_IGNORE_UNKNOWN\fP (1 << 8)"
1.1 misho 72: .br
1.1.1.2 ! misho 73: .RI "ignore unknown options in configuration files "
1.1 misho 74: .ti -1c
1.1.1.2 ! misho 75: .RI "#define \fBCFGF_DEPRECATED\fP (1 << 9)"
1.1 misho 76: .br
1.1.1.2 ! misho 77: .RI "option is deprecated and should be ignored\&. "
1.1 misho 78: .ti -1c
1.1.1.2 ! misho 79: .RI "#define \fBCFGF_DROP\fP (1 << 10)"
1.1 misho 80: .br
1.1.1.2 ! misho 81: .RI "option should be dropped after parsing "
1.1 misho 82: .ti -1c
1.1.1.2 ! misho 83: .RI "#define \fBCFGF_COMMENTS\fP (1 << 11)"
1.1 misho 84: .br
1.1.1.2 ! misho 85: .RI "Enable option annotation/comments support\&. "
1.1 misho 86: .ti -1c
1.1.1.2 ! misho 87: .RI "#define \fBCFGF_MODIFIED\fP (1 << 12)"
1.1 misho 88: .br
1.1.1.2 ! misho 89: .RI "option has been changed from its default value "
1.1 misho 90: .ti -1c
1.1.1.2 ! misho 91: .RI "#define \fBCFGF_KEYSTRVAL\fP (1 << 13)"
1.1 misho 92: .br
1.1.1.2 ! misho 93: .RI "section has free-form key=value string options created when parsing file "
1.1 misho 94: .ti -1c
95: .RI "#define \fBCFG_SUCCESS\fP 0"
96: .br
1.1.1.2 ! misho 97: .RI "Return codes from \fBcfg_parse()\fP, \fBcfg_parse_boolean()\fP, and cfg_set*() functions\&. "
1.1 misho 98: .ti -1c
1.1.1.2 ! misho 99: .RI "#define \fBCFG_STR\fP(name, def, flags) __CFG_STR(name, def, flags, 0, 0)"
1.1 misho 100: .br
1.1.1.2 ! misho 101: .RI "Initialize a string option\&. "
1.1 misho 102: .ti -1c
1.1.1.2 ! misho 103: .RI "#define \fBCFG_STR_LIST\fP(name, def, flags) __CFG_STR_LIST(name, def, flags, 0, 0)"
1.1 misho 104: .br
1.1.1.2 ! misho 105: .RI "Initialize a string list option\&. "
1.1 misho 106: .ti -1c
1.1.1.2 ! misho 107: .RI "#define \fBCFG_STR_CB\fP(name, def, flags, cb) __CFG_STR(name, def, flags, 0, cb)"
1.1 misho 108: .br
1.1.1.2 ! misho 109: .RI "Initialize a string option with a value parsing callback\&. "
1.1 misho 110: .ti -1c
1.1.1.2 ! misho 111: .RI "#define \fBCFG_STR_LIST_CB\fP(name, def, flags, cb) __CFG_STR_LIST(name, def, flags, 0, cb)"
1.1 misho 112: .br
1.1.1.2 ! misho 113: .RI "Initialize a string list option with a value parsing callback\&. "
1.1 misho 114: .ti -1c
1.1.1.2 ! misho 115: .RI "#define \fBCFG_SIMPLE_STR\fP(name, svalue) __CFG_STR(name, 0, \fBCFGF_NONE\fP, svalue, 0)"
1.1 misho 116: .br
1.1.1.2 ! misho 117: .RI "Initialize a 'simple' string option\&. "
1.1 misho 118: .ti -1c
1.1.1.2 ! misho 119: .RI "#define \fBCFG_INT\fP(name, def, flags) __CFG_INT(name, def, flags, 0, 0)"
1.1 misho 120: .br
1.1.1.2 ! misho 121: .RI "Initialize an integer option\&. "
1.1 misho 122: .ti -1c
1.1.1.2 ! misho 123: .RI "#define \fBCFG_INT_LIST\fP(name, def, flags) __CFG_INT_LIST(name, def, flags, 0, 0)"
1.1 misho 124: .br
1.1.1.2 ! misho 125: .RI "Initialize an integer list option\&. "
1.1 misho 126: .ti -1c
1.1.1.2 ! misho 127: .RI "#define \fBCFG_INT_CB\fP(name, def, flags, cb) __CFG_INT(name, def, flags, 0, cb)"
1.1 misho 128: .br
1.1.1.2 ! misho 129: .RI "Initialize an integer option with a value parsing callback\&. "
1.1 misho 130: .ti -1c
1.1.1.2 ! misho 131: .RI "#define \fBCFG_INT_LIST_CB\fP(name, def, flags, cb) __CFG_INT_LIST(name, def, flags, 0, cb)"
1.1 misho 132: .br
1.1.1.2 ! misho 133: .RI "Initialize an integer list option with a value parsing callback\&. "
1.1 misho 134: .ti -1c
1.1.1.2 ! misho 135: .RI "#define \fBCFG_SIMPLE_INT\fP(name, svalue) __CFG_INT(name, 0, \fBCFGF_NONE\fP, svalue, 0)"
1.1 misho 136: .br
1.1.1.2 ! misho 137: .RI "Initialize a 'simple' integer option (see documentation for CFG_SIMPLE_STR for more information)\&. "
1.1 misho 138: .ti -1c
1.1.1.2 ! misho 139: .RI "#define \fBCFG_FLOAT\fP(name, def, flags) __CFG_FLOAT(name, def, flags, 0, 0)"
1.1 misho 140: .br
1.1.1.2 ! misho 141: .RI "Initialize a floating point option\&. "
1.1 misho 142: .ti -1c
1.1.1.2 ! misho 143: .RI "#define \fBCFG_FLOAT_LIST\fP(name, def, flags) __CFG_FLOAT_LIST(name, def, flags, 0, 0)"
1.1 misho 144: .br
1.1.1.2 ! misho 145: .RI "Initialize a floating point list option\&. "
1.1 misho 146: .ti -1c
1.1.1.2 ! misho 147: .RI "#define \fBCFG_FLOAT_CB\fP(name, def, flags, cb) __CFG_FLOAT(name, def, flags, 0, cb)"
1.1 misho 148: .br
1.1.1.2 ! misho 149: .RI "Initialize a floating point option with a value parsing callback\&. "
1.1 misho 150: .ti -1c
1.1.1.2 ! misho 151: .RI "#define \fBCFG_FLOAT_LIST_CB\fP(name, def, flags, cb) __CFG_FLOAT_LIST(name, def, flags, 0, cb)"
1.1 misho 152: .br
1.1.1.2 ! misho 153: .RI "Initialize a floating point list option with a value parsing callback\&. "
1.1 misho 154: .ti -1c
1.1.1.2 ! misho 155: .RI "#define \fBCFG_SIMPLE_FLOAT\fP(name, svalue) __CFG_FLOAT(name, 0, \fBCFGF_NONE\fP, svalue, 0)"
1.1 misho 156: .br
1.1.1.2 ! misho 157: .RI "Initialize a 'simple' floating point option (see documentation for CFG_SIMPLE_STR for more information)\&. "
1.1 misho 158: .ti -1c
1.1.1.2 ! misho 159: .RI "#define \fBCFG_BOOL\fP(name, def, flags) __CFG_BOOL(name, def, flags, 0, 0)"
1.1 misho 160: .br
1.1.1.2 ! misho 161: .RI "Initialize a boolean option\&. "
1.1 misho 162: .ti -1c
1.1.1.2 ! misho 163: .RI "#define \fBCFG_BOOL_LIST\fP(name, def, flags) __CFG_BOOL_LIST(name, def, flags, 0, 0)"
1.1 misho 164: .br
1.1.1.2 ! misho 165: .RI "Initialize a boolean list option\&. "
1.1 misho 166: .ti -1c
1.1.1.2 ! misho 167: .RI "#define \fBCFG_BOOL_CB\fP(name, def, flags, cb) __CFG_BOOL(name, def, flags, 0, cb)"
1.1 misho 168: .br
1.1.1.2 ! misho 169: .RI "Initialize a boolean option with a value parsing callback\&. "
1.1 misho 170: .ti -1c
1.1.1.2 ! misho 171: .RI "#define \fBCFG_BOOL_LIST_CB\fP(name, def, flags, cb) __CFG_BOOL_LIST(name, def, flags, 0, cb)"
1.1 misho 172: .br
1.1.1.2 ! misho 173: .RI "Initialize a boolean list option with a value parsing callback\&. "
1.1 misho 174: .ti -1c
1.1.1.2 ! misho 175: .RI "#define \fBCFG_SIMPLE_BOOL\fP(name, svalue) __CFG_BOOL(name, cfg_false, \fBCFGF_NONE\fP, svalue, 0)"
1.1 misho 176: .br
1.1.1.2 ! misho 177: .RI "Initialize a 'simple' boolean option (see documentation for CFG_SIMPLE_STR for more information)\&. "
1.1 misho 178: .ti -1c
1.1.1.2 ! misho 179: .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}"
1.1 misho 180: .br
1.1.1.2 ! misho 181: .RI "Initialize a section\&. "
1.1 misho 182: .ti -1c
1.1.1.2 ! misho 183: .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}"
1.1 misho 184: .br
1.1.1.2 ! misho 185: .RI "Initialize a function\&. "
1.1 misho 186: .ti -1c
1.1.1.2 ! misho 187: .RI "#define \fBCFG_PTR_CB\fP(name, def, flags, parsecb, freecb) __CFG_PTR(name, def, flags, 0, parsecb, freecb)"
1.1 misho 188: .br
1.1.1.2 ! misho 189: .RI "Initialize a user-defined option\&. "
1.1 misho 190: .ti -1c
1.1.1.2 ! misho 191: .RI "#define \fBCFG_PTR_LIST_CB\fP(name, def, flags, parsecb, freecb) __CFG_PTR(name, def, flags | \fBCFGF_LIST\fP, 0, parsecb, freecb)"
1.1 misho 192: .br
1.1.1.2 ! misho 193: .RI "Initialize a list of user-defined options\&. "
1.1 misho 194: .ti -1c
1.1.1.2 ! misho 195: .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}"
1.1 misho 196: .br
1.1.1.2 ! misho 197: .RI "Terminate list of options\&. "
1.1 misho 198: .in -1c
199: .SS "Typedefs"
200:
201: .in +1c
202: .ti -1c
1.1.1.2 ! misho 203: .RI "typedef int(* \fBcfg_func_t\fP) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, int argc, const char **argv)"
! 204: .br
! 205: .RI "Function prototype used by CFGT_FUNC options\&. "
! 206: .ti -1c
! 207: .RI "typedef void(* \fBcfg_print_func_t\fP) (\fBcfg_opt_t\fP *opt, unsigned int index, FILE *fp)"
! 208: .br
! 209: .RI "Function prototype used by the cfg_print_ functions\&. "
! 210: .ti -1c
! 211: .RI "typedef int(* \fBcfg_callback_t\fP) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, const char *value, void *result)"
1.1 misho 212: .br
1.1.1.2 ! misho 213: .RI "Value parsing callback prototype\&. "
1.1 misho 214: .ti -1c
1.1.1.2 ! misho 215: .RI "typedef int(* \fBcfg_validate_callback_t\fP) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt)"
1.1 misho 216: .br
1.1.1.2 ! misho 217: .RI "Validating callback prototype\&. "
1.1 misho 218: .ti -1c
1.1.1.2 ! misho 219: .RI "typedef int(* \fBcfg_validate_callback2_t\fP) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, void *value)"
1.1 misho 220: .br
1.1.1.2 ! misho 221: .RI "Validating callback2 prototype\&. "
1.1 misho 222: .ti -1c
1.1.1.2 ! misho 223: .RI "typedef void(* \fBcfg_free_func_t\fP) (void *value)"
1.1 misho 224: .br
1.1.1.2 ! misho 225: .RI "User-defined memory release function for CFG_PTR values\&. "
1.1 misho 226: .ti -1c
1.1.1.2 ! misho 227: .RI "typedef void(* \fBcfg_errfunc_t\fP) (\fBcfg_t\fP *cfg, const char *fmt, va_list ap)"
1.1 misho 228: .br
1.1.1.2 ! misho 229: .RI "Error reporting function\&. "
1.1 misho 230: .ti -1c
1.1.1.2 ! misho 231: .RI "typedef int(* \fBcfg_print_filter_func_t\fP) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt)"
1.1 misho 232: .br
1.1.1.2 ! misho 233: .RI "Print filter function\&. "
1.1 misho 234: .in -1c
235: .SS "Enumerations"
236:
237: .in +1c
238: .ti -1c
1.1.1.2 ! misho 239: .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 }"
1.1 misho 240: .br
1.1.1.2 ! misho 241: .RI "Fundamental option types\&. "
1.1 misho 242: .ti -1c
243: .RI "enum \fBcfg_bool_t\fP "
244: .br
1.1.1.2 ! misho 245: .RI "Boolean values\&. "
1.1 misho 246: .in -1c
247: .SS "Functions"
248:
249: .in +1c
250: .ti -1c
251: .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_init\fP (\fBcfg_opt_t\fP *opts, cfg_flag_t flags)"
252: .br
1.1.1.2 ! misho 253: .RI "Create and initialize a \fBcfg_t\fP structure\&. "
! 254: .ti -1c
! 255: .RI "DLLIMPORT int __export \fBcfg_add_searchpath\fP (\fBcfg_t\fP *cfg, const char *dir)"
! 256: .br
! 257: .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\&. "
! 258: .ti -1c
! 259: .RI "DLLIMPORT char *__export \fBcfg_searchpath\fP (cfg_searchpath_t *path, const char *file)"
! 260: .br
! 261: .RI "Search the linked-list of cfg_searchpath_t for the specified file\&. "
1.1 misho 262: .ti -1c
263: .RI "DLLIMPORT int __export \fBcfg_parse\fP (\fBcfg_t\fP *cfg, const char *filename)"
264: .br
1.1.1.2 ! misho 265: .RI "Parse a configuration file\&. "
1.1 misho 266: .ti -1c
267: .RI "DLLIMPORT int __export \fBcfg_parse_fp\fP (\fBcfg_t\fP *cfg, FILE *fp)"
268: .br
1.1.1.2 ! misho 269: .RI "Same as \fBcfg_parse()\fP above, but takes an already opened file as argument\&. "
1.1 misho 270: .ti -1c
271: .RI "DLLIMPORT int __export \fBcfg_parse_buf\fP (\fBcfg_t\fP *cfg, const char *buf)"
272: .br
1.1.1.2 ! misho 273: .RI "Same as \fBcfg_parse()\fP above, but takes a character buffer as argument\&. "
1.1 misho 274: .ti -1c
1.1.1.2 ! misho 275: .RI "DLLIMPORT int __export \fBcfg_free_value\fP (\fBcfg_opt_t\fP *opt)"
1.1 misho 276: .br
1.1.1.2 ! misho 277: .RI "Free the memory allocated for the values of a given option\&. "
1.1 misho 278: .ti -1c
1.1.1.2 ! misho 279: .RI "DLLIMPORT int __export \fBcfg_free\fP (\fBcfg_t\fP *cfg)"
1.1 misho 280: .br
1.1.1.2 ! misho 281: .RI "Free a \fBcfg_t\fP context\&. "
1.1 misho 282: .ti -1c
283: .RI "DLLIMPORT \fBcfg_errfunc_t\fP __export \fBcfg_set_error_function\fP (\fBcfg_t\fP *cfg, \fBcfg_errfunc_t\fP errfunc)"
284: .br
1.1.1.2 ! misho 285: .RI "Install a user-defined error reporting function\&. "
! 286: .ti -1c
! 287: .RI "DLLIMPORT void __export \fBcfg_error\fP (\fBcfg_t\fP *cfg, const char *fmt,\&.\&.\&.)"
! 288: .br
! 289: .RI "Show a parser error\&. "
! 290: .ti -1c
! 291: .RI "DLLIMPORT char *__export \fBcfg_opt_getcomment\fP (\fBcfg_opt_t\fP *opt)"
! 292: .br
! 293: .RI "Returns the option comment\&. "
1.1 misho 294: .ti -1c
1.1.1.2 ! misho 295: .RI "DLLIMPORT char *__export \fBcfg_getcomment\fP (\fBcfg_t\fP *cfg, const char *name)"
1.1 misho 296: .br
1.1.1.2 ! misho 297: .RI "Returns the option comment\&. "
1.1 misho 298: .ti -1c
299: .RI "DLLIMPORT signed long __export \fBcfg_opt_getnint\fP (\fBcfg_opt_t\fP *opt, unsigned int index)"
300: .br
1.1.1.2 ! misho 301: .RI "Returns the value of an integer option, given a \fBcfg_opt_t\fP pointer\&. "
1.1 misho 302: .ti -1c
303: .RI "DLLIMPORT long int __export \fBcfg_getnint\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)"
304: .br
1.1.1.2 ! misho 305: .RI "Indexed version of \fBcfg_getint()\fP, used for lists\&. "
1.1 misho 306: .ti -1c
307: .RI "DLLIMPORT long int __export \fBcfg_getint\fP (\fBcfg_t\fP *cfg, const char *name)"
308: .br
1.1.1.2 ! misho 309: .RI "Returns the value of an integer option\&. "
1.1 misho 310: .ti -1c
311: .RI "DLLIMPORT double __export \fBcfg_opt_getnfloat\fP (\fBcfg_opt_t\fP *opt, unsigned int index)"
312: .br
1.1.1.2 ! misho 313: .RI "Returns the value of a floating point option, given a \fBcfg_opt_t\fP pointer\&. "
1.1 misho 314: .ti -1c
315: .RI "DLLIMPORT double __export \fBcfg_getnfloat\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)"
316: .br
1.1.1.2 ! misho 317: .RI "Indexed version of \fBcfg_getfloat()\fP, used for lists\&. "
1.1 misho 318: .ti -1c
319: .RI "DLLIMPORT double __export \fBcfg_getfloat\fP (\fBcfg_t\fP *cfg, const char *name)"
320: .br
1.1.1.2 ! misho 321: .RI "Returns the value of a floating point option\&. "
1.1 misho 322: .ti -1c
323: .RI "DLLIMPORT char *__export \fBcfg_opt_getnstr\fP (\fBcfg_opt_t\fP *opt, unsigned int index)"
324: .br
1.1.1.2 ! misho 325: .RI "Returns the value of a string option, given a \fBcfg_opt_t\fP pointer\&. "
1.1 misho 326: .ti -1c
327: .RI "DLLIMPORT char *__export \fBcfg_getnstr\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)"
328: .br
1.1.1.2 ! misho 329: .RI "Indexed version of \fBcfg_getstr()\fP, used for lists\&. "
1.1 misho 330: .ti -1c
331: .RI "DLLIMPORT char *__export \fBcfg_getstr\fP (\fBcfg_t\fP *cfg, const char *name)"
332: .br
1.1.1.2 ! misho 333: .RI "Returns the value of a string option\&. "
1.1 misho 334: .ti -1c
335: .RI "DLLIMPORT \fBcfg_bool_t\fP __export \fBcfg_opt_getnbool\fP (\fBcfg_opt_t\fP *opt, unsigned int index)"
336: .br
1.1.1.2 ! misho 337: .RI "Returns the value of a boolean option, given a \fBcfg_opt_t\fP pointer\&. "
1.1 misho 338: .ti -1c
339: .RI "DLLIMPORT \fBcfg_bool_t\fP __export \fBcfg_getnbool\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)"
340: .br
1.1.1.2 ! misho 341: .RI "Indexed version of \fBcfg_getbool()\fP, used for lists\&. "
1.1 misho 342: .ti -1c
343: .RI "DLLIMPORT \fBcfg_bool_t\fP __export \fBcfg_getbool\fP (\fBcfg_t\fP *cfg, const char *name)"
344: .br
1.1.1.2 ! misho 345: .RI "Returns the value of a boolean option\&. "
1.1 misho 346: .ti -1c
347: .RI "DLLIMPORT void *__export \fBcfg_getptr\fP (\fBcfg_t\fP *cfg, const char *name)"
348: .br
1.1.1.2 ! misho 349: .RI "Returns the value of a user-defined option (void pointer)\&. "
1.1 misho 350: .ti -1c
351: .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_opt_getnsec\fP (\fBcfg_opt_t\fP *opt, unsigned int index)"
352: .br
1.1.1.2 ! misho 353: .RI "Returns the value of a section option, given a \fBcfg_opt_t\fP pointer\&. "
1.1 misho 354: .ti -1c
355: .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_getnsec\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)"
356: .br
1.1.1.2 ! misho 357: .RI "Indexed version of \fBcfg_getsec()\fP, used for sections with the CFGF_MULTI flag set\&. "
1.1 misho 358: .ti -1c
359: .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_opt_gettsec\fP (\fBcfg_opt_t\fP *opt, const char *title)"
360: .br
1.1.1.2 ! misho 361: .RI "Returns the value of a section option, given a \fBcfg_opt_t\fP pointer and the title\&. "
1.1 misho 362: .ti -1c
363: .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_gettsec\fP (\fBcfg_t\fP *cfg, const char *name, const char *title)"
364: .br
1.1.1.2 ! misho 365: .RI "Return a section given the title, used for section with the CFGF_TITLE flag set\&. "
1.1 misho 366: .ti -1c
367: .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_getsec\fP (\fBcfg_t\fP *cfg, const char *name)"
368: .br
1.1.1.2 ! misho 369: .RI "Returns the value of a section option\&. "
1.1 misho 370: .ti -1c
371: .RI "DLLIMPORT unsigned int __export \fBcfg_opt_size\fP (\fBcfg_opt_t\fP *opt)"
372: .br
1.1.1.2 ! misho 373: .RI "Return the number of values this option has\&. "
1.1 misho 374: .ti -1c
375: .RI "DLLIMPORT unsigned int __export \fBcfg_size\fP (\fBcfg_t\fP *cfg, const char *name)"
376: .br
1.1.1.2 ! misho 377: .RI "Return the number of values this option has\&. "
! 378: .ti -1c
! 379: .RI "const DLLIMPORT char *__export \fBcfg_title\fP (\fBcfg_t\fP *cfg)"
! 380: .br
! 381: .RI "Return the title of a section\&. "
1.1 misho 382: .ti -1c
1.1.1.2 ! misho 383: .RI "const DLLIMPORT char *__export \fBcfg_name\fP (\fBcfg_t\fP *cfg)"
1.1 misho 384: .br
1.1.1.2 ! misho 385: .RI "Return the name of a section\&. "
1.1 misho 386: .ti -1c
1.1.1.2 ! misho 387: .RI "const DLLIMPORT char *__export \fBcfg_opt_name\fP (\fBcfg_opt_t\fP *opt)"
1.1 misho 388: .br
1.1.1.2 ! misho 389: .RI "Return the name of an option\&. "
1.1 misho 390: .ti -1c
1.1.1.2 ! misho 391: .RI "const DLLIMPORT char * \fBcfg_opt_getstr\fP (\fBcfg_opt_t\fP *opt)"
1.1 misho 392: .br
1.1.1.2 ! misho 393: .RI "Return the string value of a key=value pair\&. "
1.1 misho 394: .ti -1c
395: .RI "DLLIMPORT int __export \fBcfg_include\fP (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, int argc, const char **argv)"
396: .br
1.1.1.2 ! misho 397: .RI "Predefined include-function\&. "
1.1 misho 398: .ti -1c
399: .RI "DLLIMPORT char *__export \fBcfg_tilde_expand\fP (const char *filename)"
400: .br
1.1.1.2 ! misho 401: .RI "Does tilde expansion (~ -> $HOME) on the filename\&. "
1.1 misho 402: .ti -1c
403: .RI "DLLIMPORT int __export \fBcfg_parse_boolean\fP (const char *s)"
404: .br
1.1.1.2 ! misho 405: .RI "Parse a boolean option string\&. "
! 406: .ti -1c
! 407: .RI "DLLIMPORT \fBcfg_opt_t\fP * \fBcfg_getnopt\fP (\fBcfg_t\fP *cfg, unsigned int index)"
! 408: .br
! 409: .RI "Return the nth option in a file or section\&. "
1.1 misho 410: .ti -1c
411: .RI "DLLIMPORT \fBcfg_opt_t\fP *__export \fBcfg_getopt\fP (\fBcfg_t\fP *cfg, const char *name)"
412: .br
1.1.1.2 ! misho 413: .RI "Return an option given it's name\&. "
! 414: .ti -1c
! 415: .RI "DLLIMPORT \fBcfg_value_t\fP * \fBcfg_setopt\fP (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, const char *value)"
! 416: .br
! 417: .RI "Set an option (create an instance of an option)\&. "
! 418: .ti -1c
! 419: .RI "DLLIMPORT int __export \fBcfg_opt_setcomment\fP (\fBcfg_opt_t\fP *opt, char *comment)"
! 420: .br
! 421: .RI "Annotate an option\&. "
! 422: .ti -1c
! 423: .RI "DLLIMPORT int __export \fBcfg_setcomment\fP (\fBcfg_t\fP *cfg, const char *name, char *comment)"
! 424: .br
! 425: .RI "Annotate an option given its name\&. "
! 426: .ti -1c
! 427: .RI "DLLIMPORT int __export \fBcfg_opt_setnint\fP (\fBcfg_opt_t\fP *opt, long int value, unsigned int index)"
! 428: .br
! 429: .RI "Set a value of an integer option\&. "
! 430: .ti -1c
! 431: .RI "DLLIMPORT int __export \fBcfg_setint\fP (\fBcfg_t\fP *cfg, const char *name, long int value)"
! 432: .br
! 433: .RI "Set the value of an integer option given its name\&. "
! 434: .ti -1c
! 435: .RI "DLLIMPORT int __export \fBcfg_setnint\fP (\fBcfg_t\fP *cfg, const char *name, long int value, unsigned int index)"
! 436: .br
! 437: .RI "Set a value of an integer option given its name and index\&. "
! 438: .ti -1c
! 439: .RI "DLLIMPORT int __export \fBcfg_opt_setnfloat\fP (\fBcfg_opt_t\fP *opt, double value, unsigned int index)"
! 440: .br
! 441: .RI "Set a value of a floating point option\&. "
! 442: .ti -1c
! 443: .RI "DLLIMPORT int __export \fBcfg_setfloat\fP (\fBcfg_t\fP *cfg, const char *name, double value)"
! 444: .br
! 445: .RI "Set the value of a floating point option given its name\&. "
! 446: .ti -1c
! 447: .RI "DLLIMPORT int __export \fBcfg_setnfloat\fP (\fBcfg_t\fP *cfg, const char *name, double value, unsigned int index)"
! 448: .br
! 449: .RI "Set a value of a floating point option given its name and index\&. "
! 450: .ti -1c
! 451: .RI "DLLIMPORT int __export \fBcfg_opt_setnbool\fP (\fBcfg_opt_t\fP *opt, \fBcfg_bool_t\fP value, unsigned int index)"
! 452: .br
! 453: .RI "Set a value of a boolean option\&. "
! 454: .ti -1c
! 455: .RI "DLLIMPORT int __export \fBcfg_setbool\fP (\fBcfg_t\fP *cfg, const char *name, \fBcfg_bool_t\fP value)"
! 456: .br
! 457: .RI "Set the value of a boolean option given its name\&. "
1.1 misho 458: .ti -1c
1.1.1.2 ! misho 459: .RI "DLLIMPORT int __export \fBcfg_setnbool\fP (\fBcfg_t\fP *cfg, const char *name, \fBcfg_bool_t\fP value, unsigned int index)"
1.1 misho 460: .br
1.1.1.2 ! misho 461: .RI "Set a value of a boolean option given its name and index\&. "
1.1 misho 462: .ti -1c
1.1.1.2 ! misho 463: .RI "DLLIMPORT int __export \fBcfg_opt_setnstr\fP (\fBcfg_opt_t\fP *opt, const char *value, unsigned int index)"
1.1 misho 464: .br
1.1.1.2 ! misho 465: .RI "Set a value of a string option\&. "
1.1 misho 466: .ti -1c
1.1.1.2 ! misho 467: .RI "DLLIMPORT int __export \fBcfg_setstr\fP (\fBcfg_t\fP *cfg, const char *name, const char *value)"
1.1 misho 468: .br
1.1.1.2 ! misho 469: .RI "Set the value of a string option given its name\&. "
1.1 misho 470: .ti -1c
1.1.1.2 ! misho 471: .RI "DLLIMPORT int __export \fBcfg_setnstr\fP (\fBcfg_t\fP *cfg, const char *name, const char *value, unsigned int index)"
1.1 misho 472: .br
1.1.1.2 ! misho 473: .RI "Set a value of a boolean option given its name and index\&. "
1.1 misho 474: .ti -1c
1.1.1.2 ! misho 475: .RI "DLLIMPORT int __export \fBcfg_setlist\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int nvalues,\&.\&.\&.)"
1.1 misho 476: .br
1.1.1.2 ! misho 477: .RI "Set values for a list option\&. "
1.1 misho 478: .ti -1c
1.1.1.2 ! misho 479: .RI "DLLIMPORT unsigned int __export \fBcfg_num\fP (\fBcfg_t\fP *cfg)"
1.1 misho 480: .br
1.1.1.2 ! misho 481: .RI "Return number of options in a file or section\&. "
1.1 misho 482: .ti -1c
1.1.1.2 ! misho 483: .RI "DLLIMPORT int __export \fBcfg_addlist\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int nvalues,\&.\&.\&.)"
1.1 misho 484: .br
1.1.1.2 ! misho 485: .RI "Add values for a list option\&. "
1.1 misho 486: .ti -1c
1.1.1.2 ! misho 487: .RI "DLLIMPORT int \fBcfg_opt_setmulti\fP (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, unsigned int nvalues, char **values)"
1.1 misho 488: .br
1.1.1.2 ! misho 489: .RI "Set an option (create an instance of an option)\&. "
1.1 misho 490: .ti -1c
1.1.1.2 ! misho 491: .RI "DLLIMPORT int \fBcfg_setmulti\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int nvalues, char **values)"
1.1 misho 492: .br
1.1.1.2 ! misho 493: .RI "Set an option (create an instance of an option)\&. "
1.1 misho 494: .ti -1c
1.1.1.2 ! misho 495: .RI "DLLIMPORT \fBcfg_t\fP * \fBcfg_addtsec\fP (\fBcfg_t\fP *cfg, const char *name, const char *title)"
1.1 misho 496: .br
1.1.1.2 ! misho 497: .RI "Create a new titled config section\&. "
1.1 misho 498: .ti -1c
1.1.1.2 ! misho 499: .RI "DLLIMPORT int __export \fBcfg_opt_rmnsec\fP (\fBcfg_opt_t\fP *opt, unsigned int index)"
1.1 misho 500: .br
1.1.1.2 ! misho 501: .RI "Removes and frees a config section, given a \fBcfg_opt_t\fP pointer\&. "
1.1 misho 502: .ti -1c
1.1.1.2 ! misho 503: .RI "DLLIMPORT int __export \fBcfg_rmnsec\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)"
1.1 misho 504: .br
1.1.1.2 ! misho 505: .RI "Indexed version of \fBcfg_rmsec()\fP, used for CFGF_MULTI sections\&. "
1.1 misho 506: .ti -1c
1.1.1.2 ! misho 507: .RI "DLLIMPORT int __export \fBcfg_rmsec\fP (\fBcfg_t\fP *cfg, const char *name)"
1.1 misho 508: .br
1.1.1.2 ! misho 509: .RI "Removes and frees a config section\&. "
1.1 misho 510: .ti -1c
1.1.1.2 ! misho 511: .RI "DLLIMPORT int __export \fBcfg_opt_rmtsec\fP (\fBcfg_opt_t\fP *opt, const char *title)"
1.1 misho 512: .br
1.1.1.2 ! misho 513: .RI "Removes and frees a config section, given a \fBcfg_opt_t\fP pointer and the title\&. "
1.1 misho 514: .ti -1c
1.1.1.2 ! misho 515: .RI "DLLIMPORT int __export \fBcfg_rmtsec\fP (\fBcfg_t\fP *cfg, const char *name, const char *title)"
1.1 misho 516: .br
1.1.1.2 ! misho 517: .RI "Removes and frees a section given the title, used for section with the CFGF_TITLE flag set\&. "
1.1 misho 518: .ti -1c
1.1.1.2 ! misho 519: .RI "DLLIMPORT int __export \fBcfg_opt_nprint_var\fP (\fBcfg_opt_t\fP *opt, unsigned int index, FILE *fp)"
1.1 misho 520: .br
1.1.1.2 ! misho 521: .RI "Default value print function\&. "
1.1 misho 522: .ti -1c
1.1.1.2 ! misho 523: .RI "DLLIMPORT int __export \fBcfg_opt_print_indent\fP (\fBcfg_opt_t\fP *opt, FILE *fp, int indent)"
1.1 misho 524: .br
1.1.1.2 ! misho 525: .RI "Print an option and its value to a file\&. "
1.1 misho 526: .ti -1c
1.1.1.2 ! misho 527: .RI "DLLIMPORT int __export \fBcfg_opt_print\fP (\fBcfg_opt_t\fP *opt, FILE *fp)"
1.1 misho 528: .br
1.1.1.2 ! misho 529: .RI "Print an option and its value to a file\&. "
1.1 misho 530: .ti -1c
1.1.1.2 ! misho 531: .RI "DLLIMPORT int __export \fBcfg_print_indent\fP (\fBcfg_t\fP *cfg, FILE *fp, int indent)"
1.1 misho 532: .br
1.1.1.2 ! misho 533: .RI "Print the options and values to a file\&. "
1.1 misho 534: .ti -1c
1.1.1.2 ! misho 535: .RI "DLLIMPORT int __export \fBcfg_print\fP (\fBcfg_t\fP *cfg, FILE *fp)"
1.1 misho 536: .br
1.1.1.2 ! misho 537: .RI "Print the options and values to a file\&. "
1.1 misho 538: .ti -1c
539: .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)"
540: .br
1.1.1.2 ! misho 541: .RI "Set a print callback function for an option\&. "
1.1 misho 542: .ti -1c
543: .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)"
544: .br
1.1.1.2 ! misho 545: .RI "Set a print callback function for an option given its name\&. "
! 546: .ti -1c
! 547: .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)"
! 548: .br
! 549: .RI "Install a user-defined print filter function\&. "
1.1 misho 550: .ti -1c
551: .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)"
552: .br
1.1.1.2 ! misho 553: .RI "Register a validating callback function for an option\&. "
! 554: .ti -1c
! 555: .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)"
! 556: .br
! 557: .RI "Register a validating callback function for an option\&. "
1.1 misho 558: .in -1c
559: .SH "Detailed Description"
560: .PP
1.1.1.2 ! misho 561: A configuration file parser library\&.
1.1 misho 562:
563:
1.1.1.2 ! misho 564: .SH "Macro Definition Documentation"
1.1 misho 565: .PP
1.1.1.2 ! misho 566: .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}"
! 567:
1.1 misho 568: .PP
1.1.1.2 ! misho 569: Terminate list of options\&. This must be the last initializer in the option list\&.
1.1 misho 570: .PP
1.1.1.2 ! misho 571: \fBExamples\fP
1.1 misho 572: .in +1c
1.1.1.2 ! misho 573: \fBftpconf\&.c\fP, \fBreread\&.c\fP, and \fBsimple\&.c\fP\&.
! 574: .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}"
! 575:
1.1 misho 576: .PP
1.1.1.2 ! misho 577: Initialize a function\&.
1.1 misho 578: .PP
1.1.1.2 ! misho 579: \fBParameters\fP
1.1 misho 580: .RS 4
581: \fIname\fP The name of the option
582: .br
1.1.1.2 ! misho 583: \fIfunc\fP The callback function\&.
1.1 misho 584: .RE
585: .PP
1.1.1.2 ! misho 586: \fBSee also\fP
1.1 misho 587: .RS 4
588: \fBcfg_func_t\fP
589: .RE
590: .PP
591:
592: .PP
1.1.1.2 ! misho 593: \fBExamples\fP
1.1 misho 594: .in +1c
1.1.1.2 ! misho 595: \fBftpconf\&.c\fP\&.
1.1 misho 596: .SS "#define CFG_PTR_CB(name, def, flags, parsecb, freecb) __CFG_PTR(name, def, flags, 0, parsecb, freecb)"
1.1.1.2 ! misho 597:
1.1 misho 598: .PP
1.1.1.2 ! misho 599: Initialize a user-defined option\&. CFG_PTR options can only be used together with a value parsing callback\&.
1.1 misho 600: .PP
1.1.1.2 ! misho 601: \fBParameters\fP
1.1 misho 602: .RS 4
603: \fIname\fP The name of the option
604: .br
605: \fIdef\fP Default value
606: .br
607: \fIflags\fP Flags
608: .br
609: \fIparsecb\fP Value parsing callback
610: .br
611: \fIfreecb\fP Memory release function
612: .RE
613: .PP
1.1.1.2 ! misho 614: \fBSee also\fP
1.1 misho 615: .RS 4
616: \fBcfg_callback_t\fP, \fBcfg_free_func_t\fP
617: .RE
618: .PP
619:
1.1.1.2 ! misho 620: .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}"
! 621:
1.1 misho 622: .PP
1.1.1.2 ! misho 623: Initialize a section\&.
1.1 misho 624: .PP
1.1.1.2 ! misho 625: \fBParameters\fP
1.1 misho 626: .RS 4
627: \fIname\fP The name of the option
628: .br
629: \fIopts\fP Array of options that are valid within this section
630: .br
631: \fIflags\fP Flags, specify CFGF_MULTI if it should be possible to have multiples of the same section, and CFGF_TITLE if the section(s) must have a title (which can be used in the \fBcfg_gettsec()\fP function)
632: .RE
633: .PP
634:
635: .PP
1.1.1.2 ! misho 636: \fBExamples\fP
1.1 misho 637: .in +1c
1.1.1.2 ! misho 638: \fBftpconf\&.c\fP, and \fBreread\&.c\fP\&.
! 639: .SS "#define CFG_SIMPLE_INT(name, svalue) __CFG_INT(name, 0, \fBCFGF_NONE\fP, svalue, 0)"
! 640:
1.1 misho 641: .PP
1.1.1.2 ! misho 642: 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\&.
1.1 misho 643: .PP
1.1.1.2 ! misho 644: \fBExamples\fP
! 645: .in +1c
! 646: \fBsimple\&.c\fP\&.
! 647: .SS "#define CFG_SIMPLE_STR(name, svalue) __CFG_STR(name, 0, \fBCFGF_NONE\fP, svalue, 0)"
! 648:
1.1 misho 649: .PP
1.1.1.2 ! misho 650: 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\&.
1.1 misho 651: .PP
1.1.1.2 ! misho 652: 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\&.
1.1 misho 653: .PP
1.1.1.2 ! misho 654: 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\&.
! 655: .PP
! 656: \fBParameters\fP
1.1 misho 657: .RS 4
658: \fIname\fP name of the option
659: .br
1.1.1.2 ! misho 660: \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
1.1 misho 661: .PP
662: .nf
663:
1.1.1.2 ! misho 664: char *user = 'joe';
! 665: \&.\&.\&.
! 666: \fBcfg_opt_t\fP opts[] = {
! 667: CFG_SIMPLE_STR('user', &user),
! 668: \&.\&.\&.
1.1 misho 669: .fi
670: .PP
1.1.1.2 ! misho 671: 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:
1.1 misho 672: .PP
673: .nf
674:
1.1.1.2 ! misho 675: char *user = strdup('joe');
! 676: \&.\&.\&.
! 677: \fBcfg_opt_t\fP opts[] = {
! 678: CFG_SIMPLE_STR('user', &user),
! 679: \&.\&.\&.
1.1 misho 680: .fi
681: .PP
682: Alternatively, the default value can be set after the opts struct is defined, as in:
683: .PP
684: .nf
685:
1.1.1.2 ! misho 686: char *user = 0;
! 687: \&.\&.\&.
! 688: \fBcfg_opt_t\fP opts[] = {
! 689: CFG_SIMPLE_STR('user', &user),
! 690: \&.\&.\&.
! 691: user = strdup('joe');
! 692: cfg = cfg_init(opts, 0);
! 693: cfg_parse(cfg, filename);
1.1 misho 694: .fi
695: .PP
696:
697: .RE
698: .PP
699:
700: .PP
1.1.1.2 ! misho 701: \fBExamples\fP
1.1 misho 702: .in +1c
1.1.1.2 ! misho 703: \fBsimple\&.c\fP\&.
1.1 misho 704: .SS "#define CFG_SUCCESS 0"
705:
706: .PP
1.1.1.2 ! misho 707: Return codes from \fBcfg_parse()\fP, \fBcfg_parse_boolean()\fP, and cfg_set*() functions\&.
1.1 misho 708: .PP
1.1.1.2 ! misho 709: \fBExamples\fP
! 710: .in +1c
! 711: \fBftpconf\&.c\fP, and \fBreread\&.c\fP\&.
! 712: .SS "#define CFGF_DEPRECATED (1 << 9)"
! 713:
1.1 misho 714: .PP
1.1.1.2 ! misho 715: option is deprecated and should be ignored\&.
! 716: .SS "#define CFGF_NONE (0)"
1.1 misho 717:
718: .PP
1.1.1.2 ! misho 719: Flags\&.
! 720: .PP
! 721: \fBExamples\fP
1.1 misho 722: .in +1c
1.1.1.2 ! misho 723: \fBftpconf\&.c\fP, and \fBreread\&.c\fP\&.
1.1 misho 724: .SH "Typedef Documentation"
725: .PP
1.1.1.2 ! misho 726: .SS "typedef int(* cfg_callback_t) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, const char *value, void *result)"
! 727:
1.1 misho 728: .PP
1.1.1.2 ! misho 729: 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\&.
1.1 misho 730: .PP
1.1.1.2 ! misho 731: 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\&.
1.1 misho 732: .PP
1.1.1.2 ! misho 733: \fBParameters\fP
1.1 misho 734: .RS 4
1.1.1.2 ! misho 735: \fIcfg\fP The configuration file context\&.
1.1 misho 736: .br
1.1.1.2 ! misho 737: \fIopt\fP The option\&.
1.1 misho 738: .br
1.1.1.2 ! misho 739: \fIvalue\fP The value found in the configuration file\&.
1.1 misho 740: .br
1.1.1.2 ! misho 741: \fIresult\fP Pointer to storage for the result, cast to a void pointer\&.
1.1 misho 742: .RE
743: .PP
1.1.1.2 ! misho 744: \fBReturns\fP
1.1 misho 745: .RS 4
1.1.1.2 ! misho 746: 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\&.
1.1 misho 747: .RE
748: .PP
749:
1.1.1.2 ! misho 750: .SS "typedef void(* cfg_errfunc_t) (\fBcfg_t\fP *cfg, const char *fmt, va_list ap)"
1.1 misho 751:
752: .PP
1.1.1.2 ! misho 753: Error reporting function\&.
! 754: .SS "typedef void(* cfg_free_func_t) (void *value)"
! 755:
1.1 misho 756: .PP
1.1.1.2 ! misho 757: 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\&.
! 758: .SS "typedef int(* cfg_func_t) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, int argc, const char **argv)"
! 759:
1.1 misho 760: .PP
1.1.1.2 ! misho 761: 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\&.
1.1 misho 762: .PP
1.1.1.2 ! misho 763: \fBParameters\fP
1.1 misho 764: .RS 4
1.1.1.2 ! misho 765: \fIcfg\fP The configuration file context\&.
1.1 misho 766: .br
1.1.1.2 ! misho 767: \fIopt\fP The option\&.
1.1 misho 768: .br
1.1.1.2 ! misho 769: \fIargc\fP Number of arguments passed\&. The callback function is responsible for checking that the correct number of arguments are passed\&.
1.1 misho 770: .br
1.1.1.2 ! misho 771: \fIargv\fP Arguments as an array of character strings\&.
1.1 misho 772: .RE
773: .PP
1.1.1.2 ! misho 774: \fBReturns\fP
1.1 misho 775: .RS 4
1.1.1.2 ! misho 776: 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\&.
1.1 misho 777: .RE
778: .PP
1.1.1.2 ! misho 779: \fBSee also\fP
1.1 misho 780: .RS 4
781: \fBCFG_FUNC\fP
782: .RE
783: .PP
784:
1.1.1.2 ! misho 785: .SS "typedef int(* cfg_print_filter_func_t) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt)"
! 786:
1.1 misho 787: .PP
1.1.1.2 ! misho 788: Print filter function\&.
1.1 misho 789: .PP
1.1.1.2 ! misho 790: \fBParameters\fP
! 791: .RS 4
! 792: \fIcfg\fP The configuration file context that opt belongs to\&.
! 793: .br
! 794: \fIopt\fP The configuration option that is about to be printed, or not\&.
! 795: .RE
1.1 misho 796: .PP
1.1.1.2 ! misho 797: \fBReturns\fP
! 798: .RS 4
! 799: Zero if opt should be printed, non-zero if it should be filtered out\&.
! 800: .RE
1.1 misho 801: .PP
1.1.1.2 ! misho 802: \fBSee also\fP
! 803: .RS 4
! 804: \fBcfg_set_print_filter_func()\fP
! 805: .RE
! 806: .PP
! 807:
! 808: .SS "typedef void(* cfg_print_func_t) (\fBcfg_opt_t\fP *opt, unsigned int index, FILE *fp)"
! 809:
! 810: .PP
! 811: 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\&.
! 812: .PP
! 813: 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\&.
! 814: .PP
! 815: \fBParameters\fP
1.1 misho 816: .RS 4
817: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
818: .br
1.1.1.2 ! misho 819: \fIindex\fP Index of the value to get\&. Zero based\&.
1.1 misho 820: .br
1.1.1.2 ! misho 821: \fIfp\fP File stream to print to, use stdout to print to the screen\&.
1.1 misho 822: .RE
823: .PP
1.1.1.2 ! misho 824: \fBSee also\fP
1.1 misho 825: .RS 4
826: \fBcfg_print\fP, \fBcfg_set_print_func\fP
827: .RE
828: .PP
829:
1.1.1.2 ! misho 830: .SS "typedef int(* cfg_validate_callback2_t) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, void *value)"
! 831:
! 832: .PP
! 833: 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\&.
! 834: .PP
! 835: \fBReturns\fP
! 836: .RS 4
! 837: On success, 0 should be returned\&. All other values indicates an error, and the cfg_set*() function will return without setting the value\&.
! 838: .RE
! 839: .PP
! 840: \fBSee also\fP
! 841: .RS 4
! 842: \fBcfg_set_validate_func2()\fP
! 843: .RE
1.1 misho 844: .PP
1.1.1.2 ! misho 845:
! 846: .SS "typedef int(* cfg_validate_callback_t) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt)"
! 847:
1.1 misho 848: .PP
1.1.1.2 ! misho 849: 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\&.
1.1 misho 850: .PP
1.1.1.2 ! misho 851: \fBReturns\fP
1.1 misho 852: .RS 4
1.1.1.2 ! misho 853: 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\&.
1.1 misho 854: .RE
855: .PP
1.1.1.2 ! misho 856: \fBSee also\fP
1.1 misho 857: .RS 4
858: \fBcfg_set_validate_func\fP
859: .RE
860: .PP
861:
862: .SH "Enumeration Type Documentation"
863: .PP
864: .SS "enum \fBcfg_bool_t\fP"
865:
1.1.1.2 ! misho 866: .PP
! 867: Boolean values\&.
1.1 misho 868: .SS "enum \fBcfg_type_t\fP"
1.1.1.2 ! misho 869:
1.1 misho 870: .PP
1.1.1.2 ! misho 871: Fundamental option types\&.
1.1 misho 872: .PP
1.1.1.2 ! misho 873: \fBEnumerator\fP
1.1 misho 874: .in +1c
875: .TP
876: \fB\fICFGT_INT \fP\fP
877: integer
878: .TP
879: \fB\fICFGT_FLOAT \fP\fP
880: floating point number
881: .TP
882: \fB\fICFGT_STR \fP\fP
883: string
884: .TP
885: \fB\fICFGT_BOOL \fP\fP
886: boolean value
887: .TP
888: \fB\fICFGT_SEC \fP\fP
889: section
890: .TP
891: \fB\fICFGT_FUNC \fP\fP
892: function
893: .TP
894: \fB\fICFGT_PTR \fP\fP
895: pointer to user-defined value
1.1.1.2 ! misho 896: .TP
! 897: \fB\fICFGT_COMMENT \fP\fP
! 898: comment/annotation
1.1 misho 899: .SH "Function Documentation"
900: .PP
1.1.1.2 ! misho 901: .SS "DLLIMPORT int __export cfg_add_searchpath (\fBcfg_t\fP * cfg, const char * dir)"
! 902:
! 903: .PP
! 904: 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\&.
1.1 misho 905: .PP
1.1.1.2 ! misho 906: \fBParameters\fP
! 907: .RS 4
! 908: \fIcfg\fP The configuration file context as returned from \fBcfg_init()\fP\&.
! 909: .br
! 910: \fIdir\fP Directory to be added to the search path\&.
! 911: .RE
! 912: .PP
! 913: \fBReturns\fP
! 914: .RS 4
! 915: On success, CFG_SUCCESS, on failure (which can only be caused by a failed malloc()), CFG_PARSE_ERROR\&.
! 916: .RE
! 917: .PP
! 918:
! 919: .SS "DLLIMPORT int __export cfg_addlist (\fBcfg_t\fP * cfg, const char * name, unsigned int nvalues, \&.\&.\&.)"
! 920:
1.1 misho 921: .PP
1.1.1.2 ! misho 922: Add values for a list option\&. The new values are appended to any current values in the list\&.
1.1 misho 923: .PP
1.1.1.2 ! misho 924: \fBParameters\fP
1.1 misho 925: .RS 4
1.1.1.2 ! misho 926: \fIcfg\fP The configuration file context\&.
1.1 misho 927: .br
1.1.1.2 ! misho 928: \fIname\fP The name of the option\&.
1.1 misho 929: .br
1.1.1.2 ! misho 930: \fInvalues\fP Number of values to add\&.
1.1 misho 931: .br
1.1.1.2 ! misho 932: \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\&.
1.1 misho 933: .RE
934: .PP
1.1.1.2 ! misho 935: \fBReturns\fP
! 936: .RS 4
! 937: POSIX OK(0), or non-zero on failure\&.
! 938: .RE
! 939: .PP
! 940:
! 941: .SS "DLLIMPORT \fBcfg_t\fP* cfg_addtsec (\fBcfg_t\fP * cfg, const char * name, const char * title)"
1.1 misho 942:
943: .PP
1.1.1.2 ! misho 944: Create a new titled config section\&.
! 945: .PP
! 946: \fBParameters\fP
! 947: .RS 4
! 948: \fIcfg\fP The configuration file context\&.
! 949: .br
! 950: \fIname\fP The name of the option\&.
! 951: .br
! 952: \fItitle\fP The title of this section\&.
! 953: .RE
! 954: .PP
! 955: \fBReturns\fP
! 956: .RS 4
! 957: 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\&.
! 958: .RE
1.1 misho 959: .PP
1.1.1.2 ! misho 960:
! 961: .SS "DLLIMPORT void __export cfg_error (\fBcfg_t\fP * cfg, const char * fmt, \&.\&.\&.)"
! 962:
1.1 misho 963: .PP
1.1.1.2 ! misho 964: Show a parser error\&. Any user-defined error reporting function is called\&.
1.1 misho 965: .PP
1.1.1.2 ! misho 966: \fBSee also\fP
1.1 misho 967: .RS 4
968: \fBcfg_set_error_function\fP
969: .RE
970: .PP
971:
972: .PP
1.1.1.2 ! misho 973: \fBExamples\fP
1.1 misho 974: .in +1c
1.1.1.2 ! misho 975: \fBftpconf\&.c\fP\&.
! 976: .SS "DLLIMPORT int __export cfg_free (\fBcfg_t\fP * cfg)"
! 977:
1.1 misho 978: .PP
1.1.1.2 ! misho 979: 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\&.
1.1 misho 980: .PP
1.1.1.2 ! misho 981: \fBReturns\fP
! 982: .RS 4
! 983: POSIX OK(0), or non-zero on failure\&.
! 984: .RE
1.1 misho 985: .PP
1.1.1.2 ! misho 986:
1.1 misho 987: .PP
1.1.1.2 ! misho 988: \fBExamples\fP
1.1 misho 989: .in +1c
1.1.1.2 ! misho 990: \fBftpconf\&.c\fP, \fBreread\&.c\fP, and \fBsimple\&.c\fP\&.
! 991: .SS "DLLIMPORT int __export cfg_free_value (\fBcfg_opt_t\fP * opt)"
! 992:
1.1 misho 993: .PP
1.1.1.2 ! misho 994: 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)\&.
1.1 misho 995: .PP
1.1.1.2 ! misho 996: \fBSee also\fP
! 997: .RS 4
! 998: \fBcfg_free()\fP
! 999: .RE
1.1 misho 1000: .PP
1.1.1.2 ! misho 1001: \fBReturns\fP
1.1 misho 1002: .RS 4
1.1.1.2 ! misho 1003: POSIX OK(0), or non-zero on failure\&.
1.1 misho 1004: .RE
1005: .PP
1006:
1007: .SS "DLLIMPORT \fBcfg_bool_t\fP __export cfg_getbool (\fBcfg_t\fP * cfg, const char * name)"
1.1.1.2 ! misho 1008:
1.1 misho 1009: .PP
1.1.1.2 ! misho 1010: Returns the value of a boolean option\&.
1.1 misho 1011: .PP
1.1.1.2 ! misho 1012: \fBParameters\fP
1.1 misho 1013: .RS 4
1.1.1.2 ! misho 1014: \fIcfg\fP The configuration file context\&.
1.1 misho 1015: .br
1.1.1.2 ! misho 1016: \fIname\fP The name of the option\&.
1.1 misho 1017: .RE
1018: .PP
1.1.1.2 ! misho 1019: \fBReturns\fP
1.1 misho 1020: .RS 4
1.1.1.2 ! misho 1021: 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\&.
1.1 misho 1022: .RE
1023: .PP
1024:
1025: .PP
1.1.1.2 ! misho 1026: \fBExamples\fP
1.1 misho 1027: .in +1c
1.1.1.2 ! misho 1028: \fBftpconf\&.c\fP\&.
! 1029: .SS "DLLIMPORT char* __export cfg_getcomment (\fBcfg_t\fP * cfg, const char * name)"
! 1030:
! 1031: .PP
! 1032: 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\&.
! 1033: .PP
! 1034: \fBParameters\fP
! 1035: .RS 4
! 1036: \fIcfg\fP The configuration file context\&.
! 1037: .br
! 1038: \fIname\fP The name of the option\&.
! 1039: .RE
! 1040: .PP
! 1041: \fBSee also\fP
! 1042: .RS 4
! 1043: \fBcfg_setcomment\fP
! 1044: .RE
! 1045: .PP
! 1046: \fBReturns\fP
! 1047: .RS 4
! 1048: The comment for this option, or NULL if unset
! 1049: .RE
! 1050: .PP
! 1051:
1.1 misho 1052: .SS "DLLIMPORT double __export cfg_getfloat (\fBcfg_t\fP * cfg, const char * name)"
1.1.1.2 ! misho 1053:
1.1 misho 1054: .PP
1.1.1.2 ! misho 1055: Returns the value of a floating point option\&.
1.1 misho 1056: .PP
1.1.1.2 ! misho 1057: \fBParameters\fP
1.1 misho 1058: .RS 4
1.1.1.2 ! misho 1059: \fIcfg\fP The configuration file context\&.
1.1 misho 1060: .br
1.1.1.2 ! misho 1061: \fIname\fP The name of the option\&.
1.1 misho 1062: .RE
1063: .PP
1.1.1.2 ! misho 1064: \fBReturns\fP
1.1 misho 1065: .RS 4
1.1.1.2 ! misho 1066: 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\&.
1.1 misho 1067: .RE
1068: .PP
1069:
1070: .SS "DLLIMPORT long int __export cfg_getint (\fBcfg_t\fP * cfg, const char * name)"
1.1.1.2 ! misho 1071:
1.1 misho 1072: .PP
1.1.1.2 ! misho 1073: Returns the value of an integer option\&. This is the same as calling cfg_getnint with index 0\&.
1.1 misho 1074: .PP
1.1.1.2 ! misho 1075: \fBParameters\fP
1.1 misho 1076: .RS 4
1.1.1.2 ! misho 1077: \fIcfg\fP The configuration file context\&.
1.1 misho 1078: .br
1.1.1.2 ! misho 1079: \fIname\fP The name of the option\&.
1.1 misho 1080: .RE
1081: .PP
1.1.1.2 ! misho 1082: \fBReturns\fP
1.1 misho 1083: .RS 4
1.1.1.2 ! misho 1084: 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\&.
1.1 misho 1085: .RE
1086: .PP
1087:
1088: .PP
1.1.1.2 ! misho 1089: \fBExamples\fP
1.1 misho 1090: .in +1c
1.1.1.2 ! misho 1091: \fBftpconf\&.c\fP, and \fBreread\&.c\fP\&.
1.1 misho 1092: .SS "DLLIMPORT \fBcfg_bool_t\fP __export cfg_getnbool (\fBcfg_t\fP * cfg, const char * name, unsigned int index)"
1.1.1.2 ! misho 1093:
1.1 misho 1094: .PP
1.1.1.2 ! misho 1095: Indexed version of \fBcfg_getbool()\fP, used for lists\&.
1.1 misho 1096: .PP
1.1.1.2 ! misho 1097: \fBParameters\fP
1.1 misho 1098: .RS 4
1.1.1.2 ! misho 1099: \fIcfg\fP The configuration file context\&.
1.1 misho 1100: .br
1.1.1.2 ! misho 1101: \fIname\fP The name of the option\&.
1.1 misho 1102: .br
1.1.1.2 ! misho 1103: \fIindex\fP Index of the value to get\&. Zero based\&.
1.1 misho 1104: .RE
1105: .PP
1.1.1.2 ! misho 1106: \fBSee also\fP
1.1 misho 1107: .RS 4
1108: \fBcfg_getbool\fP
1109: .RE
1110: .PP
1111:
1112: .SS "DLLIMPORT double __export cfg_getnfloat (\fBcfg_t\fP * cfg, const char * name, unsigned int index)"
1.1.1.2 ! misho 1113:
1.1 misho 1114: .PP
1.1.1.2 ! misho 1115: Indexed version of \fBcfg_getfloat()\fP, used for lists\&.
1.1 misho 1116: .PP
1.1.1.2 ! misho 1117: \fBParameters\fP
1.1 misho 1118: .RS 4
1.1.1.2 ! misho 1119: \fIcfg\fP The configuration file context\&.
1.1 misho 1120: .br
1.1.1.2 ! misho 1121: \fIname\fP The name of the option\&.
1.1 misho 1122: .br
1.1.1.2 ! misho 1123: \fIindex\fP Index of the value to get\&. Zero based\&.
1.1 misho 1124: .RE
1125: .PP
1.1.1.2 ! misho 1126: \fBSee also\fP
1.1 misho 1127: .RS 4
1128: \fBcfg_getfloat\fP
1129: .RE
1130: .PP
1131:
1132: .SS "DLLIMPORT long int __export cfg_getnint (\fBcfg_t\fP * cfg, const char * name, unsigned int index)"
1.1.1.2 ! misho 1133:
1.1 misho 1134: .PP
1.1.1.2 ! misho 1135: Indexed version of \fBcfg_getint()\fP, used for lists\&.
1.1 misho 1136: .PP
1.1.1.2 ! misho 1137: \fBParameters\fP
1.1 misho 1138: .RS 4
1.1.1.2 ! misho 1139: \fIcfg\fP The configuration file context\&.
1.1 misho 1140: .br
1.1.1.2 ! misho 1141: \fIname\fP The name of the option\&.
1.1 misho 1142: .br
1.1.1.2 ! misho 1143: \fIindex\fP Index of the value to get\&. Zero based\&.
1.1 misho 1144: .RE
1145: .PP
1.1.1.2 ! misho 1146: \fBSee also\fP
1.1 misho 1147: .RS 4
1148: \fBcfg_getint\fP
1149: .RE
1150: .PP
1151:
1.1.1.2 ! misho 1152: .SS "DLLIMPORT \fBcfg_opt_t\fP* cfg_getnopt (\fBcfg_t\fP * cfg, unsigned int index)"
! 1153:
! 1154: .PP
! 1155: Return the nth option in a file or section\&.
! 1156: .PP
! 1157: \fBParameters\fP
! 1158: .RS 4
! 1159: \fIcfg\fP The configuration file or section context
! 1160: .br
! 1161: \fIindex\fP Option index
! 1162: .RE
! 1163: .PP
! 1164: \fBSee also\fP
! 1165: .RS 4
! 1166: \fBcfg_num\fP
! 1167: .RE
! 1168: .PP
! 1169:
1.1 misho 1170: .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_getnsec (\fBcfg_t\fP * cfg, const char * name, unsigned int index)"
1.1.1.2 ! misho 1171:
1.1 misho 1172: .PP
1.1.1.2 ! misho 1173: Indexed version of \fBcfg_getsec()\fP, used for sections with the CFGF_MULTI flag set\&.
1.1 misho 1174: .PP
1.1.1.2 ! misho 1175: \fBParameters\fP
1.1 misho 1176: .RS 4
1.1.1.2 ! misho 1177: \fIcfg\fP The configuration file context\&.
1.1 misho 1178: .br
1.1.1.2 ! misho 1179: \fIname\fP The name of the option\&.
1.1 misho 1180: .br
1.1.1.2 ! misho 1181: \fIindex\fP Index of the section to get\&. Zero based\&.
1.1 misho 1182: .RE
1183: .PP
1.1.1.2 ! misho 1184: \fBSee also\fP
1.1 misho 1185: .RS 4
1186: \fBcfg_getsec\fP
1187: .RE
1188: .PP
1189:
1190: .PP
1.1.1.2 ! misho 1191: \fBExamples\fP
1.1 misho 1192: .in +1c
1.1.1.2 ! misho 1193: \fBftpconf\&.c\fP, and \fBreread\&.c\fP\&.
1.1 misho 1194: .SS "DLLIMPORT char* __export cfg_getnstr (\fBcfg_t\fP * cfg, const char * name, unsigned int index)"
1.1.1.2 ! misho 1195:
1.1 misho 1196: .PP
1.1.1.2 ! misho 1197: Indexed version of \fBcfg_getstr()\fP, used for lists\&.
1.1 misho 1198: .PP
1.1.1.2 ! misho 1199: \fBParameters\fP
1.1 misho 1200: .RS 4
1.1.1.2 ! misho 1201: \fIcfg\fP The configuration file context\&.
1.1 misho 1202: .br
1.1.1.2 ! misho 1203: \fIname\fP The name of the option\&.
1.1 misho 1204: .br
1.1.1.2 ! misho 1205: \fIindex\fP Index of the value to get\&. Zero based\&.
1.1 misho 1206: .RE
1207: .PP
1.1.1.2 ! misho 1208: \fBSee also\fP
1.1 misho 1209: .RS 4
1210: \fBcfg_getstr\fP
1211: .RE
1212: .PP
1213:
1214: .PP
1.1.1.2 ! misho 1215: \fBExamples\fP
1.1 misho 1216: .in +1c
1.1.1.2 ! misho 1217: \fBftpconf\&.c\fP\&.
1.1 misho 1218: .SS "DLLIMPORT \fBcfg_opt_t\fP* __export cfg_getopt (\fBcfg_t\fP * cfg, const char * name)"
1.1.1.2 ! misho 1219:
1.1 misho 1220: .PP
1.1.1.2 ! misho 1221: Return an option given it's name\&.
1.1 misho 1222: .PP
1.1.1.2 ! misho 1223: \fBParameters\fP
1.1 misho 1224: .RS 4
1.1.1.2 ! misho 1225: \fIcfg\fP The configuration file context\&.
1.1 misho 1226: .br
1.1.1.2 ! misho 1227: \fIname\fP The name of the option\&.
1.1 misho 1228: .RE
1229: .PP
1.1.1.2 ! misho 1230: \fBReturns\fP
1.1 misho 1231: .RS 4
1.1.1.2 ! misho 1232: Returns a pointer to the option\&. If the option isn't declared, libConfuse will print an error message and return 0\&.
1.1 misho 1233: .RE
1234: .PP
1235:
1236: .SS "DLLIMPORT void* __export cfg_getptr (\fBcfg_t\fP * cfg, const char * name)"
1.1.1.2 ! misho 1237:
1.1 misho 1238: .PP
1.1.1.2 ! misho 1239: Returns the value of a user-defined option (void pointer)\&.
1.1 misho 1240: .PP
1.1.1.2 ! misho 1241: \fBParameters\fP
1.1 misho 1242: .RS 4
1.1.1.2 ! misho 1243: \fIcfg\fP The configuration file context\&.
1.1 misho 1244: .br
1.1.1.2 ! misho 1245: \fIname\fP The name of the option\&.
1.1 misho 1246: .RE
1247: .PP
1.1.1.2 ! misho 1248: \fBReturns\fP
1.1 misho 1249: .RS 4
1.1.1.2 ! misho 1250: 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\&.
1.1 misho 1251: .RE
1252: .PP
1253:
1254: .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_getsec (\fBcfg_t\fP * cfg, const char * name)"
1.1.1.2 ! misho 1255:
1.1 misho 1256: .PP
1.1.1.2 ! misho 1257: 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\&.
1.1 misho 1258: .PP
1.1.1.2 ! misho 1259: \fBParameters\fP
1.1 misho 1260: .RS 4
1.1.1.2 ! misho 1261: \fIcfg\fP The configuration file context\&.
1.1 misho 1262: .br
1.1.1.2 ! misho 1263: \fIname\fP The name of the option\&.
1.1 misho 1264: .RE
1265: .PP
1.1.1.2 ! misho 1266: \fBReturns\fP
1.1 misho 1267: .RS 4
1.1.1.2 ! misho 1268: 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\&.
1.1 misho 1269: .RE
1270: .PP
1271:
1272: .SS "DLLIMPORT char* __export cfg_getstr (\fBcfg_t\fP * cfg, const char * name)"
1.1.1.2 ! misho 1273:
1.1 misho 1274: .PP
1.1.1.2 ! misho 1275: Returns the value of a string option\&.
1.1 misho 1276: .PP
1.1.1.2 ! misho 1277: \fBParameters\fP
1.1 misho 1278: .RS 4
1.1.1.2 ! misho 1279: \fIcfg\fP The configuration file context\&.
1.1 misho 1280: .br
1.1.1.2 ! misho 1281: \fIname\fP The name of the option\&.
1.1 misho 1282: .RE
1283: .PP
1.1.1.2 ! misho 1284: \fBReturns\fP
1.1 misho 1285: .RS 4
1.1.1.2 ! misho 1286: 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\&.
1.1 misho 1287: .RE
1288: .PP
1289:
1290: .PP
1.1.1.2 ! misho 1291: \fBExamples\fP
1.1 misho 1292: .in +1c
1.1.1.2 ! misho 1293: \fBftpconf\&.c\fP, and \fBreread\&.c\fP\&.
1.1 misho 1294: .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_gettsec (\fBcfg_t\fP * cfg, const char * name, const char * title)"
1.1.1.2 ! misho 1295:
1.1 misho 1296: .PP
1.1.1.2 ! misho 1297: Return a section given the title, used for section with the CFGF_TITLE flag set\&.
1.1 misho 1298: .PP
1.1.1.2 ! misho 1299: \fBParameters\fP
1.1 misho 1300: .RS 4
1.1.1.2 ! misho 1301: \fIcfg\fP The configuration file context\&.
1.1 misho 1302: .br
1.1.1.2 ! misho 1303: \fIname\fP The name of the option\&.
1.1 misho 1304: .br
1.1.1.2 ! misho 1305: \fItitle\fP The title of this section\&. The CFGF_TITLE flag must have been set for this option\&.
1.1 misho 1306: .RE
1307: .PP
1.1.1.2 ! misho 1308: \fBSee also\fP
1.1 misho 1309: .RS 4
1310: \fBcfg_getsec\fP
1311: .RE
1312: .PP
1313:
1314: .SS "DLLIMPORT int __export cfg_include (\fBcfg_t\fP * cfg, \fBcfg_opt_t\fP * opt, int argc, const char ** argv)"
1.1.1.2 ! misho 1315:
1.1 misho 1316: .PP
1.1.1.2 ! misho 1317: 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)
1.1 misho 1318: .PP
1.1.1.2 ! misho 1319: \fBExamples\fP
1.1 misho 1320: .in +1c
1.1.1.2 ! misho 1321: \fBftpconf\&.c\fP\&.
1.1 misho 1322: .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_init (\fBcfg_opt_t\fP * opts, cfg_flag_t flags)"
1.1.1.2 ! misho 1323:
! 1324: .PP
! 1325: 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\&.
1.1 misho 1326: .PP
1.1.1.2 ! misho 1327: The options must no longer be defined in the same scope as where the cfg_xxx functions are used (since version 2\&.3)\&.
1.1 misho 1328: .PP
1.1.1.2 ! misho 1329: 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\&.
! 1330: .PP
! 1331: Call setlocale() before calling this function to localize handling of types, LC_CTYPE, and messages, LC_MESSAGES, since version 2\&.9:
! 1332: .PP
! 1333: .nf
! 1334:
! 1335: setlocale(LC_MESSAGES, '');
! 1336: setlocale(LC_CTYPE, '');
! 1337: .fi
1.1 misho 1338: .PP
1.1.1.2 ! misho 1339:
1.1 misho 1340: .PP
1.1.1.2 ! misho 1341: \fBParameters\fP
1.1 misho 1342: .RS 4
1343: \fIopts\fP An arrary of options
1344: .br
1.1.1.2 ! misho 1345: \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\&.
1.1 misho 1346: .RE
1347: .PP
1.1.1.2 ! misho 1348: \fBReturns\fP
1.1 misho 1349: .RS 4
1.1.1.2 ! misho 1350: A configuration context structure\&. This pointer is passed to almost all other functions as the first parameter\&.
1.1 misho 1351: .RE
1352: .PP
1353:
1354: .PP
1.1.1.2 ! misho 1355: \fBExamples\fP
1.1 misho 1356: .in +1c
1.1.1.2 ! misho 1357: \fBftpconf\&.c\fP, \fBreread\&.c\fP, and \fBsimple\&.c\fP\&.
! 1358: .SS "const DLLIMPORT char* __export cfg_name (\fBcfg_t\fP * cfg)"
! 1359:
1.1 misho 1360: .PP
1.1.1.2 ! misho 1361: Return the name of a section\&.
1.1 misho 1362: .PP
1.1.1.2 ! misho 1363: \fBParameters\fP
1.1 misho 1364: .RS 4
1.1.1.2 ! misho 1365: \fIcfg\fP The configuration file context\&.
1.1 misho 1366: .RE
1367: .PP
1.1.1.2 ! misho 1368: \fBReturns\fP
1.1 misho 1369: .RS 4
1.1.1.2 ! misho 1370: Returns the title, or 0 if there is no title\&. This string should not be modified\&.
1.1 misho 1371: .RE
1372: .PP
1373:
1374: .PP
1.1.1.2 ! misho 1375: \fBExamples\fP
1.1 misho 1376: .in +1c
1.1.1.2 ! misho 1377: \fBftpconf\&.c\fP\&.
! 1378: .SS "DLLIMPORT unsigned int __export cfg_num (\fBcfg_t\fP * cfg)"
! 1379:
! 1380: .PP
! 1381: Return number of options in a file or section\&.
! 1382: .PP
! 1383: \fBParameters\fP
! 1384: .RS 4
! 1385: \fIcfg\fP The configuration file or section context
! 1386: .RE
! 1387: .PP
! 1388: When a file has been parsed this function returns the number of options/settings the file, or a sub-section, has\&.
! 1389: .PP
! 1390: \fBReturns\fP
! 1391: .RS 4
! 1392: Number of options in a config file or section\&.
! 1393: .RE
! 1394: .PP
! 1395:
! 1396: .SS "DLLIMPORT char* __export cfg_opt_getcomment (\fBcfg_opt_t\fP * opt)"
! 1397:
! 1398: .PP
! 1399: Returns the option comment\&.
! 1400: .PP
! 1401: \fBParameters\fP
! 1402: .RS 4
! 1403: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
! 1404: .RE
! 1405: .PP
! 1406: \fBSee also\fP
! 1407: .RS 4
! 1408: \fBcfg_getcomment\fP
! 1409: .RE
1.1 misho 1410: .PP
1.1.1.2 ! misho 1411:
1.1 misho 1412: .SS "DLLIMPORT \fBcfg_bool_t\fP __export cfg_opt_getnbool (\fBcfg_opt_t\fP * opt, unsigned int index)"
1.1.1.2 ! misho 1413:
1.1 misho 1414: .PP
1.1.1.2 ! misho 1415: Returns the value of a boolean option, given a \fBcfg_opt_t\fP pointer\&.
1.1 misho 1416: .PP
1.1.1.2 ! misho 1417: \fBParameters\fP
1.1 misho 1418: .RS 4
1419: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1420: .br
1.1.1.2 ! misho 1421: \fIindex\fP Index of the value to get\&. Zero based\&.
1.1 misho 1422: .RE
1423: .PP
1.1.1.2 ! misho 1424: \fBSee also\fP
1.1 misho 1425: .RS 4
1426: \fBcfg_getnbool\fP
1427: .RE
1428: .PP
1429:
1430: .SS "DLLIMPORT double __export cfg_opt_getnfloat (\fBcfg_opt_t\fP * opt, unsigned int index)"
1.1.1.2 ! misho 1431:
1.1 misho 1432: .PP
1.1.1.2 ! misho 1433: Returns the value of a floating point option, given a \fBcfg_opt_t\fP pointer\&.
1.1 misho 1434: .PP
1.1.1.2 ! misho 1435: \fBParameters\fP
1.1 misho 1436: .RS 4
1437: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1438: .br
1.1.1.2 ! misho 1439: \fIindex\fP Index of the value to get\&. Zero based\&.
1.1 misho 1440: .RE
1441: .PP
1.1.1.2 ! misho 1442: \fBSee also\fP
1.1 misho 1443: .RS 4
1444: \fBcfg_getnfloat\fP
1445: .RE
1446: .PP
1447:
1448: .SS "DLLIMPORT signed long __export cfg_opt_getnint (\fBcfg_opt_t\fP * opt, unsigned int index)"
1.1.1.2 ! misho 1449:
1.1 misho 1450: .PP
1.1.1.2 ! misho 1451: Returns the value of an integer option, given a \fBcfg_opt_t\fP pointer\&.
1.1 misho 1452: .PP
1.1.1.2 ! misho 1453: \fBParameters\fP
1.1 misho 1454: .RS 4
1455: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1456: .br
1.1.1.2 ! misho 1457: \fIindex\fP Index of the value to get\&. Zero based\&.
1.1 misho 1458: .RE
1459: .PP
1.1.1.2 ! misho 1460: \fBSee also\fP
1.1 misho 1461: .RS 4
1462: \fBcfg_getnint\fP
1463: .RE
1464: .PP
1465:
1466: .PP
1.1.1.2 ! misho 1467: \fBExamples\fP
1.1 misho 1468: .in +1c
1.1.1.2 ! misho 1469: \fBftpconf\&.c\fP\&.
1.1 misho 1470: .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_opt_getnsec (\fBcfg_opt_t\fP * opt, unsigned int index)"
1.1.1.2 ! misho 1471:
1.1 misho 1472: .PP
1.1.1.2 ! misho 1473: Returns the value of a section option, given a \fBcfg_opt_t\fP pointer\&.
1.1 misho 1474: .PP
1.1.1.2 ! misho 1475: \fBParameters\fP
1.1 misho 1476: .RS 4
1477: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1478: .br
1.1.1.2 ! misho 1479: \fIindex\fP Index of the value to get\&. Zero based\&.
1.1 misho 1480: .RE
1481: .PP
1.1.1.2 ! misho 1482: \fBSee also\fP
1.1 misho 1483: .RS 4
1484: \fBcfg_getnsec\fP
1485: .RE
1486: .PP
1487:
1488: .PP
1.1.1.2 ! misho 1489: \fBExamples\fP
1.1 misho 1490: .in +1c
1.1.1.2 ! misho 1491: \fBftpconf\&.c\fP\&.
1.1 misho 1492: .SS "DLLIMPORT char* __export cfg_opt_getnstr (\fBcfg_opt_t\fP * opt, unsigned int index)"
1.1.1.2 ! misho 1493:
1.1 misho 1494: .PP
1.1.1.2 ! misho 1495: Returns the value of a string option, given a \fBcfg_opt_t\fP pointer\&.
1.1 misho 1496: .PP
1.1.1.2 ! misho 1497: \fBParameters\fP
1.1 misho 1498: .RS 4
1499: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1500: .br
1.1.1.2 ! misho 1501: \fIindex\fP Index of the value to get\&. Zero based\&.
1.1 misho 1502: .RE
1503: .PP
1.1.1.2 ! misho 1504: \fBSee also\fP
1.1 misho 1505: .RS 4
1506: \fBcfg_getnstr\fP
1507: .RE
1508: .PP
1509:
1.1.1.2 ! misho 1510: .SS "const DLLIMPORT char* cfg_opt_getstr (\fBcfg_opt_t\fP * opt)"
! 1511:
! 1512: .PP
! 1513: Return the string value of a key=value pair\&.
1.1 misho 1514: .PP
1.1.1.2 ! misho 1515: \fBParameters\fP
! 1516: .RS 4
! 1517: \fIopt\fP The option structure (eg, as returned from \fBcfg_getnopt()\fP)
! 1518: .RE
! 1519: .PP
! 1520: \fBSee also\fP
! 1521: .RS 4
! 1522: \fBcfg_opt_name\fP
! 1523: .RE
! 1524: .PP
! 1525: \fBReturns\fP
! 1526: .RS 4
! 1527: The string value for the option, or NULL if it's not a string\&. This string must not be modified!
! 1528: .RE
! 1529: .PP
! 1530:
1.1 misho 1531: .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_opt_gettsec (\fBcfg_opt_t\fP * opt, const char * title)"
1.1.1.2 ! misho 1532:
1.1 misho 1533: .PP
1.1.1.2 ! misho 1534: Returns the value of a section option, given a \fBcfg_opt_t\fP pointer and the title\&.
1.1 misho 1535: .PP
1.1.1.2 ! misho 1536: \fBParameters\fP
1.1 misho 1537: .RS 4
1538: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1539: .br
1.1.1.2 ! misho 1540: \fItitle\fP The title of this section\&. The CFGF_TITLE flag must have been set for this option\&.
1.1 misho 1541: .RE
1542: .PP
1.1.1.2 ! misho 1543: \fBSee also\fP
1.1 misho 1544: .RS 4
1545: \fBcfg_gettsec\fP
1546: .RE
1547: .PP
1548:
1.1.1.2 ! misho 1549: .SS "const DLLIMPORT char* __export cfg_opt_name (\fBcfg_opt_t\fP * opt)"
! 1550:
1.1 misho 1551: .PP
1.1.1.2 ! misho 1552: Return the name of an option\&.
1.1 misho 1553: .PP
1.1.1.2 ! misho 1554: \fBParameters\fP
1.1 misho 1555: .RS 4
1556: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1557: .RE
1558: .PP
1.1.1.2 ! misho 1559: \fBReturns\fP
1.1 misho 1560: .RS 4
1.1.1.2 ! misho 1561: Returns the title, or 0 if there is no title\&. This string should not be modified\&.
1.1 misho 1562: .RE
1563: .PP
1564:
1565: .PP
1.1.1.2 ! misho 1566: \fBExamples\fP
1.1 misho 1567: .in +1c
1.1.1.2 ! misho 1568: \fBftpconf\&.c\fP\&.
! 1569: .SS "DLLIMPORT int __export cfg_opt_nprint_var (\fBcfg_opt_t\fP * opt, unsigned int index, FILE * fp)"
! 1570:
1.1 misho 1571: .PP
1.1.1.2 ! misho 1572: 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
! 1573: = value'), or cfg_print to print the whole config file\&.
1.1 misho 1574: .PP
1.1.1.2 ! misho 1575: \fBParameters\fP
1.1 misho 1576: .RS 4
1577: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1578: .br
1579: \fIindex\fP The index in the option value array that should be printed
1580: .br
1.1.1.2 ! misho 1581: \fIfp\fP File stream to print to\&.
! 1582: .RE
! 1583: .PP
! 1584: \fBSee also\fP
! 1585: .RS 4
! 1586: \fBcfg_print\fP, \fBcfg_opt_print\fP
! 1587: .RE
! 1588: .PP
! 1589: \fBReturns\fP
! 1590: .RS 4
! 1591: POSIX OK(0), or non-zero on failure\&.
! 1592: .RE
! 1593: .PP
! 1594:
! 1595: .SS "DLLIMPORT int __export cfg_opt_print (\fBcfg_opt_t\fP * opt, FILE * fp)"
! 1596:
! 1597: .PP
! 1598: 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\&.
! 1599: .PP
! 1600: \fBParameters\fP
! 1601: .RS 4
! 1602: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
! 1603: .br
! 1604: \fIfp\fP File stream to print to\&.
1.1 misho 1605: .RE
1606: .PP
1.1.1.2 ! misho 1607: \fBSee also\fP
1.1 misho 1608: .RS 4
1.1.1.2 ! misho 1609: \fBcfg_print_func_t\fP
1.1 misho 1610: .RE
1611: .PP
1.1.1.2 ! misho 1612: \fBReturns\fP
! 1613: .RS 4
! 1614: POSIX OK(0), or non-zero on failure\&.
! 1615: .RE
! 1616: .PP
! 1617:
! 1618: .SS "DLLIMPORT int __export cfg_opt_print_indent (\fBcfg_opt_t\fP * opt, FILE * fp, int indent)"
1.1 misho 1619:
1620: .PP
1.1.1.2 ! misho 1621: Print an option and its value to a file\&. Same as cfg_opt_print, but with the indentation level specified\&.
1.1 misho 1622: .PP
1.1.1.2 ! misho 1623: \fBSee also\fP
! 1624: .RS 4
! 1625: \fBcfg_opt_print\fP
! 1626: .RE
! 1627: .PP
! 1628: \fBReturns\fP
! 1629: .RS 4
! 1630: POSIX OK(0), or non-zero on failure\&.
! 1631: .RE
! 1632: .PP
! 1633:
! 1634: .SS "DLLIMPORT int __export cfg_opt_rmnsec (\fBcfg_opt_t\fP * opt, unsigned int index)"
! 1635:
1.1 misho 1636: .PP
1.1.1.2 ! misho 1637: Removes and frees a config section, given a \fBcfg_opt_t\fP pointer\&.
1.1 misho 1638: .PP
1.1.1.2 ! misho 1639: \fBParameters\fP
1.1 misho 1640: .RS 4
1641: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1642: .br
1.1.1.2 ! misho 1643: \fIindex\fP Index of the section to remove\&. Zero based\&.
1.1 misho 1644: .RE
1645: .PP
1.1.1.2 ! misho 1646: \fBSee also\fP
1.1 misho 1647: .RS 4
1.1.1.2 ! misho 1648: \fBcfg_rmnsec\fP
! 1649: .RE
! 1650: .PP
! 1651: \fBReturns\fP
! 1652: .RS 4
! 1653: POSIX OK(0), or non-zero on failure\&.
1.1 misho 1654: .RE
1655: .PP
1656:
1.1.1.2 ! misho 1657: .SS "DLLIMPORT int __export cfg_opt_rmtsec (\fBcfg_opt_t\fP * opt, const char * title)"
! 1658:
! 1659: .PP
! 1660: Removes and frees a config section, given a \fBcfg_opt_t\fP pointer and the title\&.
1.1 misho 1661: .PP
1.1.1.2 ! misho 1662: \fBParameters\fP
! 1663: .RS 4
! 1664: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
! 1665: .br
! 1666: \fItitle\fP The title of this section\&. The CFGF_TITLE flag must have been set for this option\&.
! 1667: .RE
1.1 misho 1668: .PP
1.1.1.2 ! misho 1669: \fBSee also\fP
! 1670: .RS 4
! 1671: \fBcfg_rmtsec\fP
! 1672: .RE
1.1 misho 1673: .PP
1.1.1.2 ! misho 1674: \fBReturns\fP
1.1 misho 1675: .RS 4
1.1.1.2 ! misho 1676: POSIX OK(0), or non-zero on failure\&.
1.1 misho 1677: .RE
1678: .PP
1679:
1680: .SS "DLLIMPORT \fBcfg_print_func_t\fP __export cfg_opt_set_print_func (\fBcfg_opt_t\fP * opt, \fBcfg_print_func_t\fP pf)"
1.1.1.2 ! misho 1681:
1.1 misho 1682: .PP
1.1.1.2 ! misho 1683: Set a print callback function for an option\&.
1.1 misho 1684: .PP
1.1.1.2 ! misho 1685: \fBParameters\fP
1.1 misho 1686: .RS 4
1687: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1688: .br
1.1.1.2 ! misho 1689: \fIpf\fP The print function callback\&.
1.1 misho 1690: .RE
1691: .PP
1.1.1.2 ! misho 1692: \fBSee also\fP
1.1 misho 1693: .RS 4
1694: \fBcfg_print_func_t\fP
1695: .RE
1696: .PP
1697:
1.1.1.2 ! misho 1698: .SS "DLLIMPORT int __export cfg_opt_setcomment (\fBcfg_opt_t\fP * opt, char * comment)"
! 1699:
1.1 misho 1700: .PP
1.1.1.2 ! misho 1701: Annotate an option\&.
1.1 misho 1702: .PP
1.1.1.2 ! misho 1703: \fBParameters\fP
1.1 misho 1704: .RS 4
1705: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1706: .br
1.1.1.2 ! misho 1707: \fIcomment\fP The annotation
! 1708: .RE
! 1709: .PP
! 1710: \fBSee also\fP
! 1711: .RS 4
! 1712: \fBcfg_setcomment\fP
1.1 misho 1713: .RE
1714: .PP
1.1.1.2 ! misho 1715: \fBReturns\fP
! 1716: .RS 4
! 1717: POSIX OK(0), or non-zero on failure\&.
! 1718: .RE
! 1719: .PP
! 1720:
! 1721: .SS "DLLIMPORT int cfg_opt_setmulti (\fBcfg_t\fP * cfg, \fBcfg_opt_t\fP * opt, unsigned int nvalues, char ** values)"
1.1 misho 1722:
1723: .PP
1.1.1.2 ! misho 1724: Set an option (create an instance of an option)\&.
1.1 misho 1725: .PP
1.1.1.2 ! misho 1726: \fBParameters\fP
! 1727: .RS 4
! 1728: \fIcfg\fP The configuration file context\&.
! 1729: .br
! 1730: \fIopt\fP The option definition\&.
! 1731: .br
! 1732: \fInvalues\fP The number of values to set for the option\&.
! 1733: .br
! 1734: \fIvalues\fP The value(s) for the option\&.
! 1735: .RE
! 1736: .PP
! 1737: \fBReturns\fP
! 1738: .RS 4
! 1739: POSIX OK(0), or non-zero on failure\&.
! 1740: .RE
1.1 misho 1741: .PP
1.1.1.2 ! misho 1742:
! 1743: .SS "DLLIMPORT int __export cfg_opt_setnbool (\fBcfg_opt_t\fP * opt, \fBcfg_bool_t\fP value, unsigned int index)"
! 1744:
! 1745: .PP
! 1746: Set a value of a boolean option\&.
! 1747: .PP
! 1748: \fBParameters\fP
1.1 misho 1749: .RS 4
1750: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1751: .br
1.1.1.2 ! misho 1752: \fIvalue\fP The value to set\&.
1.1 misho 1753: .br
1.1.1.2 ! misho 1754: \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\&.
1.1 misho 1755: .RE
1756: .PP
1.1.1.2 ! misho 1757: \fBReturns\fP
! 1758: .RS 4
! 1759: POSIX OK(0), or non-zero on failure\&.
! 1760: .RE
1.1 misho 1761: .PP
1.1.1.2 ! misho 1762:
! 1763: .SS "DLLIMPORT int __export cfg_opt_setnfloat (\fBcfg_opt_t\fP * opt, double value, unsigned int index)"
! 1764:
1.1 misho 1765: .PP
1.1.1.2 ! misho 1766: Set a value of a floating point option\&.
1.1 misho 1767: .PP
1.1.1.2 ! misho 1768: \fBParameters\fP
1.1 misho 1769: .RS 4
1770: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1771: .br
1.1.1.2 ! misho 1772: \fIvalue\fP The value to set\&.
1.1 misho 1773: .br
1.1.1.2 ! misho 1774: \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\&.
1.1 misho 1775: .RE
1776: .PP
1.1.1.2 ! misho 1777: \fBReturns\fP
! 1778: .RS 4
! 1779: POSIX OK(0), or non-zero on failure\&.
! 1780: .RE
1.1 misho 1781: .PP
1.1.1.2 ! misho 1782:
! 1783: .SS "DLLIMPORT int __export cfg_opt_setnint (\fBcfg_opt_t\fP * opt, long int value, unsigned int index)"
! 1784:
1.1 misho 1785: .PP
1.1.1.2 ! misho 1786: Set a value of an integer option\&.
1.1 misho 1787: .PP
1.1.1.2 ! misho 1788: \fBParameters\fP
1.1 misho 1789: .RS 4
1790: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1791: .br
1.1.1.2 ! misho 1792: \fIvalue\fP The value to set\&.
1.1 misho 1793: .br
1.1.1.2 ! misho 1794: \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\&.
! 1795: .RE
! 1796: .PP
! 1797: \fBReturns\fP
! 1798: .RS 4
! 1799: POSIX OK(0), or non-zero on failure\&.
1.1 misho 1800: .RE
1801: .PP
1802:
1.1.1.2 ! misho 1803: .SS "DLLIMPORT int __export cfg_opt_setnstr (\fBcfg_opt_t\fP * opt, const char * value, unsigned int index)"
! 1804:
1.1 misho 1805: .PP
1.1.1.2 ! misho 1806: Set a value of a string option\&.
! 1807: .PP
! 1808: \fBParameters\fP
! 1809: .RS 4
! 1810: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
! 1811: .br
! 1812: \fIvalue\fP The value to set\&. Memory for the string is allocated and the value is copied\&. Any previous string value is freed\&.
! 1813: .br
! 1814: \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\&.
! 1815: .RE
! 1816: .PP
! 1817: \fBReturns\fP
! 1818: .RS 4
! 1819: POSIX OK(0), or non-zero on failure\&.
! 1820: .RE
1.1 misho 1821: .PP
1.1.1.2 ! misho 1822:
! 1823: .SS "DLLIMPORT unsigned int __export cfg_opt_size (\fBcfg_opt_t\fP * opt)"
! 1824:
1.1 misho 1825: .PP
1.1.1.2 ! misho 1826: 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)\&.
1.1 misho 1827: .PP
1.1.1.2 ! misho 1828: \fBParameters\fP
1.1 misho 1829: .RS 4
1830: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1831: .RE
1832: .PP
1833:
1834: .PP
1.1.1.2 ! misho 1835: \fBExamples\fP
1.1 misho 1836: .in +1c
1.1.1.2 ! misho 1837: \fBftpconf\&.c\fP\&.
1.1 misho 1838: .SS "DLLIMPORT int __export cfg_parse (\fBcfg_t\fP * cfg, const char * filename)"
1.1.1.2 ! misho 1839:
1.1 misho 1840: .PP
1.1.1.2 ! misho 1841: 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\&.
1.1 misho 1842: .PP
1.1.1.2 ! misho 1843: \fBParameters\fP
1.1 misho 1844: .RS 4
1.1.1.2 ! misho 1845: \fIcfg\fP The configuration file context as returned from \fBcfg_init()\fP\&.
1.1 misho 1846: .br
1.1.1.2 ! misho 1847: \fIfilename\fP The name of the file to parse\&.
1.1 misho 1848: .RE
1849: .PP
1.1.1.2 ! misho 1850: \fBReturns\fP
1.1 misho 1851: .RS 4
1.1.1.2 ! misho 1852: 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\&.
1.1 misho 1853: .RE
1854: .PP
1855:
1856: .PP
1.1.1.2 ! misho 1857: \fBExamples\fP
1.1 misho 1858: .in +1c
1.1.1.2 ! misho 1859: \fBftpconf\&.c\fP, \fBreread\&.c\fP, and \fBsimple\&.c\fP\&.
1.1 misho 1860: .SS "DLLIMPORT int __export cfg_parse_boolean (const char * s)"
1.1.1.2 ! misho 1861:
1.1 misho 1862: .PP
1.1.1.2 ! misho 1863: Parse a boolean option string\&. Accepted 'true' values are 'true', 'on' and 'yes', and accepted 'false' values are 'false', 'off' and 'no'\&.
1.1 misho 1864: .PP
1.1.1.2 ! misho 1865: \fBReturns\fP
1.1 misho 1866: .RS 4
1.1.1.2 ! misho 1867: Returns 1 or 0 (true/false) if the string was parsed correctly, or -1 if an error occurred\&.
1.1 misho 1868: .RE
1869: .PP
1870:
1871: .SS "DLLIMPORT int __export cfg_parse_buf (\fBcfg_t\fP * cfg, const char * buf)"
1.1.1.2 ! misho 1872:
1.1 misho 1873: .PP
1.1.1.2 ! misho 1874: Same as \fBcfg_parse()\fP above, but takes a character buffer as argument\&.
1.1 misho 1875: .PP
1.1.1.2 ! misho 1876: \fBParameters\fP
1.1 misho 1877: .RS 4
1.1.1.2 ! misho 1878: \fIcfg\fP The configuration file context as returned from \fBcfg_init()\fP\&.
1.1 misho 1879: .br
1.1.1.2 ! misho 1880: \fIbuf\fP A zero-terminated string with configuration directives\&.
1.1 misho 1881: .RE
1882: .PP
1.1.1.2 ! misho 1883: \fBSee also\fP
1.1 misho 1884: .RS 4
1.1.1.2 ! misho 1885: \fBcfg_parse()\fP
! 1886: .RE
! 1887: .PP
! 1888: \fBReturns\fP
! 1889: .RS 4
! 1890: POSIX OK(0), or non-zero on failure\&.
1.1 misho 1891: .RE
1892: .PP
1893:
1894: .PP
1.1.1.2 ! misho 1895: \fBExamples\fP
1.1 misho 1896: .in +1c
1.1.1.2 ! misho 1897: \fBreread\&.c\fP\&.
1.1 misho 1898: .SS "DLLIMPORT int __export cfg_parse_fp (\fBcfg_t\fP * cfg, FILE * fp)"
1.1.1.2 ! misho 1899:
! 1900: .PP
! 1901: 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\&.
! 1902: .PP
! 1903: \fBParameters\fP
! 1904: .RS 4
! 1905: \fIcfg\fP The configuration file context as returned from \fBcfg_init()\fP\&.
! 1906: .br
! 1907: \fIfp\fP An open file stream\&.
! 1908: .RE
1.1 misho 1909: .PP
1.1.1.2 ! misho 1910: \fBSee also\fP
! 1911: .RS 4
! 1912: \fBcfg_parse()\fP
! 1913: .RE
! 1914: .PP
! 1915: \fBReturns\fP
! 1916: .RS 4
! 1917: POSIX OK(0), or non-zero on failure\&.
! 1918: .RE
! 1919: .PP
! 1920:
! 1921: .SS "DLLIMPORT int __export cfg_print (\fBcfg_t\fP * cfg, FILE * fp)"
! 1922:
1.1 misho 1923: .PP
1.1.1.2 ! misho 1924: 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\&.
1.1 misho 1925: .PP
1.1.1.2 ! misho 1926: \fBParameters\fP
1.1 misho 1927: .RS 4
1.1.1.2 ! misho 1928: \fIcfg\fP The configuration file context\&.
1.1 misho 1929: .br
1.1.1.2 ! misho 1930: \fIfp\fP File stream to print to, use stdout to print to the screen\&.
! 1931: .RE
! 1932: .PP
! 1933: \fBSee also\fP
! 1934: .RS 4
! 1935: \fBcfg_print_func_t\fP, \fBcfg_set_print_func\fP
! 1936: .RE
! 1937: .PP
! 1938: \fBReturns\fP
! 1939: .RS 4
! 1940: POSIX OK(0), or non-zero on failure\&.
! 1941: .RE
! 1942: .PP
! 1943:
! 1944: .PP
! 1945: \fBExamples\fP
! 1946: .in +1c
! 1947: \fBsimple\&.c\fP\&.
! 1948: .SS "DLLIMPORT int __export cfg_print_indent (\fBcfg_t\fP * cfg, FILE * fp, int indent)"
! 1949:
! 1950: .PP
! 1951: Print the options and values to a file\&. Same as cfg_print, but with the indentation level specified\&.
! 1952: .PP
! 1953: \fBSee also\fP
! 1954: .RS 4
! 1955: \fBcfg_print\fP
1.1 misho 1956: .RE
1957: .PP
1.1.1.2 ! misho 1958: \fBReturns\fP
1.1 misho 1959: .RS 4
1.1.1.2 ! misho 1960: POSIX OK(0), or non-zero on failure\&.
1.1 misho 1961: .RE
1962: .PP
1963:
1.1.1.2 ! misho 1964: .SS "DLLIMPORT int __export cfg_rmnsec (\fBcfg_t\fP * cfg, const char * name, unsigned int index)"
! 1965:
! 1966: .PP
! 1967: Indexed version of \fBcfg_rmsec()\fP, used for CFGF_MULTI sections\&.
! 1968: .PP
! 1969: \fBParameters\fP
! 1970: .RS 4
! 1971: \fIcfg\fP The configuration file context\&.
! 1972: .br
! 1973: \fIname\fP The name of the section\&.
! 1974: .br
! 1975: \fIindex\fP Index of the section to remove\&. Zero based\&.
! 1976: .RE
! 1977: .PP
! 1978: \fBSee also\fP
! 1979: .RS 4
! 1980: \fBcfg_rmsec\fP
! 1981: .RE
1.1 misho 1982: .PP
1.1.1.2 ! misho 1983: \fBReturns\fP
! 1984: .RS 4
! 1985: POSIX OK(0), or non-zero on failure\&.
! 1986: .RE
1.1 misho 1987: .PP
1.1.1.2 ! misho 1988:
! 1989: .SS "DLLIMPORT int __export cfg_rmsec (\fBcfg_t\fP * cfg, const char * name)"
! 1990:
1.1 misho 1991: .PP
1.1.1.2 ! misho 1992: Removes and frees a config section\&. This is the same as calling cfg_rmnsec with index 0\&.
1.1 misho 1993: .PP
1.1.1.2 ! misho 1994: \fBParameters\fP
1.1 misho 1995: .RS 4
1.1.1.2 ! misho 1996: \fIcfg\fP The configuration file context\&.
1.1 misho 1997: .br
1.1.1.2 ! misho 1998: \fIname\fP The name of the section\&.
1.1 misho 1999: .RE
2000: .PP
1.1.1.2 ! misho 2001: \fBReturns\fP
1.1 misho 2002: .RS 4
1.1.1.2 ! misho 2003: POSIX OK(0), or non-zero on failure\&.
1.1 misho 2004: .RE
2005: .PP
2006:
1.1.1.2 ! misho 2007: .SS "DLLIMPORT int __export cfg_rmtsec (\fBcfg_t\fP * cfg, const char * name, const char * title)"
! 2008:
1.1 misho 2009: .PP
1.1.1.2 ! misho 2010: Removes and frees a section given the title, used for section with the CFGF_TITLE flag set\&.
1.1 misho 2011: .PP
1.1.1.2 ! misho 2012: \fBParameters\fP
! 2013: .RS 4
! 2014: \fIcfg\fP The configuration file context\&.
! 2015: .br
! 2016: \fIname\fP The name of the section\&.
! 2017: .br
! 2018: \fItitle\fP The title of this section\&. The CFGF_TITLE flag must have been set for this option\&.
! 2019: .RE
1.1 misho 2020: .PP
1.1.1.2 ! misho 2021: \fBSee also\fP
! 2022: .RS 4
! 2023: \fBcfg_rmsec\fP
! 2024: .RE
1.1 misho 2025: .PP
1.1.1.2 ! misho 2026: \fBReturns\fP
1.1 misho 2027: .RS 4
1.1.1.2 ! misho 2028: POSIX OK(0), or non-zero on failure\&.
1.1 misho 2029: .RE
2030: .PP
2031:
1.1.1.2 ! misho 2032: .SS "DLLIMPORT char* __export cfg_searchpath (cfg_searchpath_t * path, const char * file)"
! 2033:
! 2034: .PP
! 2035: 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\&.
1.1 misho 2036: .PP
1.1.1.2 ! misho 2037: \fBParameters\fP
! 2038: .RS 4
! 2039: \fIpath\fP The linked list of cfg_searchpath_t structs, each containg a directory to be searched
! 2040: .br
! 2041: \fIfile\fP The file for which to search
! 2042: .RE
! 2043: .PP
! 2044: \fBReturns\fP
! 2045: .RS 4
! 2046: If the file is found on the searchpath then the full path to the file is returned\&. If not found, NULL is returned\&.
! 2047: .RE
! 2048: .PP
! 2049:
1.1 misho 2050: .SS "DLLIMPORT \fBcfg_errfunc_t\fP __export cfg_set_error_function (\fBcfg_t\fP * cfg, \fBcfg_errfunc_t\fP errfunc)"
1.1.1.2 ! misho 2051:
1.1 misho 2052: .PP
1.1.1.2 ! misho 2053: Install a user-defined error reporting function\&.
1.1 misho 2054: .PP
1.1.1.2 ! misho 2055: \fBReturns\fP
1.1 misho 2056: .RS 4
1.1.1.2 ! misho 2057: The old error reporting function is returned\&.
1.1 misho 2058: .RE
2059: .PP
2060:
1.1.1.2 ! misho 2061: .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)"
! 2062:
! 2063: .PP
! 2064: 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\&.
! 2065: .PP
! 2066: \fBParameters\fP
! 2067: .RS 4
! 2068: \fIcfg\fP The configuration file context\&.
! 2069: .br
! 2070: \fIpff\fP The print filter callback function\&.
! 2071: .RE
! 2072: .PP
! 2073: \fBReturns\fP
! 2074: .RS 4
! 2075: The old print filter function is returned\&.
! 2076: .RE
! 2077: .PP
! 2078: \fBSee also\fP
! 2079: .RS 4
! 2080: \fBcfg_print_filter_func_t\fP
! 2081: .RE
1.1 misho 2082: .PP
1.1.1.2 ! misho 2083:
1.1 misho 2084: .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)"
1.1.1.2 ! misho 2085:
1.1 misho 2086: .PP
1.1.1.2 ! misho 2087: Set a print callback function for an option given its name\&.
1.1 misho 2088: .PP
1.1.1.2 ! misho 2089: \fBParameters\fP
1.1 misho 2090: .RS 4
1.1.1.2 ! misho 2091: \fIcfg\fP The configuration file context\&.
1.1 misho 2092: .br
1.1.1.2 ! misho 2093: \fIname\fP The name of the option\&.
1.1 misho 2094: .br
1.1.1.2 ! misho 2095: \fIpf\fP The print callback function\&.
1.1 misho 2096: .RE
2097: .PP
1.1.1.2 ! misho 2098: \fBSee also\fP
1.1 misho 2099: .RS 4
2100: \fBcfg_print_func_t\fP
2101: .RE
2102: .PP
2103:
2104: .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)"
1.1.1.2 ! misho 2105:
1.1 misho 2106: .PP
1.1.1.2 ! misho 2107: Register a validating callback function for an option\&.
1.1 misho 2108: .PP
1.1.1.2 ! misho 2109: \fBParameters\fP
1.1 misho 2110: .RS 4
1.1.1.2 ! misho 2111: \fIcfg\fP The configuration file context\&.
1.1 misho 2112: .br
1.1.1.2 ! misho 2113: \fIname\fP The name of the option\&.
1.1 misho 2114: .br
1.1.1.2 ! misho 2115: \fIvf\fP The validating callback function\&.
1.1 misho 2116: .RE
2117: .PP
1.1.1.2 ! misho 2118: \fBSee also\fP
1.1 misho 2119: .RS 4
2120: \fBcfg_validate_callback_t\fP
2121: .RE
2122: .PP
2123:
2124: .PP
1.1.1.2 ! misho 2125: \fBExamples\fP
1.1 misho 2126: .in +1c
1.1.1.2 ! misho 2127: \fBftpconf\&.c\fP\&.
! 2128: .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)"
! 2129:
! 2130: .PP
! 2131: 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\&.
! 2132: .PP
! 2133: \fBParameters\fP
! 2134: .RS 4
! 2135: \fIcfg\fP The configuration file context\&.
! 2136: .br
! 2137: \fIname\fP The name of the option\&.
! 2138: .br
! 2139: \fIvf\fP The validating callback function\&.
! 2140: .RE
! 2141: .PP
! 2142: \fBSee also\fP
! 2143: .RS 4
! 2144: \fBcfg_validate_callback2_t\fP
! 2145: .RE
1.1 misho 2146: .PP
1.1.1.2 ! misho 2147:
! 2148: .SS "DLLIMPORT int __export cfg_setbool (\fBcfg_t\fP * cfg, const char * name, \fBcfg_bool_t\fP value)"
! 2149:
1.1 misho 2150: .PP
1.1.1.2 ! misho 2151: Set the value of a boolean option given its name\&.
1.1 misho 2152: .PP
1.1.1.2 ! misho 2153: \fBParameters\fP
1.1 misho 2154: .RS 4
1.1.1.2 ! misho 2155: \fIcfg\fP The configuration file context\&.
1.1 misho 2156: .br
1.1.1.2 ! misho 2157: \fIname\fP The name of the option\&.
1.1 misho 2158: .br
1.1.1.2 ! misho 2159: \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\&.
1.1 misho 2160: .RE
2161: .PP
1.1.1.2 ! misho 2162: \fBReturns\fP
! 2163: .RS 4
! 2164: POSIX OK(0), or non-zero on failure\&.
! 2165: .RE
! 2166: .PP
! 2167:
! 2168: .SS "DLLIMPORT int __export cfg_setcomment (\fBcfg_t\fP * cfg, const char * name, char * comment)"
1.1 misho 2169:
2170: .PP
1.1.1.2 ! misho 2171: Annotate an option given its name\&. All options can be annotated as long as the CFGF_COMMENTS flag is given to \fBcfg_init()\fP\&.
1.1 misho 2172: .PP
1.1.1.2 ! misho 2173: When calling \fBcfg_print()\fP, annotations are saved as a C style one-liner comment before each option\&.
! 2174: .PP
! 2175: When calling \fBcfg_parse()\fP, only one-liner comments preceding an option are read and used to annotate the option\&.
! 2176: .PP
! 2177: \fBParameters\fP
1.1 misho 2178: .RS 4
1.1.1.2 ! misho 2179: \fIcfg\fP The configuration file context\&.
1.1 misho 2180: .br
1.1.1.2 ! misho 2181: \fIname\fP The name of the option\&.
1.1 misho 2182: .br
1.1.1.2 ! misho 2183: \fIcomment\fP The annotation
! 2184: .RE
! 2185: .PP
! 2186: \fBReturns\fP
! 2187: .RS 4
! 2188: POSIX OK(0), or non-zero on failure\&. This function will fail if memory for the new comment cannot be allocated\&.
1.1 misho 2189: .RE
2190: .PP
2191:
1.1.1.2 ! misho 2192: .SS "DLLIMPORT int __export cfg_setfloat (\fBcfg_t\fP * cfg, const char * name, double value)"
! 2193:
1.1 misho 2194: .PP
1.1.1.2 ! misho 2195: Set the value of a floating point option given its name\&.
1.1 misho 2196: .PP
1.1.1.2 ! misho 2197: \fBParameters\fP
1.1 misho 2198: .RS 4
1.1.1.2 ! misho 2199: \fIcfg\fP The configuration file context\&.
1.1 misho 2200: .br
1.1.1.2 ! misho 2201: \fIname\fP The name of the option\&.
1.1 misho 2202: .br
1.1.1.2 ! misho 2203: \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\&.
! 2204: .RE
! 2205: .PP
! 2206: \fBReturns\fP
! 2207: .RS 4
! 2208: POSIX OK(0), or non-zero on failure\&.
1.1 misho 2209: .RE
2210: .PP
2211:
1.1.1.2 ! misho 2212: .SS "DLLIMPORT int __export cfg_setint (\fBcfg_t\fP * cfg, const char * name, long int value)"
! 2213:
! 2214: .PP
! 2215: Set the value of an integer option given its name\&.
! 2216: .PP
! 2217: \fBParameters\fP
! 2218: .RS 4
! 2219: \fIcfg\fP The configuration file context\&.
! 2220: .br
! 2221: \fIname\fP The name of the option\&.
! 2222: .br
! 2223: \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\&.
! 2224: .RE
1.1 misho 2225: .PP
1.1.1.2 ! misho 2226: \fBReturns\fP
! 2227: .RS 4
! 2228: POSIX OK(0), or non-zero on failure\&.
! 2229: .RE
! 2230: .PP
! 2231:
! 2232: .SS "DLLIMPORT int __export cfg_setlist (\fBcfg_t\fP * cfg, const char * name, unsigned int nvalues, \&.\&.\&.)"
! 2233:
1.1 misho 2234: .PP
1.1.1.2 ! misho 2235: Set values for a list option\&. All existing values are replaced with the new ones\&.
1.1 misho 2236: .PP
1.1.1.2 ! misho 2237: \fBParameters\fP
1.1 misho 2238: .RS 4
1.1.1.2 ! misho 2239: \fIcfg\fP The configuration file context\&.
1.1 misho 2240: .br
1.1.1.2 ! misho 2241: \fIname\fP The name of the option\&.
1.1 misho 2242: .br
1.1.1.2 ! misho 2243: \fInvalues\fP Number of values to set\&.
1.1 misho 2244: .br
1.1.1.2 ! misho 2245: \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\&.
1.1 misho 2246: .RE
2247: .PP
1.1.1.2 ! misho 2248: \fBReturns\fP
! 2249: .RS 4
! 2250: POSIX OK(0), or non-zero on failure\&.
! 2251: .RE
1.1 misho 2252: .PP
1.1.1.2 ! misho 2253:
! 2254: .SS "DLLIMPORT int cfg_setmulti (\fBcfg_t\fP * cfg, const char * name, unsigned int nvalues, char ** values)"
! 2255:
1.1 misho 2256: .PP
1.1.1.2 ! misho 2257: Set an option (create an instance of an option)\&.
1.1 misho 2258: .PP
1.1.1.2 ! misho 2259: \fBParameters\fP
1.1 misho 2260: .RS 4
1.1.1.2 ! misho 2261: \fIcfg\fP The configuration file context\&.
1.1 misho 2262: .br
1.1.1.2 ! misho 2263: \fIname\fP The name of the option\&.
1.1 misho 2264: .br
1.1.1.2 ! misho 2265: \fInvalues\fP The number of values to set for the option\&.
1.1 misho 2266: .br
1.1.1.2 ! misho 2267: \fIvalues\fP The value(s) for the option\&.
! 2268: .RE
! 2269: .PP
! 2270: \fBReturns\fP
! 2271: .RS 4
! 2272: POSIX OK(0), or non-zero on failure\&.
1.1 misho 2273: .RE
2274: .PP
2275:
1.1.1.2 ! misho 2276: .SS "DLLIMPORT int __export cfg_setnbool (\fBcfg_t\fP * cfg, const char * name, \fBcfg_bool_t\fP value, unsigned int index)"
! 2277:
1.1 misho 2278: .PP
1.1.1.2 ! misho 2279: Set a value of a boolean option given its name and index\&.
1.1 misho 2280: .PP
1.1.1.2 ! misho 2281: \fBParameters\fP
1.1 misho 2282: .RS 4
1.1.1.2 ! misho 2283: \fIcfg\fP The configuration file context\&.
1.1 misho 2284: .br
1.1.1.2 ! misho 2285: \fIname\fP The name of the option\&.
1.1 misho 2286: .br
1.1.1.2 ! misho 2287: \fIvalue\fP The value to set\&.
1.1 misho 2288: .br
1.1.1.2 ! misho 2289: \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\&.
1.1 misho 2290: .RE
2291: .PP
1.1.1.2 ! misho 2292: \fBReturns\fP
! 2293: .RS 4
! 2294: POSIX OK(0), or non-zero on failure\&.
! 2295: .RE
! 2296: .PP
! 2297:
! 2298: .SS "DLLIMPORT int __export cfg_setnfloat (\fBcfg_t\fP * cfg, const char * name, double value, unsigned int index)"
1.1 misho 2299:
2300: .PP
1.1.1.2 ! misho 2301: Set a value of a floating point option given its name and index\&.
1.1 misho 2302: .PP
1.1.1.2 ! misho 2303: \fBParameters\fP
1.1 misho 2304: .RS 4
1.1.1.2 ! misho 2305: \fIcfg\fP The configuration file context\&.
1.1 misho 2306: .br
1.1.1.2 ! misho 2307: \fIname\fP The name of the option\&.
1.1 misho 2308: .br
1.1.1.2 ! misho 2309: \fIvalue\fP The value to set\&.
1.1 misho 2310: .br
1.1.1.2 ! misho 2311: \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\&.
! 2312: .RE
! 2313: .PP
! 2314: \fBReturns\fP
! 2315: .RS 4
! 2316: POSIX OK(0), or non-zero on failure\&.
1.1 misho 2317: .RE
2318: .PP
2319:
1.1.1.2 ! misho 2320: .SS "DLLIMPORT int __export cfg_setnint (\fBcfg_t\fP * cfg, const char * name, long int value, unsigned int index)"
! 2321:
1.1 misho 2322: .PP
1.1.1.2 ! misho 2323: Set a value of an integer option given its name and index\&.
1.1 misho 2324: .PP
1.1.1.2 ! misho 2325: \fBParameters\fP
1.1 misho 2326: .RS 4
1.1.1.2 ! misho 2327: \fIcfg\fP The configuration file context\&.
1.1 misho 2328: .br
1.1.1.2 ! misho 2329: \fIname\fP The name of the option\&.
1.1 misho 2330: .br
1.1.1.2 ! misho 2331: \fIvalue\fP The value to set\&.
1.1 misho 2332: .br
1.1.1.2 ! misho 2333: \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\&.
! 2334: .RE
! 2335: .PP
! 2336: \fBReturns\fP
! 2337: .RS 4
! 2338: POSIX OK(0), or non-zero on failure\&.
1.1 misho 2339: .RE
2340: .PP
2341:
1.1.1.2 ! misho 2342: .SS "DLLIMPORT int __export cfg_setnstr (\fBcfg_t\fP * cfg, const char * name, const char * value, unsigned int index)"
! 2343:
1.1 misho 2344: .PP
1.1.1.2 ! misho 2345: Set a value of a boolean option given its name and index\&.
1.1 misho 2346: .PP
1.1.1.2 ! misho 2347: \fBParameters\fP
1.1 misho 2348: .RS 4
1.1.1.2 ! misho 2349: \fIcfg\fP The configuration file context\&.
1.1 misho 2350: .br
1.1.1.2 ! misho 2351: \fIname\fP The name of the option\&.
1.1 misho 2352: .br
1.1.1.2 ! misho 2353: \fIvalue\fP The value to set\&. Memory for the string is allocated and the value is copied\&. Any privious string value is freed\&.
! 2354: .br
! 2355: \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\&.
1.1 misho 2356: .RE
2357: .PP
1.1.1.2 ! misho 2358: \fBReturns\fP
1.1 misho 2359: .RS 4
1.1.1.2 ! misho 2360: POSIX OK(0), or non-zero on failure\&.
1.1 misho 2361: .RE
2362: .PP
2363:
1.1.1.2 ! misho 2364: .SS "DLLIMPORT \fBcfg_value_t\fP* cfg_setopt (\fBcfg_t\fP * cfg, \fBcfg_opt_t\fP * opt, const char * value)"
! 2365:
1.1 misho 2366: .PP
1.1.1.2 ! misho 2367: Set an option (create an instance of an option)\&.
1.1 misho 2368: .PP
1.1.1.2 ! misho 2369: \fBParameters\fP
! 2370: .RS 4
! 2371: \fIcfg\fP The configuration file context\&.
! 2372: .br
! 2373: \fIopt\fP The option definition\&.
! 2374: .br
! 2375: \fIvalue\fP The initial value for the option\&.
! 2376: .RE
1.1 misho 2377: .PP
1.1.1.2 ! misho 2378: \fBReturns\fP
1.1 misho 2379: .RS 4
1.1.1.2 ! misho 2380: Returns a pointer to the value object\&.
! 2381: .RE
! 2382: .PP
! 2383:
! 2384: .SS "DLLIMPORT int __export cfg_setstr (\fBcfg_t\fP * cfg, const char * name, const char * value)"
! 2385:
! 2386: .PP
! 2387: Set the value of a string option given its name\&.
! 2388: .PP
! 2389: \fBParameters\fP
! 2390: .RS 4
! 2391: \fIcfg\fP The configuration file context\&.
1.1 misho 2392: .br
1.1.1.2 ! misho 2393: \fIname\fP The name of the option\&.
1.1 misho 2394: .br
1.1.1.2 ! misho 2395: \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\&.
! 2396: .RE
! 2397: .PP
! 2398: \fBReturns\fP
! 2399: .RS 4
! 2400: POSIX OK(0), or non-zero on failure\&.
1.1 misho 2401: .RE
2402: .PP
2403:
2404: .PP
1.1.1.2 ! misho 2405: \fBExamples\fP
1.1 misho 2406: .in +1c
1.1.1.2 ! misho 2407: \fBsimple\&.c\fP\&.
1.1 misho 2408: .SS "DLLIMPORT unsigned int __export cfg_size (\fBcfg_t\fP * cfg, const char * name)"
1.1.1.2 ! misho 2409:
1.1 misho 2410: .PP
1.1.1.2 ! misho 2411: 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)\&.
1.1 misho 2412: .PP
1.1.1.2 ! misho 2413: 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\&.
1.1 misho 2414: .PP
1.1.1.2 ! misho 2415: \fBParameters\fP
1.1 misho 2416: .RS 4
1.1.1.2 ! misho 2417: \fIcfg\fP The configuration file context\&.
1.1 misho 2418: .br
1.1.1.2 ! misho 2419: \fIname\fP The name of the option\&.
1.1 misho 2420: .RE
2421: .PP
2422:
2423: .PP
1.1.1.2 ! misho 2424: \fBExamples\fP
1.1 misho 2425: .in +1c
1.1.1.2 ! misho 2426: \fBftpconf\&.c\fP, and \fBreread\&.c\fP\&.
1.1 misho 2427: .SS "DLLIMPORT char* __export cfg_tilde_expand (const char * filename)"
1.1.1.2 ! misho 2428:
1.1 misho 2429: .PP
1.1.1.2 ! misho 2430: Does tilde expansion (~ -> $HOME) on the filename\&.
1.1 misho 2431: .PP
1.1.1.2 ! misho 2432: \fBReturns\fP
1.1 misho 2433: .RS 4
1.1.1.2 ! misho 2434: 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\&.
1.1 misho 2435: .RE
2436: .PP
2437:
1.1.1.2 ! misho 2438: .SS "const DLLIMPORT char* __export cfg_title (\fBcfg_t\fP * cfg)"
! 2439:
1.1 misho 2440: .PP
1.1.1.2 ! misho 2441: Return the title of a section\&.
1.1 misho 2442: .PP
1.1.1.2 ! misho 2443: \fBParameters\fP
1.1 misho 2444: .RS 4
1.1.1.2 ! misho 2445: \fIcfg\fP The configuration file context\&.
1.1 misho 2446: .RE
2447: .PP
1.1.1.2 ! misho 2448: \fBReturns\fP
1.1 misho 2449: .RS 4
1.1.1.2 ! misho 2450: Returns the title, or 0 if there is no title\&. This string should not be modified\&.
1.1 misho 2451: .RE
2452: .PP
2453:
2454: .SH "Author"
2455: .PP
1.1.1.2 ! misho 2456: Generated automatically by Doxygen for confuse from the source code\&.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to confuse.h.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / confuse / doc / man / man3