1: .TH "confuse.h" 3 "Thu Jun 25 2020" "Version 3.3" "confuse" \" -*- nroff -*-
2: .ad l
3: .nh
4: .SH NAME
5: confuse.h \- A configuration file parser library\&.
6:
7: .SH SYNOPSIS
8: .br
9: .PP
10: \fC#include <stdio\&.h>\fP
11: .br
12: \fC#include <stdarg\&.h>\fP
13: .br
14:
15: .SS "Data Structures"
16:
17: .in +1c
18: .ti -1c
19: .RI "struct \fBcfg_t\fP"
20: .br
21: .RI "Data structure holding information about a 'section'\&. "
22: .ti -1c
23: .RI "union \fBcfg_value_t\fP"
24: .br
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_*\&. "
30: .ti -1c
31: .RI "struct \fBcfg_defvalue_t\fP"
32: .br
33: .RI "Data structure holding the default value given by the initialization macros\&. "
34: .ti -1c
35: .RI "struct \fBcfg_opt_t\fP"
36: .br
37: .RI "Data structure holding information about an option\&. "
38: .in -1c
39: .SS "Macros"
40:
41: .in +1c
42: .ti -1c
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)"
68: .br
69: .RI "multiple section titles must be unique (duplicates raises an error, only applies to sections) "
70: .ti -1c
71: .RI "#define \fBCFGF_IGNORE_UNKNOWN\fP (1 << 8)"
72: .br
73: .RI "ignore unknown options in configuration files "
74: .ti -1c
75: .RI "#define \fBCFGF_DEPRECATED\fP (1 << 9)"
76: .br
77: .RI "option is deprecated and should be ignored\&. "
78: .ti -1c
79: .RI "#define \fBCFGF_DROP\fP (1 << 10)"
80: .br
81: .RI "option should be dropped after parsing "
82: .ti -1c
83: .RI "#define \fBCFGF_COMMENTS\fP (1 << 11)"
84: .br
85: .RI "Enable option annotation/comments support\&. "
86: .ti -1c
87: .RI "#define \fBCFGF_MODIFIED\fP (1 << 12)"
88: .br
89: .RI "option has been changed from its default value "
90: .ti -1c
91: .RI "#define \fBCFGF_KEYSTRVAL\fP (1 << 13)"
92: .br
93: .RI "section has free-form key=value string options created when parsing file "
94: .ti -1c
95: .RI "#define \fBCFG_SUCCESS\fP 0"
96: .br
97: .RI "Return codes from \fBcfg_parse()\fP, \fBcfg_parse_boolean()\fP, and cfg_set*() functions\&. "
98: .ti -1c
99: .RI "#define \fBCFG_STR\fP(name, def, flags) __CFG_STR(name, def, flags, 0, 0)"
100: .br
101: .RI "Initialize a string option\&. "
102: .ti -1c
103: .RI "#define \fBCFG_STR_LIST\fP(name, def, flags) __CFG_STR_LIST(name, def, flags, 0, 0)"
104: .br
105: .RI "Initialize a string list option\&. "
106: .ti -1c
107: .RI "#define \fBCFG_STR_CB\fP(name, def, flags, cb) __CFG_STR(name, def, flags, 0, cb)"
108: .br
109: .RI "Initialize a string option with a value parsing callback\&. "
110: .ti -1c
111: .RI "#define \fBCFG_STR_LIST_CB\fP(name, def, flags, cb) __CFG_STR_LIST(name, def, flags, 0, cb)"
112: .br
113: .RI "Initialize a string list option with a value parsing callback\&. "
114: .ti -1c
115: .RI "#define \fBCFG_SIMPLE_STR\fP(name, svalue) __CFG_STR(name, 0, \fBCFGF_NONE\fP, svalue, 0)"
116: .br
117: .RI "Initialize a 'simple' string option\&. "
118: .ti -1c
119: .RI "#define \fBCFG_INT\fP(name, def, flags) __CFG_INT(name, def, flags, 0, 0)"
120: .br
121: .RI "Initialize an integer option\&. "
122: .ti -1c
123: .RI "#define \fBCFG_INT_LIST\fP(name, def, flags) __CFG_INT_LIST(name, def, flags, 0, 0)"
124: .br
125: .RI "Initialize an integer list option\&. "
126: .ti -1c
127: .RI "#define \fBCFG_INT_CB\fP(name, def, flags, cb) __CFG_INT(name, def, flags, 0, cb)"
128: .br
129: .RI "Initialize an integer option with a value parsing callback\&. "
130: .ti -1c
131: .RI "#define \fBCFG_INT_LIST_CB\fP(name, def, flags, cb) __CFG_INT_LIST(name, def, flags, 0, cb)"
132: .br
133: .RI "Initialize an integer list option with a value parsing callback\&. "
134: .ti -1c
135: .RI "#define \fBCFG_SIMPLE_INT\fP(name, svalue) __CFG_INT(name, 0, \fBCFGF_NONE\fP, svalue, 0)"
136: .br
137: .RI "Initialize a 'simple' integer option (see documentation for CFG_SIMPLE_STR for more information)\&. "
138: .ti -1c
139: .RI "#define \fBCFG_FLOAT\fP(name, def, flags) __CFG_FLOAT(name, def, flags, 0, 0)"
140: .br
141: .RI "Initialize a floating point option\&. "
142: .ti -1c
143: .RI "#define \fBCFG_FLOAT_LIST\fP(name, def, flags) __CFG_FLOAT_LIST(name, def, flags, 0, 0)"
144: .br
145: .RI "Initialize a floating point list option\&. "
146: .ti -1c
147: .RI "#define \fBCFG_FLOAT_CB\fP(name, def, flags, cb) __CFG_FLOAT(name, def, flags, 0, cb)"
148: .br
149: .RI "Initialize a floating point option with a value parsing callback\&. "
150: .ti -1c
151: .RI "#define \fBCFG_FLOAT_LIST_CB\fP(name, def, flags, cb) __CFG_FLOAT_LIST(name, def, flags, 0, cb)"
152: .br
153: .RI "Initialize a floating point list option with a value parsing callback\&. "
154: .ti -1c
155: .RI "#define \fBCFG_SIMPLE_FLOAT\fP(name, svalue) __CFG_FLOAT(name, 0, \fBCFGF_NONE\fP, svalue, 0)"
156: .br
157: .RI "Initialize a 'simple' floating point option (see documentation for CFG_SIMPLE_STR for more information)\&. "
158: .ti -1c
159: .RI "#define \fBCFG_BOOL\fP(name, def, flags) __CFG_BOOL(name, def, flags, 0, 0)"
160: .br
161: .RI "Initialize a boolean option\&. "
162: .ti -1c
163: .RI "#define \fBCFG_BOOL_LIST\fP(name, def, flags) __CFG_BOOL_LIST(name, def, flags, 0, 0)"
164: .br
165: .RI "Initialize a boolean list option\&. "
166: .ti -1c
167: .RI "#define \fBCFG_BOOL_CB\fP(name, def, flags, cb) __CFG_BOOL(name, def, flags, 0, cb)"
168: .br
169: .RI "Initialize a boolean option with a value parsing callback\&. "
170: .ti -1c
171: .RI "#define \fBCFG_BOOL_LIST_CB\fP(name, def, flags, cb) __CFG_BOOL_LIST(name, def, flags, 0, cb)"
172: .br
173: .RI "Initialize a boolean list option with a value parsing callback\&. "
174: .ti -1c
175: .RI "#define \fBCFG_SIMPLE_BOOL\fP(name, svalue) __CFG_BOOL(name, cfg_false, \fBCFGF_NONE\fP, svalue, 0)"
176: .br
177: .RI "Initialize a 'simple' boolean option (see documentation for CFG_SIMPLE_STR for more information)\&. "
178: .ti -1c
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}"
180: .br
181: .RI "Initialize a section\&. "
182: .ti -1c
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}"
184: .br
185: .RI "Initialize a function\&. "
186: .ti -1c
187: .RI "#define \fBCFG_PTR_CB\fP(name, def, flags, parsecb, freecb) __CFG_PTR(name, def, flags, 0, parsecb, freecb)"
188: .br
189: .RI "Initialize a user-defined option\&. "
190: .ti -1c
191: .RI "#define \fBCFG_PTR_LIST_CB\fP(name, def, flags, parsecb, freecb) __CFG_PTR(name, def, flags | \fBCFGF_LIST\fP, 0, parsecb, freecb)"
192: .br
193: .RI "Initialize a list of user-defined options\&. "
194: .ti -1c
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}"
196: .br
197: .RI "Terminate list of options\&. "
198: .in -1c
199: .SS "Typedefs"
200:
201: .in +1c
202: .ti -1c
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)"
212: .br
213: .RI "Value parsing callback prototype\&. "
214: .ti -1c
215: .RI "typedef int(* \fBcfg_validate_callback_t\fP) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt)"
216: .br
217: .RI "Validating callback prototype\&. "
218: .ti -1c
219: .RI "typedef int(* \fBcfg_validate_callback2_t\fP) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, void *value)"
220: .br
221: .RI "Validating callback2 prototype\&. "
222: .ti -1c
223: .RI "typedef void(* \fBcfg_free_func_t\fP) (void *value)"
224: .br
225: .RI "User-defined memory release function for CFG_PTR values\&. "
226: .ti -1c
227: .RI "typedef void(* \fBcfg_errfunc_t\fP) (\fBcfg_t\fP *cfg, const char *fmt, va_list ap)"
228: .br
229: .RI "Error reporting function\&. "
230: .ti -1c
231: .RI "typedef int(* \fBcfg_print_filter_func_t\fP) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt)"
232: .br
233: .RI "Print filter function\&. "
234: .in -1c
235: .SS "Enumerations"
236:
237: .in +1c
238: .ti -1c
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 }"
240: .br
241: .RI "Fundamental option types\&. "
242: .ti -1c
243: .RI "enum \fBcfg_bool_t\fP "
244: .br
245: .RI "Boolean values\&. "
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
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\&. "
262: .ti -1c
263: .RI "DLLIMPORT int __export \fBcfg_parse\fP (\fBcfg_t\fP *cfg, const char *filename)"
264: .br
265: .RI "Parse a configuration file\&. "
266: .ti -1c
267: .RI "DLLIMPORT int __export \fBcfg_parse_fp\fP (\fBcfg_t\fP *cfg, FILE *fp)"
268: .br
269: .RI "Same as \fBcfg_parse()\fP above, but takes an already opened file as argument\&. "
270: .ti -1c
271: .RI "DLLIMPORT int __export \fBcfg_parse_buf\fP (\fBcfg_t\fP *cfg, const char *buf)"
272: .br
273: .RI "Same as \fBcfg_parse()\fP above, but takes a character buffer as argument\&. "
274: .ti -1c
275: .RI "DLLIMPORT int __export \fBcfg_free_value\fP (\fBcfg_opt_t\fP *opt)"
276: .br
277: .RI "Free the memory allocated for the values of a given option\&. "
278: .ti -1c
279: .RI "DLLIMPORT int __export \fBcfg_free\fP (\fBcfg_t\fP *cfg)"
280: .br
281: .RI "Free a \fBcfg_t\fP context\&. "
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
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\&. "
294: .ti -1c
295: .RI "DLLIMPORT char *__export \fBcfg_getcomment\fP (\fBcfg_t\fP *cfg, const char *name)"
296: .br
297: .RI "Returns the option comment\&. "
298: .ti -1c
299: .RI "DLLIMPORT signed long __export \fBcfg_opt_getnint\fP (\fBcfg_opt_t\fP *opt, unsigned int index)"
300: .br
301: .RI "Returns the value of an integer option, given a \fBcfg_opt_t\fP pointer\&. "
302: .ti -1c
303: .RI "DLLIMPORT long int __export \fBcfg_getnint\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)"
304: .br
305: .RI "Indexed version of \fBcfg_getint()\fP, used for lists\&. "
306: .ti -1c
307: .RI "DLLIMPORT long int __export \fBcfg_getint\fP (\fBcfg_t\fP *cfg, const char *name)"
308: .br
309: .RI "Returns the value of an integer option\&. "
310: .ti -1c
311: .RI "DLLIMPORT double __export \fBcfg_opt_getnfloat\fP (\fBcfg_opt_t\fP *opt, unsigned int index)"
312: .br
313: .RI "Returns the value of a floating point option, given a \fBcfg_opt_t\fP pointer\&. "
314: .ti -1c
315: .RI "DLLIMPORT double __export \fBcfg_getnfloat\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)"
316: .br
317: .RI "Indexed version of \fBcfg_getfloat()\fP, used for lists\&. "
318: .ti -1c
319: .RI "DLLIMPORT double __export \fBcfg_getfloat\fP (\fBcfg_t\fP *cfg, const char *name)"
320: .br
321: .RI "Returns the value of a floating point option\&. "
322: .ti -1c
323: .RI "DLLIMPORT char *__export \fBcfg_opt_getnstr\fP (\fBcfg_opt_t\fP *opt, unsigned int index)"
324: .br
325: .RI "Returns the value of a string option, given a \fBcfg_opt_t\fP pointer\&. "
326: .ti -1c
327: .RI "DLLIMPORT char *__export \fBcfg_getnstr\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)"
328: .br
329: .RI "Indexed version of \fBcfg_getstr()\fP, used for lists\&. "
330: .ti -1c
331: .RI "DLLIMPORT char *__export \fBcfg_getstr\fP (\fBcfg_t\fP *cfg, const char *name)"
332: .br
333: .RI "Returns the value of a string option\&. "
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
337: .RI "Returns the value of a boolean option, given a \fBcfg_opt_t\fP pointer\&. "
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
341: .RI "Indexed version of \fBcfg_getbool()\fP, used for lists\&. "
342: .ti -1c
343: .RI "DLLIMPORT \fBcfg_bool_t\fP __export \fBcfg_getbool\fP (\fBcfg_t\fP *cfg, const char *name)"
344: .br
345: .RI "Returns the value of a boolean option\&. "
346: .ti -1c
347: .RI "DLLIMPORT void *__export \fBcfg_getptr\fP (\fBcfg_t\fP *cfg, const char *name)"
348: .br
349: .RI "Returns the value of a user-defined option (void pointer)\&. "
350: .ti -1c
351: .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_opt_getnsec\fP (\fBcfg_opt_t\fP *opt, unsigned int index)"
352: .br
353: .RI "Returns the value of a section option, given a \fBcfg_opt_t\fP pointer\&. "
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
357: .RI "Indexed version of \fBcfg_getsec()\fP, used for sections with the CFGF_MULTI flag set\&. "
358: .ti -1c
359: .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_opt_gettsec\fP (\fBcfg_opt_t\fP *opt, const char *title)"
360: .br
361: .RI "Returns the value of a section option, given a \fBcfg_opt_t\fP pointer and the title\&. "
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
365: .RI "Return a section given the title, used for section with the CFGF_TITLE flag set\&. "
366: .ti -1c
367: .RI "DLLIMPORT \fBcfg_t\fP *__export \fBcfg_getsec\fP (\fBcfg_t\fP *cfg, const char *name)"
368: .br
369: .RI "Returns the value of a section option\&. "
370: .ti -1c
371: .RI "DLLIMPORT unsigned int __export \fBcfg_opt_size\fP (\fBcfg_opt_t\fP *opt)"
372: .br
373: .RI "Return the number of values this option has\&. "
374: .ti -1c
375: .RI "DLLIMPORT unsigned int __export \fBcfg_size\fP (\fBcfg_t\fP *cfg, const char *name)"
376: .br
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\&. "
382: .ti -1c
383: .RI "const DLLIMPORT char *__export \fBcfg_name\fP (\fBcfg_t\fP *cfg)"
384: .br
385: .RI "Return the name of a section\&. "
386: .ti -1c
387: .RI "const DLLIMPORT char *__export \fBcfg_opt_name\fP (\fBcfg_opt_t\fP *opt)"
388: .br
389: .RI "Return the name of an option\&. "
390: .ti -1c
391: .RI "const DLLIMPORT char * \fBcfg_opt_getstr\fP (\fBcfg_opt_t\fP *opt)"
392: .br
393: .RI "Return the string value of a key=value pair\&. "
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
397: .RI "Predefined include-function\&. "
398: .ti -1c
399: .RI "DLLIMPORT char *__export \fBcfg_tilde_expand\fP (const char *filename)"
400: .br
401: .RI "Does tilde expansion (~ -> $HOME) on the filename\&. "
402: .ti -1c
403: .RI "DLLIMPORT int __export \fBcfg_parse_boolean\fP (const char *s)"
404: .br
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\&. "
410: .ti -1c
411: .RI "DLLIMPORT \fBcfg_opt_t\fP *__export \fBcfg_getopt\fP (\fBcfg_t\fP *cfg, const char *name)"
412: .br
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\&. "
458: .ti -1c
459: .RI "DLLIMPORT int __export \fBcfg_setnbool\fP (\fBcfg_t\fP *cfg, const char *name, \fBcfg_bool_t\fP value, unsigned int index)"
460: .br
461: .RI "Set a value of a boolean option given its name and index\&. "
462: .ti -1c
463: .RI "DLLIMPORT int __export \fBcfg_opt_setnstr\fP (\fBcfg_opt_t\fP *opt, const char *value, unsigned int index)"
464: .br
465: .RI "Set a value of a string option\&. "
466: .ti -1c
467: .RI "DLLIMPORT int __export \fBcfg_setstr\fP (\fBcfg_t\fP *cfg, const char *name, const char *value)"
468: .br
469: .RI "Set the value of a string option given its name\&. "
470: .ti -1c
471: .RI "DLLIMPORT int __export \fBcfg_setnstr\fP (\fBcfg_t\fP *cfg, const char *name, const char *value, unsigned int index)"
472: .br
473: .RI "Set a value of a boolean option given its name and index\&. "
474: .ti -1c
475: .RI "DLLIMPORT int __export \fBcfg_setlist\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int nvalues,\&.\&.\&.)"
476: .br
477: .RI "Set values for a list option\&. "
478: .ti -1c
479: .RI "DLLIMPORT unsigned int __export \fBcfg_num\fP (\fBcfg_t\fP *cfg)"
480: .br
481: .RI "Return number of options in a file or section\&. "
482: .ti -1c
483: .RI "DLLIMPORT int __export \fBcfg_addlist\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int nvalues,\&.\&.\&.)"
484: .br
485: .RI "Add values for a list option\&. "
486: .ti -1c
487: .RI "DLLIMPORT int \fBcfg_opt_setmulti\fP (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, unsigned int nvalues, char **values)"
488: .br
489: .RI "Set an option (create an instance of an option)\&. "
490: .ti -1c
491: .RI "DLLIMPORT int \fBcfg_setmulti\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int nvalues, char **values)"
492: .br
493: .RI "Set an option (create an instance of an option)\&. "
494: .ti -1c
495: .RI "DLLIMPORT \fBcfg_t\fP * \fBcfg_addtsec\fP (\fBcfg_t\fP *cfg, const char *name, const char *title)"
496: .br
497: .RI "Create a new titled config section\&. "
498: .ti -1c
499: .RI "DLLIMPORT int __export \fBcfg_opt_rmnsec\fP (\fBcfg_opt_t\fP *opt, unsigned int index)"
500: .br
501: .RI "Removes and frees a config section, given a \fBcfg_opt_t\fP pointer\&. "
502: .ti -1c
503: .RI "DLLIMPORT int __export \fBcfg_rmnsec\fP (\fBcfg_t\fP *cfg, const char *name, unsigned int index)"
504: .br
505: .RI "Indexed version of \fBcfg_rmsec()\fP, used for CFGF_MULTI sections\&. "
506: .ti -1c
507: .RI "DLLIMPORT int __export \fBcfg_rmsec\fP (\fBcfg_t\fP *cfg, const char *name)"
508: .br
509: .RI "Removes and frees a config section\&. "
510: .ti -1c
511: .RI "DLLIMPORT int __export \fBcfg_opt_rmtsec\fP (\fBcfg_opt_t\fP *opt, const char *title)"
512: .br
513: .RI "Removes and frees a config section, given a \fBcfg_opt_t\fP pointer and the title\&. "
514: .ti -1c
515: .RI "DLLIMPORT int __export \fBcfg_rmtsec\fP (\fBcfg_t\fP *cfg, const char *name, const char *title)"
516: .br
517: .RI "Removes and frees a section given the title, used for section with the CFGF_TITLE flag set\&. "
518: .ti -1c
519: .RI "DLLIMPORT int __export \fBcfg_opt_nprint_var\fP (\fBcfg_opt_t\fP *opt, unsigned int index, FILE *fp)"
520: .br
521: .RI "Default value print function\&. "
522: .ti -1c
523: .RI "DLLIMPORT int __export \fBcfg_opt_print_indent\fP (\fBcfg_opt_t\fP *opt, FILE *fp, int indent)"
524: .br
525: .RI "Print an option and its value to a file\&. "
526: .ti -1c
527: .RI "DLLIMPORT int __export \fBcfg_opt_print\fP (\fBcfg_opt_t\fP *opt, FILE *fp)"
528: .br
529: .RI "Print an option and its value to a file\&. "
530: .ti -1c
531: .RI "DLLIMPORT int __export \fBcfg_print_indent\fP (\fBcfg_t\fP *cfg, FILE *fp, int indent)"
532: .br
533: .RI "Print the options and values to a file\&. "
534: .ti -1c
535: .RI "DLLIMPORT int __export \fBcfg_print\fP (\fBcfg_t\fP *cfg, FILE *fp)"
536: .br
537: .RI "Print the options and values to a file\&. "
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
541: .RI "Set a print callback function for an option\&. "
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
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\&. "
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
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\&. "
558: .in -1c
559: .SH "Detailed Description"
560: .PP
561: A configuration file parser library\&.
562:
563:
564: .SH "Macro Definition Documentation"
565: .PP
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:
568: .PP
569: Terminate list of options\&. This must be the last initializer in the option list\&.
570: .PP
571: \fBExamples\fP
572: .in +1c
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:
576: .PP
577: Initialize a function\&.
578: .PP
579: \fBParameters\fP
580: .RS 4
581: \fIname\fP The name of the option
582: .br
583: \fIfunc\fP The callback function\&.
584: .RE
585: .PP
586: \fBSee also\fP
587: .RS 4
588: \fBcfg_func_t\fP
589: .RE
590: .PP
591:
592: .PP
593: \fBExamples\fP
594: .in +1c
595: \fBftpconf\&.c\fP\&.
596: .SS "#define CFG_PTR_CB(name, def, flags, parsecb, freecb) __CFG_PTR(name, def, flags, 0, parsecb, freecb)"
597:
598: .PP
599: Initialize a user-defined option\&. CFG_PTR options can only be used together with a value parsing callback\&.
600: .PP
601: \fBParameters\fP
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
614: \fBSee also\fP
615: .RS 4
616: \fBcfg_callback_t\fP, \fBcfg_free_func_t\fP
617: .RE
618: .PP
619:
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:
622: .PP
623: Initialize a section\&.
624: .PP
625: \fBParameters\fP
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
636: \fBExamples\fP
637: .in +1c
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:
641: .PP
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\&.
643: .PP
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:
649: .PP
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\&.
651: .PP
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\&.
653: .PP
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
657: .RS 4
658: \fIname\fP name of the option
659: .br
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
661: .PP
662: .nf
663:
664: char *user = 'joe';
665: \&.\&.\&.
666: \fBcfg_opt_t\fP opts[] = {
667: CFG_SIMPLE_STR('user', &user),
668: \&.\&.\&.
669: .fi
670: .PP
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:
672: .PP
673: .nf
674:
675: char *user = strdup('joe');
676: \&.\&.\&.
677: \fBcfg_opt_t\fP opts[] = {
678: CFG_SIMPLE_STR('user', &user),
679: \&.\&.\&.
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:
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);
694: .fi
695: .PP
696:
697: .RE
698: .PP
699:
700: .PP
701: \fBExamples\fP
702: .in +1c
703: \fBsimple\&.c\fP\&.
704: .SS "#define CFG_SUCCESS 0"
705:
706: .PP
707: Return codes from \fBcfg_parse()\fP, \fBcfg_parse_boolean()\fP, and cfg_set*() functions\&.
708: .PP
709: \fBExamples\fP
710: .in +1c
711: \fBftpconf\&.c\fP, and \fBreread\&.c\fP\&.
712: .SS "#define CFGF_DEPRECATED (1 << 9)"
713:
714: .PP
715: option is deprecated and should be ignored\&.
716: .SS "#define CFGF_NONE (0)"
717:
718: .PP
719: Flags\&.
720: .PP
721: \fBExamples\fP
722: .in +1c
723: \fBftpconf\&.c\fP, and \fBreread\&.c\fP\&.
724: .SH "Typedef Documentation"
725: .PP
726: .SS "typedef int(* cfg_callback_t) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt, const char *value, void *result)"
727:
728: .PP
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\&.
730: .PP
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\&.
732: .PP
733: \fBParameters\fP
734: .RS 4
735: \fIcfg\fP The configuration file context\&.
736: .br
737: \fIopt\fP The option\&.
738: .br
739: \fIvalue\fP The value found in the configuration file\&.
740: .br
741: \fIresult\fP Pointer to storage for the result, cast to a void pointer\&.
742: .RE
743: .PP
744: \fBReturns\fP
745: .RS 4
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\&.
747: .RE
748: .PP
749:
750: .SS "typedef void(* cfg_errfunc_t) (\fBcfg_t\fP *cfg, const char *fmt, va_list ap)"
751:
752: .PP
753: Error reporting function\&.
754: .SS "typedef void(* cfg_free_func_t) (void *value)"
755:
756: .PP
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:
760: .PP
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\&.
762: .PP
763: \fBParameters\fP
764: .RS 4
765: \fIcfg\fP The configuration file context\&.
766: .br
767: \fIopt\fP The option\&.
768: .br
769: \fIargc\fP Number of arguments passed\&. The callback function is responsible for checking that the correct number of arguments are passed\&.
770: .br
771: \fIargv\fP Arguments as an array of character strings\&.
772: .RE
773: .PP
774: \fBReturns\fP
775: .RS 4
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\&.
777: .RE
778: .PP
779: \fBSee also\fP
780: .RS 4
781: \fBCFG_FUNC\fP
782: .RE
783: .PP
784:
785: .SS "typedef int(* cfg_print_filter_func_t) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt)"
786:
787: .PP
788: Print filter function\&.
789: .PP
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
796: .PP
797: \fBReturns\fP
798: .RS 4
799: Zero if opt should be printed, non-zero if it should be filtered out\&.
800: .RE
801: .PP
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
816: .RS 4
817: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
818: .br
819: \fIindex\fP Index of the value to get\&. Zero based\&.
820: .br
821: \fIfp\fP File stream to print to, use stdout to print to the screen\&.
822: .RE
823: .PP
824: \fBSee also\fP
825: .RS 4
826: \fBcfg_print\fP, \fBcfg_set_print_func\fP
827: .RE
828: .PP
829:
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
844: .PP
845:
846: .SS "typedef int(* cfg_validate_callback_t) (\fBcfg_t\fP *cfg, \fBcfg_opt_t\fP *opt)"
847:
848: .PP
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\&.
850: .PP
851: \fBReturns\fP
852: .RS 4
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\&.
854: .RE
855: .PP
856: \fBSee also\fP
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:
866: .PP
867: Boolean values\&.
868: .SS "enum \fBcfg_type_t\fP"
869:
870: .PP
871: Fundamental option types\&.
872: .PP
873: \fBEnumerator\fP
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
896: .TP
897: \fB\fICFGT_COMMENT \fP\fP
898: comment/annotation
899: .SH "Function Documentation"
900: .PP
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\&.
905: .PP
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:
921: .PP
922: Add values for a list option\&. The new values are appended to any current values in the list\&.
923: .PP
924: \fBParameters\fP
925: .RS 4
926: \fIcfg\fP The configuration file context\&.
927: .br
928: \fIname\fP The name of the option\&.
929: .br
930: \fInvalues\fP Number of values to add\&.
931: .br
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\&.
933: .RE
934: .PP
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)"
942:
943: .PP
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
959: .PP
960:
961: .SS "DLLIMPORT void __export cfg_error (\fBcfg_t\fP * cfg, const char * fmt, \&.\&.\&.)"
962:
963: .PP
964: Show a parser error\&. Any user-defined error reporting function is called\&.
965: .PP
966: \fBSee also\fP
967: .RS 4
968: \fBcfg_set_error_function\fP
969: .RE
970: .PP
971:
972: .PP
973: \fBExamples\fP
974: .in +1c
975: \fBftpconf\&.c\fP\&.
976: .SS "DLLIMPORT int __export cfg_free (\fBcfg_t\fP * cfg)"
977:
978: .PP
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\&.
980: .PP
981: \fBReturns\fP
982: .RS 4
983: POSIX OK(0), or non-zero on failure\&.
984: .RE
985: .PP
986:
987: .PP
988: \fBExamples\fP
989: .in +1c
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:
993: .PP
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)\&.
995: .PP
996: \fBSee also\fP
997: .RS 4
998: \fBcfg_free()\fP
999: .RE
1000: .PP
1001: \fBReturns\fP
1002: .RS 4
1003: POSIX OK(0), or non-zero on failure\&.
1004: .RE
1005: .PP
1006:
1007: .SS "DLLIMPORT \fBcfg_bool_t\fP __export cfg_getbool (\fBcfg_t\fP * cfg, const char * name)"
1008:
1009: .PP
1010: Returns the value of a boolean option\&.
1011: .PP
1012: \fBParameters\fP
1013: .RS 4
1014: \fIcfg\fP The configuration file context\&.
1015: .br
1016: \fIname\fP The name of the option\&.
1017: .RE
1018: .PP
1019: \fBReturns\fP
1020: .RS 4
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\&.
1022: .RE
1023: .PP
1024:
1025: .PP
1026: \fBExamples\fP
1027: .in +1c
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:
1052: .SS "DLLIMPORT double __export cfg_getfloat (\fBcfg_t\fP * cfg, const char * name)"
1053:
1054: .PP
1055: Returns the value of a floating point option\&.
1056: .PP
1057: \fBParameters\fP
1058: .RS 4
1059: \fIcfg\fP The configuration file context\&.
1060: .br
1061: \fIname\fP The name of the option\&.
1062: .RE
1063: .PP
1064: \fBReturns\fP
1065: .RS 4
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\&.
1067: .RE
1068: .PP
1069:
1070: .SS "DLLIMPORT long int __export cfg_getint (\fBcfg_t\fP * cfg, const char * name)"
1071:
1072: .PP
1073: Returns the value of an integer option\&. This is the same as calling cfg_getnint with index 0\&.
1074: .PP
1075: \fBParameters\fP
1076: .RS 4
1077: \fIcfg\fP The configuration file context\&.
1078: .br
1079: \fIname\fP The name of the option\&.
1080: .RE
1081: .PP
1082: \fBReturns\fP
1083: .RS 4
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\&.
1085: .RE
1086: .PP
1087:
1088: .PP
1089: \fBExamples\fP
1090: .in +1c
1091: \fBftpconf\&.c\fP, and \fBreread\&.c\fP\&.
1092: .SS "DLLIMPORT \fBcfg_bool_t\fP __export cfg_getnbool (\fBcfg_t\fP * cfg, const char * name, unsigned int index)"
1093:
1094: .PP
1095: Indexed version of \fBcfg_getbool()\fP, used for lists\&.
1096: .PP
1097: \fBParameters\fP
1098: .RS 4
1099: \fIcfg\fP The configuration file context\&.
1100: .br
1101: \fIname\fP The name of the option\&.
1102: .br
1103: \fIindex\fP Index of the value to get\&. Zero based\&.
1104: .RE
1105: .PP
1106: \fBSee also\fP
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)"
1113:
1114: .PP
1115: Indexed version of \fBcfg_getfloat()\fP, used for lists\&.
1116: .PP
1117: \fBParameters\fP
1118: .RS 4
1119: \fIcfg\fP The configuration file context\&.
1120: .br
1121: \fIname\fP The name of the option\&.
1122: .br
1123: \fIindex\fP Index of the value to get\&. Zero based\&.
1124: .RE
1125: .PP
1126: \fBSee also\fP
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)"
1133:
1134: .PP
1135: Indexed version of \fBcfg_getint()\fP, used for lists\&.
1136: .PP
1137: \fBParameters\fP
1138: .RS 4
1139: \fIcfg\fP The configuration file context\&.
1140: .br
1141: \fIname\fP The name of the option\&.
1142: .br
1143: \fIindex\fP Index of the value to get\&. Zero based\&.
1144: .RE
1145: .PP
1146: \fBSee also\fP
1147: .RS 4
1148: \fBcfg_getint\fP
1149: .RE
1150: .PP
1151:
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:
1170: .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_getnsec (\fBcfg_t\fP * cfg, const char * name, unsigned int index)"
1171:
1172: .PP
1173: Indexed version of \fBcfg_getsec()\fP, used for sections with the CFGF_MULTI flag set\&.
1174: .PP
1175: \fBParameters\fP
1176: .RS 4
1177: \fIcfg\fP The configuration file context\&.
1178: .br
1179: \fIname\fP The name of the option\&.
1180: .br
1181: \fIindex\fP Index of the section to get\&. Zero based\&.
1182: .RE
1183: .PP
1184: \fBSee also\fP
1185: .RS 4
1186: \fBcfg_getsec\fP
1187: .RE
1188: .PP
1189:
1190: .PP
1191: \fBExamples\fP
1192: .in +1c
1193: \fBftpconf\&.c\fP, and \fBreread\&.c\fP\&.
1194: .SS "DLLIMPORT char* __export cfg_getnstr (\fBcfg_t\fP * cfg, const char * name, unsigned int index)"
1195:
1196: .PP
1197: Indexed version of \fBcfg_getstr()\fP, used for lists\&.
1198: .PP
1199: \fBParameters\fP
1200: .RS 4
1201: \fIcfg\fP The configuration file context\&.
1202: .br
1203: \fIname\fP The name of the option\&.
1204: .br
1205: \fIindex\fP Index of the value to get\&. Zero based\&.
1206: .RE
1207: .PP
1208: \fBSee also\fP
1209: .RS 4
1210: \fBcfg_getstr\fP
1211: .RE
1212: .PP
1213:
1214: .PP
1215: \fBExamples\fP
1216: .in +1c
1217: \fBftpconf\&.c\fP\&.
1218: .SS "DLLIMPORT \fBcfg_opt_t\fP* __export cfg_getopt (\fBcfg_t\fP * cfg, const char * name)"
1219:
1220: .PP
1221: Return an option given it's name\&.
1222: .PP
1223: \fBParameters\fP
1224: .RS 4
1225: \fIcfg\fP The configuration file context\&.
1226: .br
1227: \fIname\fP The name of the option\&.
1228: .RE
1229: .PP
1230: \fBReturns\fP
1231: .RS 4
1232: Returns a pointer to the option\&. If the option isn't declared, libConfuse will print an error message and return 0\&.
1233: .RE
1234: .PP
1235:
1236: .SS "DLLIMPORT void* __export cfg_getptr (\fBcfg_t\fP * cfg, const char * name)"
1237:
1238: .PP
1239: Returns the value of a user-defined option (void pointer)\&.
1240: .PP
1241: \fBParameters\fP
1242: .RS 4
1243: \fIcfg\fP The configuration file context\&.
1244: .br
1245: \fIname\fP The name of the option\&.
1246: .RE
1247: .PP
1248: \fBReturns\fP
1249: .RS 4
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\&.
1251: .RE
1252: .PP
1253:
1254: .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_getsec (\fBcfg_t\fP * cfg, const char * name)"
1255:
1256: .PP
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\&.
1258: .PP
1259: \fBParameters\fP
1260: .RS 4
1261: \fIcfg\fP The configuration file context\&.
1262: .br
1263: \fIname\fP The name of the option\&.
1264: .RE
1265: .PP
1266: \fBReturns\fP
1267: .RS 4
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\&.
1269: .RE
1270: .PP
1271:
1272: .SS "DLLIMPORT char* __export cfg_getstr (\fBcfg_t\fP * cfg, const char * name)"
1273:
1274: .PP
1275: Returns the value of a string option\&.
1276: .PP
1277: \fBParameters\fP
1278: .RS 4
1279: \fIcfg\fP The configuration file context\&.
1280: .br
1281: \fIname\fP The name of the option\&.
1282: .RE
1283: .PP
1284: \fBReturns\fP
1285: .RS 4
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\&.
1287: .RE
1288: .PP
1289:
1290: .PP
1291: \fBExamples\fP
1292: .in +1c
1293: \fBftpconf\&.c\fP, and \fBreread\&.c\fP\&.
1294: .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_gettsec (\fBcfg_t\fP * cfg, const char * name, const char * title)"
1295:
1296: .PP
1297: Return a section given the title, used for section with the CFGF_TITLE flag set\&.
1298: .PP
1299: \fBParameters\fP
1300: .RS 4
1301: \fIcfg\fP The configuration file context\&.
1302: .br
1303: \fIname\fP The name of the option\&.
1304: .br
1305: \fItitle\fP The title of this section\&. The CFGF_TITLE flag must have been set for this option\&.
1306: .RE
1307: .PP
1308: \fBSee also\fP
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)"
1315:
1316: .PP
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)
1318: .PP
1319: \fBExamples\fP
1320: .in +1c
1321: \fBftpconf\&.c\fP\&.
1322: .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_init (\fBcfg_opt_t\fP * opts, cfg_flag_t flags)"
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\&.
1326: .PP
1327: The options must no longer be defined in the same scope as where the cfg_xxx functions are used (since version 2\&.3)\&.
1328: .PP
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
1338: .PP
1339:
1340: .PP
1341: \fBParameters\fP
1342: .RS 4
1343: \fIopts\fP An arrary of options
1344: .br
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\&.
1346: .RE
1347: .PP
1348: \fBReturns\fP
1349: .RS 4
1350: A configuration context structure\&. This pointer is passed to almost all other functions as the first parameter\&.
1351: .RE
1352: .PP
1353:
1354: .PP
1355: \fBExamples\fP
1356: .in +1c
1357: \fBftpconf\&.c\fP, \fBreread\&.c\fP, and \fBsimple\&.c\fP\&.
1358: .SS "const DLLIMPORT char* __export cfg_name (\fBcfg_t\fP * cfg)"
1359:
1360: .PP
1361: Return the name of a section\&.
1362: .PP
1363: \fBParameters\fP
1364: .RS 4
1365: \fIcfg\fP The configuration file context\&.
1366: .RE
1367: .PP
1368: \fBReturns\fP
1369: .RS 4
1370: Returns the title, or 0 if there is no title\&. This string should not be modified\&.
1371: .RE
1372: .PP
1373:
1374: .PP
1375: \fBExamples\fP
1376: .in +1c
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
1410: .PP
1411:
1412: .SS "DLLIMPORT \fBcfg_bool_t\fP __export cfg_opt_getnbool (\fBcfg_opt_t\fP * opt, unsigned int index)"
1413:
1414: .PP
1415: Returns the value of a boolean option, given a \fBcfg_opt_t\fP pointer\&.
1416: .PP
1417: \fBParameters\fP
1418: .RS 4
1419: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1420: .br
1421: \fIindex\fP Index of the value to get\&. Zero based\&.
1422: .RE
1423: .PP
1424: \fBSee also\fP
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)"
1431:
1432: .PP
1433: Returns the value of a floating point option, given a \fBcfg_opt_t\fP pointer\&.
1434: .PP
1435: \fBParameters\fP
1436: .RS 4
1437: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1438: .br
1439: \fIindex\fP Index of the value to get\&. Zero based\&.
1440: .RE
1441: .PP
1442: \fBSee also\fP
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)"
1449:
1450: .PP
1451: Returns the value of an integer option, given a \fBcfg_opt_t\fP pointer\&.
1452: .PP
1453: \fBParameters\fP
1454: .RS 4
1455: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1456: .br
1457: \fIindex\fP Index of the value to get\&. Zero based\&.
1458: .RE
1459: .PP
1460: \fBSee also\fP
1461: .RS 4
1462: \fBcfg_getnint\fP
1463: .RE
1464: .PP
1465:
1466: .PP
1467: \fBExamples\fP
1468: .in +1c
1469: \fBftpconf\&.c\fP\&.
1470: .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_opt_getnsec (\fBcfg_opt_t\fP * opt, unsigned int index)"
1471:
1472: .PP
1473: Returns the value of a section option, given a \fBcfg_opt_t\fP pointer\&.
1474: .PP
1475: \fBParameters\fP
1476: .RS 4
1477: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1478: .br
1479: \fIindex\fP Index of the value to get\&. Zero based\&.
1480: .RE
1481: .PP
1482: \fBSee also\fP
1483: .RS 4
1484: \fBcfg_getnsec\fP
1485: .RE
1486: .PP
1487:
1488: .PP
1489: \fBExamples\fP
1490: .in +1c
1491: \fBftpconf\&.c\fP\&.
1492: .SS "DLLIMPORT char* __export cfg_opt_getnstr (\fBcfg_opt_t\fP * opt, unsigned int index)"
1493:
1494: .PP
1495: Returns the value of a string option, given a \fBcfg_opt_t\fP pointer\&.
1496: .PP
1497: \fBParameters\fP
1498: .RS 4
1499: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1500: .br
1501: \fIindex\fP Index of the value to get\&. Zero based\&.
1502: .RE
1503: .PP
1504: \fBSee also\fP
1505: .RS 4
1506: \fBcfg_getnstr\fP
1507: .RE
1508: .PP
1509:
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\&.
1514: .PP
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:
1531: .SS "DLLIMPORT \fBcfg_t\fP* __export cfg_opt_gettsec (\fBcfg_opt_t\fP * opt, const char * title)"
1532:
1533: .PP
1534: Returns the value of a section option, given a \fBcfg_opt_t\fP pointer and the title\&.
1535: .PP
1536: \fBParameters\fP
1537: .RS 4
1538: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1539: .br
1540: \fItitle\fP The title of this section\&. The CFGF_TITLE flag must have been set for this option\&.
1541: .RE
1542: .PP
1543: \fBSee also\fP
1544: .RS 4
1545: \fBcfg_gettsec\fP
1546: .RE
1547: .PP
1548:
1549: .SS "const DLLIMPORT char* __export cfg_opt_name (\fBcfg_opt_t\fP * opt)"
1550:
1551: .PP
1552: Return the name of an option\&.
1553: .PP
1554: \fBParameters\fP
1555: .RS 4
1556: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1557: .RE
1558: .PP
1559: \fBReturns\fP
1560: .RS 4
1561: Returns the title, or 0 if there is no title\&. This string should not be modified\&.
1562: .RE
1563: .PP
1564:
1565: .PP
1566: \fBExamples\fP
1567: .in +1c
1568: \fBftpconf\&.c\fP\&.
1569: .SS "DLLIMPORT int __export cfg_opt_nprint_var (\fBcfg_opt_t\fP * opt, unsigned int index, FILE * fp)"
1570:
1571: .PP
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\&.
1574: .PP
1575: \fBParameters\fP
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
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\&.
1605: .RE
1606: .PP
1607: \fBSee also\fP
1608: .RS 4
1609: \fBcfg_print_func_t\fP
1610: .RE
1611: .PP
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)"
1619:
1620: .PP
1621: Print an option and its value to a file\&. Same as cfg_opt_print, but with the indentation level specified\&.
1622: .PP
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:
1636: .PP
1637: Removes and frees a config section, given a \fBcfg_opt_t\fP pointer\&.
1638: .PP
1639: \fBParameters\fP
1640: .RS 4
1641: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1642: .br
1643: \fIindex\fP Index of the section to remove\&. Zero based\&.
1644: .RE
1645: .PP
1646: \fBSee also\fP
1647: .RS 4
1648: \fBcfg_rmnsec\fP
1649: .RE
1650: .PP
1651: \fBReturns\fP
1652: .RS 4
1653: POSIX OK(0), or non-zero on failure\&.
1654: .RE
1655: .PP
1656:
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\&.
1661: .PP
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
1668: .PP
1669: \fBSee also\fP
1670: .RS 4
1671: \fBcfg_rmtsec\fP
1672: .RE
1673: .PP
1674: \fBReturns\fP
1675: .RS 4
1676: POSIX OK(0), or non-zero on failure\&.
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)"
1681:
1682: .PP
1683: Set a print callback function for an option\&.
1684: .PP
1685: \fBParameters\fP
1686: .RS 4
1687: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1688: .br
1689: \fIpf\fP The print function callback\&.
1690: .RE
1691: .PP
1692: \fBSee also\fP
1693: .RS 4
1694: \fBcfg_print_func_t\fP
1695: .RE
1696: .PP
1697:
1698: .SS "DLLIMPORT int __export cfg_opt_setcomment (\fBcfg_opt_t\fP * opt, char * comment)"
1699:
1700: .PP
1701: Annotate an option\&.
1702: .PP
1703: \fBParameters\fP
1704: .RS 4
1705: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1706: .br
1707: \fIcomment\fP The annotation
1708: .RE
1709: .PP
1710: \fBSee also\fP
1711: .RS 4
1712: \fBcfg_setcomment\fP
1713: .RE
1714: .PP
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)"
1722:
1723: .PP
1724: Set an option (create an instance of an option)\&.
1725: .PP
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
1741: .PP
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
1749: .RS 4
1750: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1751: .br
1752: \fIvalue\fP The value to set\&.
1753: .br
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\&.
1755: .RE
1756: .PP
1757: \fBReturns\fP
1758: .RS 4
1759: POSIX OK(0), or non-zero on failure\&.
1760: .RE
1761: .PP
1762:
1763: .SS "DLLIMPORT int __export cfg_opt_setnfloat (\fBcfg_opt_t\fP * opt, double value, unsigned int index)"
1764:
1765: .PP
1766: Set a value of a floating point option\&.
1767: .PP
1768: \fBParameters\fP
1769: .RS 4
1770: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1771: .br
1772: \fIvalue\fP The value to set\&.
1773: .br
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\&.
1775: .RE
1776: .PP
1777: \fBReturns\fP
1778: .RS 4
1779: POSIX OK(0), or non-zero on failure\&.
1780: .RE
1781: .PP
1782:
1783: .SS "DLLIMPORT int __export cfg_opt_setnint (\fBcfg_opt_t\fP * opt, long int value, unsigned int index)"
1784:
1785: .PP
1786: Set a value of an integer option\&.
1787: .PP
1788: \fBParameters\fP
1789: .RS 4
1790: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1791: .br
1792: \fIvalue\fP The value to set\&.
1793: .br
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\&.
1800: .RE
1801: .PP
1802:
1803: .SS "DLLIMPORT int __export cfg_opt_setnstr (\fBcfg_opt_t\fP * opt, const char * value, unsigned int index)"
1804:
1805: .PP
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
1821: .PP
1822:
1823: .SS "DLLIMPORT unsigned int __export cfg_opt_size (\fBcfg_opt_t\fP * opt)"
1824:
1825: .PP
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)\&.
1827: .PP
1828: \fBParameters\fP
1829: .RS 4
1830: \fIopt\fP The option structure (eg, as returned from \fBcfg_getopt()\fP)
1831: .RE
1832: .PP
1833:
1834: .PP
1835: \fBExamples\fP
1836: .in +1c
1837: \fBftpconf\&.c\fP\&.
1838: .SS "DLLIMPORT int __export cfg_parse (\fBcfg_t\fP * cfg, const char * filename)"
1839:
1840: .PP
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\&.
1842: .PP
1843: \fBParameters\fP
1844: .RS 4
1845: \fIcfg\fP The configuration file context as returned from \fBcfg_init()\fP\&.
1846: .br
1847: \fIfilename\fP The name of the file to parse\&.
1848: .RE
1849: .PP
1850: \fBReturns\fP
1851: .RS 4
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\&.
1853: .RE
1854: .PP
1855:
1856: .PP
1857: \fBExamples\fP
1858: .in +1c
1859: \fBftpconf\&.c\fP, \fBreread\&.c\fP, and \fBsimple\&.c\fP\&.
1860: .SS "DLLIMPORT int __export cfg_parse_boolean (const char * s)"
1861:
1862: .PP
1863: Parse a boolean option string\&. Accepted 'true' values are 'true', 'on' and 'yes', and accepted 'false' values are 'false', 'off' and 'no'\&.
1864: .PP
1865: \fBReturns\fP
1866: .RS 4
1867: Returns 1 or 0 (true/false) if the string was parsed correctly, or -1 if an error occurred\&.
1868: .RE
1869: .PP
1870:
1871: .SS "DLLIMPORT int __export cfg_parse_buf (\fBcfg_t\fP * cfg, const char * buf)"
1872:
1873: .PP
1874: Same as \fBcfg_parse()\fP above, but takes a character buffer as argument\&.
1875: .PP
1876: \fBParameters\fP
1877: .RS 4
1878: \fIcfg\fP The configuration file context as returned from \fBcfg_init()\fP\&.
1879: .br
1880: \fIbuf\fP A zero-terminated string with configuration directives\&.
1881: .RE
1882: .PP
1883: \fBSee also\fP
1884: .RS 4
1885: \fBcfg_parse()\fP
1886: .RE
1887: .PP
1888: \fBReturns\fP
1889: .RS 4
1890: POSIX OK(0), or non-zero on failure\&.
1891: .RE
1892: .PP
1893:
1894: .PP
1895: \fBExamples\fP
1896: .in +1c
1897: \fBreread\&.c\fP\&.
1898: .SS "DLLIMPORT int __export cfg_parse_fp (\fBcfg_t\fP * cfg, FILE * fp)"
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
1909: .PP
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:
1923: .PP
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\&.
1925: .PP
1926: \fBParameters\fP
1927: .RS 4
1928: \fIcfg\fP The configuration file context\&.
1929: .br
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
1956: .RE
1957: .PP
1958: \fBReturns\fP
1959: .RS 4
1960: POSIX OK(0), or non-zero on failure\&.
1961: .RE
1962: .PP
1963:
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
1982: .PP
1983: \fBReturns\fP
1984: .RS 4
1985: POSIX OK(0), or non-zero on failure\&.
1986: .RE
1987: .PP
1988:
1989: .SS "DLLIMPORT int __export cfg_rmsec (\fBcfg_t\fP * cfg, const char * name)"
1990:
1991: .PP
1992: Removes and frees a config section\&. This is the same as calling cfg_rmnsec with index 0\&.
1993: .PP
1994: \fBParameters\fP
1995: .RS 4
1996: \fIcfg\fP The configuration file context\&.
1997: .br
1998: \fIname\fP The name of the section\&.
1999: .RE
2000: .PP
2001: \fBReturns\fP
2002: .RS 4
2003: POSIX OK(0), or non-zero on failure\&.
2004: .RE
2005: .PP
2006:
2007: .SS "DLLIMPORT int __export cfg_rmtsec (\fBcfg_t\fP * cfg, const char * name, const char * title)"
2008:
2009: .PP
2010: Removes and frees a section given the title, used for section with the CFGF_TITLE flag set\&.
2011: .PP
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
2020: .PP
2021: \fBSee also\fP
2022: .RS 4
2023: \fBcfg_rmsec\fP
2024: .RE
2025: .PP
2026: \fBReturns\fP
2027: .RS 4
2028: POSIX OK(0), or non-zero on failure\&.
2029: .RE
2030: .PP
2031:
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\&.
2036: .PP
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:
2050: .SS "DLLIMPORT \fBcfg_errfunc_t\fP __export cfg_set_error_function (\fBcfg_t\fP * cfg, \fBcfg_errfunc_t\fP errfunc)"
2051:
2052: .PP
2053: Install a user-defined error reporting function\&.
2054: .PP
2055: \fBReturns\fP
2056: .RS 4
2057: The old error reporting function is returned\&.
2058: .RE
2059: .PP
2060:
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
2082: .PP
2083:
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)"
2085:
2086: .PP
2087: Set a print callback function for an option given its name\&.
2088: .PP
2089: \fBParameters\fP
2090: .RS 4
2091: \fIcfg\fP The configuration file context\&.
2092: .br
2093: \fIname\fP The name of the option\&.
2094: .br
2095: \fIpf\fP The print callback function\&.
2096: .RE
2097: .PP
2098: \fBSee also\fP
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)"
2105:
2106: .PP
2107: Register a validating callback function for an option\&.
2108: .PP
2109: \fBParameters\fP
2110: .RS 4
2111: \fIcfg\fP The configuration file context\&.
2112: .br
2113: \fIname\fP The name of the option\&.
2114: .br
2115: \fIvf\fP The validating callback function\&.
2116: .RE
2117: .PP
2118: \fBSee also\fP
2119: .RS 4
2120: \fBcfg_validate_callback_t\fP
2121: .RE
2122: .PP
2123:
2124: .PP
2125: \fBExamples\fP
2126: .in +1c
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
2146: .PP
2147:
2148: .SS "DLLIMPORT int __export cfg_setbool (\fBcfg_t\fP * cfg, const char * name, \fBcfg_bool_t\fP value)"
2149:
2150: .PP
2151: Set the value of a boolean option given its name\&.
2152: .PP
2153: \fBParameters\fP
2154: .RS 4
2155: \fIcfg\fP The configuration file context\&.
2156: .br
2157: \fIname\fP The name of the option\&.
2158: .br
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\&.
2160: .RE
2161: .PP
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)"
2169:
2170: .PP
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\&.
2172: .PP
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
2178: .RS 4
2179: \fIcfg\fP The configuration file context\&.
2180: .br
2181: \fIname\fP The name of the option\&.
2182: .br
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\&.
2189: .RE
2190: .PP
2191:
2192: .SS "DLLIMPORT int __export cfg_setfloat (\fBcfg_t\fP * cfg, const char * name, double value)"
2193:
2194: .PP
2195: Set the value of a floating point option given its name\&.
2196: .PP
2197: \fBParameters\fP
2198: .RS 4
2199: \fIcfg\fP The configuration file context\&.
2200: .br
2201: \fIname\fP The name of the option\&.
2202: .br
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\&.
2209: .RE
2210: .PP
2211:
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
2225: .PP
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:
2234: .PP
2235: Set values for a list option\&. All existing values are replaced with the new ones\&.
2236: .PP
2237: \fBParameters\fP
2238: .RS 4
2239: \fIcfg\fP The configuration file context\&.
2240: .br
2241: \fIname\fP The name of the option\&.
2242: .br
2243: \fInvalues\fP Number of values to set\&.
2244: .br
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\&.
2246: .RE
2247: .PP
2248: \fBReturns\fP
2249: .RS 4
2250: POSIX OK(0), or non-zero on failure\&.
2251: .RE
2252: .PP
2253:
2254: .SS "DLLIMPORT int cfg_setmulti (\fBcfg_t\fP * cfg, const char * name, unsigned int nvalues, char ** values)"
2255:
2256: .PP
2257: Set an option (create an instance of an option)\&.
2258: .PP
2259: \fBParameters\fP
2260: .RS 4
2261: \fIcfg\fP The configuration file context\&.
2262: .br
2263: \fIname\fP The name of the option\&.
2264: .br
2265: \fInvalues\fP The number of values to set for the option\&.
2266: .br
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\&.
2273: .RE
2274: .PP
2275:
2276: .SS "DLLIMPORT int __export cfg_setnbool (\fBcfg_t\fP * cfg, const char * name, \fBcfg_bool_t\fP value, unsigned int index)"
2277:
2278: .PP
2279: Set a value of a boolean option given its name and index\&.
2280: .PP
2281: \fBParameters\fP
2282: .RS 4
2283: \fIcfg\fP The configuration file context\&.
2284: .br
2285: \fIname\fP The name of the option\&.
2286: .br
2287: \fIvalue\fP The value to set\&.
2288: .br
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\&.
2290: .RE
2291: .PP
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)"
2299:
2300: .PP
2301: Set a value of a floating point option given its name and index\&.
2302: .PP
2303: \fBParameters\fP
2304: .RS 4
2305: \fIcfg\fP The configuration file context\&.
2306: .br
2307: \fIname\fP The name of the option\&.
2308: .br
2309: \fIvalue\fP The value to set\&.
2310: .br
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\&.
2317: .RE
2318: .PP
2319:
2320: .SS "DLLIMPORT int __export cfg_setnint (\fBcfg_t\fP * cfg, const char * name, long int value, unsigned int index)"
2321:
2322: .PP
2323: Set a value of an integer option given its name and index\&.
2324: .PP
2325: \fBParameters\fP
2326: .RS 4
2327: \fIcfg\fP The configuration file context\&.
2328: .br
2329: \fIname\fP The name of the option\&.
2330: .br
2331: \fIvalue\fP The value to set\&.
2332: .br
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\&.
2339: .RE
2340: .PP
2341:
2342: .SS "DLLIMPORT int __export cfg_setnstr (\fBcfg_t\fP * cfg, const char * name, const char * value, unsigned int index)"
2343:
2344: .PP
2345: Set a value of a boolean option given its name and index\&.
2346: .PP
2347: \fBParameters\fP
2348: .RS 4
2349: \fIcfg\fP The configuration file context\&.
2350: .br
2351: \fIname\fP The name of the option\&.
2352: .br
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\&.
2356: .RE
2357: .PP
2358: \fBReturns\fP
2359: .RS 4
2360: POSIX OK(0), or non-zero on failure\&.
2361: .RE
2362: .PP
2363:
2364: .SS "DLLIMPORT \fBcfg_value_t\fP* cfg_setopt (\fBcfg_t\fP * cfg, \fBcfg_opt_t\fP * opt, const char * value)"
2365:
2366: .PP
2367: Set an option (create an instance of an option)\&.
2368: .PP
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
2377: .PP
2378: \fBReturns\fP
2379: .RS 4
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\&.
2392: .br
2393: \fIname\fP The name of the option\&.
2394: .br
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\&.
2401: .RE
2402: .PP
2403:
2404: .PP
2405: \fBExamples\fP
2406: .in +1c
2407: \fBsimple\&.c\fP\&.
2408: .SS "DLLIMPORT unsigned int __export cfg_size (\fBcfg_t\fP * cfg, const char * name)"
2409:
2410: .PP
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)\&.
2412: .PP
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\&.
2414: .PP
2415: \fBParameters\fP
2416: .RS 4
2417: \fIcfg\fP The configuration file context\&.
2418: .br
2419: \fIname\fP The name of the option\&.
2420: .RE
2421: .PP
2422:
2423: .PP
2424: \fBExamples\fP
2425: .in +1c
2426: \fBftpconf\&.c\fP, and \fBreread\&.c\fP\&.
2427: .SS "DLLIMPORT char* __export cfg_tilde_expand (const char * filename)"
2428:
2429: .PP
2430: Does tilde expansion (~ -> $HOME) on the filename\&.
2431: .PP
2432: \fBReturns\fP
2433: .RS 4
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\&.
2435: .RE
2436: .PP
2437:
2438: .SS "const DLLIMPORT char* __export cfg_title (\fBcfg_t\fP * cfg)"
2439:
2440: .PP
2441: Return the title of a section\&.
2442: .PP
2443: \fBParameters\fP
2444: .RS 4
2445: \fIcfg\fP The configuration file context\&.
2446: .RE
2447: .PP
2448: \fBReturns\fP
2449: .RS 4
2450: Returns the title, or 0 if there is no title\&. This string should not be modified\&.
2451: .RE
2452: .PP
2453:
2454: .SH "Author"
2455: .PP
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