1 /* 2 * Copyright (c) 2002-2017 Martin Hedenfalk <martin@bzero.se> 3 * 4 * Permission to use, copy, modify, and/or distribute this software for any 5 * purpose with or without fee is hereby granted, provided that the above 6 * copyright notice and this permission notice appear in all copies. 7 * 8 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15 */ 16 17 /** A configuration file parser library. 18 * @file confuse.h 19 * 20 */ 21 22 /** 23 * \mainpage libConfuse Documentation 24 * 25 * \section intro 26 * 27 * Copyright © 2002-2017 Martin Hedenfalk <martin@bzero.se> 28 * 29 * The latest versions of this manual and the libConfuse software are 30 * available at http://www.nongnu.org/confuse/ 31 * 32 * 33 * <em>If you can't convince, confuse.</em> 34 */ 35 36 #ifndef CONFUSE_H_ 37 #define CONFUSE_H_ 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 #include <stdio.h> 44 #include <stdarg.h> 45 46 #if defined(_WIN32) && !defined(__GNUC__) 47 # ifdef HAVE__FILENO 48 # define fileno _fileno 49 # endif 50 # include <io.h> 51 # ifdef HAVE__ISATTY 52 # define isatty _isatty 53 # endif 54 # ifdef BUILDING_STATIC 55 # define DLLIMPORT 56 # else /* ! BUILDING_STATIC */ 57 # ifdef BUILDING_DLL 58 # define DLLIMPORT __declspec (dllexport) 59 # else /* ! BUILDING_DLL */ 60 # define DLLIMPORT __declspec (dllimport) 61 # endif /* BUILDING_DLL */ 62 # endif /* BUILDING_STATIC */ 63 #else /* ! _WIN32 || __GNUC__ */ 64 # define DLLIMPORT 65 #endif /* _WIN32 */ 66 67 #ifndef __BORLANDC__ 68 # define __export 69 #endif 70 71 /** Fundamental option types */ 72 enum cfg_type_t { 73 CFGT_NONE, 74 CFGT_INT, /**< integer */ 75 CFGT_FLOAT, /**< floating point number */ 76 CFGT_STR, /**< string */ 77 CFGT_BOOL, /**< boolean value */ 78 CFGT_SEC, /**< section */ 79 CFGT_FUNC, /**< function */ 80 CFGT_PTR, /**< pointer to user-defined value */ 81 CFGT_COMMENT /**< comment/annotation */ 82 }; 83 typedef enum cfg_type_t cfg_type_t; 84 85 /** Flags. */ 86 #define CFGF_NONE (0) 87 #define CFGF_MULTI (1 << 0) /**< option may be specified multiple times (only applies to sections) */ 88 #define CFGF_LIST (1 << 1) /**< option is a list */ 89 #define CFGF_NOCASE (1 << 2) /**< configuration file is case insensitive */ 90 #define CFGF_TITLE (1 << 3) /**< option has a title (only applies to sections) */ 91 #define CFGF_NODEFAULT (1 << 4) /**< option has no default value */ 92 #define CFGF_NO_TITLE_DUPES (1 << 5) /**< multiple section titles must be unique 93 (duplicates raises an error, only applies to sections) */ 94 95 #define CFGF_RESET (1 << 6) 96 #define CFGF_DEFINIT (1 << 7) 97 #define CFGF_IGNORE_UNKNOWN (1 << 8) /**< ignore unknown options in configuration files */ 98 #define CFGF_DEPRECATED (1 << 9) /**< option is deprecated and should be ignored. */ 99 #define CFGF_DROP (1 << 10) /**< option should be dropped after parsing */ 100 #define CFGF_COMMENTS (1 << 11) /**< Enable option annotation/comments support */ 101 #define CFGF_MODIFIED (1 << 12) /**< option has been changed from its default value */ 102 #define CFGF_KEYSTRVAL (1 << 13) /**< section has free-form key=value string options created when parsing file */ 103 104 /** Return codes from cfg_parse(), cfg_parse_boolean(), and cfg_set*() functions. */ 105 #define CFG_SUCCESS 0 106 #define CFG_FAIL -1 107 #define CFG_FILE_ERROR -1 108 #define CFG_PARSE_ERROR 1 109 110 typedef union cfg_value_t cfg_value_t; 111 typedef union cfg_simple_t cfg_simple_t; 112 typedef struct cfg_opt_t cfg_opt_t; 113 typedef struct cfg_t cfg_t; 114 typedef struct cfg_defvalue_t cfg_defvalue_t; 115 typedef int cfg_flag_t; 116 typedef struct cfg_searchpath_t cfg_searchpath_t; 117 118 /** Function prototype used by CFGT_FUNC options. 119 * 120 * This is a callback function, registered with the CFG_FUNC 121 * initializer. Each time libConfuse finds a function, the registered 122 * callback function is called (parameters are passed as strings, any 123 * conversion to other types should be made in the callback 124 * function). libConfuse does not support any storage of the data 125 * found; these are passed as parameters to the callback, and it's the 126 * responsibility of the callback function to do whatever it should do 127 * with the data. 128 * 129 * @param cfg The configuration file context. 130 * @param opt The option. 131 * @param argc Number of arguments passed. The callback function is 132 * responsible for checking that the correct number of arguments are 133 * passed. 134 * @param argv Arguments as an array of character strings. 135 * 136 * @return On success, 0 should be returned. All other values 137 * indicates an error, and the parsing is aborted. The callback 138 * function should notify the error itself, for example by calling 139 * cfg_error(). 140 * 141 * @see CFG_FUNC 142 */ 143 typedef int (*cfg_func_t)(cfg_t *cfg, cfg_opt_t *opt, int argc, const char **argv); 144 145 /** Function prototype used by the cfg_print_ functions. 146 * 147 * This callback function is used to print option values. For options 148 * with a value parsing callback, this is often required, especially 149 * if a string is mapped to an integer by the callback. This print 150 * callback must then map the integer back to the appropriate string. 151 * 152 * Except for functions, the print callback function should only print 153 * the value of the option, not the name and the equal sign (that is 154 * handled by the cfg_opt_print function). For function options 155 * however, the name and the parenthesis must be printed by this 156 * function. The value to print can be accessed with the cfg_opt_get 157 * functions. 158 * 159 * @param opt The option structure (eg, as returned from cfg_getopt()) 160 * @param index Index of the value to get. Zero based. 161 * @param fp File stream to print to, use stdout to print to the screen. 162 * 163 * @see cfg_print, cfg_set_print_func 164 */ 165 typedef void (*cfg_print_func_t)(cfg_opt_t *opt, unsigned int index, FILE *fp); 166 167 /** Value parsing callback prototype 168 * 169 * This is a callback function (different from the one registered with the 170 * CFG_FUNC initializer) used to parse a value. This can be used to override 171 * the internal parsing of a value. 172 * 173 * Suppose you want an integer option that only can have certain values, for 174 * example 1, 2 and 3, and these should be written in the configuration file as 175 * "yes", "no" and "maybe". The callback function would be called with the 176 * found value ("yes", "no" or "maybe") as a string, and the result should be 177 * stored in the result parameter. 178 * 179 * @param cfg The configuration file context. 180 * @param opt The option. 181 * @param value The value found in the configuration file. 182 * @param result Pointer to storage for the result, cast to a void pointer. 183 * 184 * @return On success, 0 should be returned. All other values indicates an 185 * error, and the parsing is aborted. The callback function should notify the 186 * error itself, for example by calling cfg_error(). 187 */ 188 typedef int (*cfg_callback_t)(cfg_t *cfg, cfg_opt_t *opt, const char *value, void *result); 189 190 /** Validating callback prototype 191 * 192 * This callback function is called after an option has been parsed and set. 193 * The function is called for both fundamental values (strings, integers etc) 194 * as well as lists and sections. This can for example be used to validate that 195 * all required options in a section has been set to sane values. 196 * 197 * @return On success, 0 should be returned. All other values indicates an 198 * error, and the parsing is aborted. The callback function should notify the 199 * error itself, for example by calling cfg_error(). 200 * 201 * @see cfg_set_validate_func 202 */ 203 typedef int (*cfg_validate_callback_t)(cfg_t *cfg, cfg_opt_t *opt); 204 205 /** Validating callback2 prototype 206 * 207 * This callback function is called before an option is set using the 208 * cfg_set*() APIs. The function is called only for strings, integers, 209 * and floats. Compared to the regular callback function this takes a 210 * value pointer argument which must be casted before use, but can also 211 * be used to correct a value before it is set, e.g. when a too large 212 * value is set this can be used to set the MAX. 213 * 214 * @return On success, 0 should be returned. All other values indicates an 215 * error, and the cfg_set*() function will return without setting the value. 216 * 217 * @see cfg_set_validate_func2() 218 */ 219 typedef int (*cfg_validate_callback2_t)(cfg_t *cfg, cfg_opt_t *opt, void *value); 220 221 /** User-defined memory release function for CFG_PTR values 222 * 223 * This callback is used to free memory allocated in a value parsing callback 224 * function. Especially useful for CFG_PTR options, since libConfuse will not 225 * itself release such values. If the values are simply allocated with a 226 * malloc(3), one can use the standard free(3) function here. 227 * 228 */ 229 typedef void (*cfg_free_func_t)(void *value); 230 231 /** Boolean values. */ 232 typedef enum { cfg_false, cfg_true } cfg_bool_t; 233 234 /** Error reporting function. */ 235 typedef void (*cfg_errfunc_t)(cfg_t *cfg, const char *fmt, va_list ap); 236 237 /** Print filter function. 238 * 239 * @param cfg The configuration file context that opt belongs to. 240 * @param opt The configuration option that is about to be printed, or not. 241 * @return Zero if opt should be printed, non-zero if it should be filtered 242 * out. 243 * 244 * @see cfg_set_print_filter_func() 245 */ 246 typedef int (*cfg_print_filter_func_t)(cfg_t *cfg, cfg_opt_t *opt); 247 248 /** Data structure holding information about a "section". Sections can 249 * be nested. A section has a list of options (strings, numbers, 250 * booleans or other sections) grouped together. 251 */ 252 struct cfg_t { 253 cfg_flag_t flags; /**< Any flags passed to cfg_init() */ 254 char *name; /**< The name of this section, the root 255 * section returned from cfg_init() is 256 * always named "root" */ 257 char *comment; /**< Optional annotation/comment */ 258 cfg_opt_t *opts; /**< Array of options */ 259 char *title; /**< Optional title for this section, only 260 * set if CFGF_TITLE flag is set */ 261 char *filename; /**< Name of the file being parsed */ 262 int line; /**< Line number in the config file */ 263 cfg_errfunc_t errfunc; /**< This function (if set with 264 * cfg_set_error_function) is called for 265 * any error message. */ 266 cfg_searchpath_t *path; /**< Linked list of directories to search */ 267 cfg_print_filter_func_t pff; /**< Printing filter function */ 268 }; 269 270 /** Data structure holding the value of a fundamental option value. 271 */ 272 union cfg_value_t { 273 long int number; /**< integer value */ 274 double fpnumber; /**< floating point value */ 275 cfg_bool_t boolean; /**< boolean value */ 276 char *string; /**< string value */ 277 cfg_t *section; /**< section value */ 278 void *ptr; /**< user-defined value */ 279 }; 280 281 /** Data structure holding the pointer to a user provided variable 282 * defined with CFG_SIMPLE_* 283 */ 284 union cfg_simple_t { 285 long int *number; 286 double *fpnumber; 287 cfg_bool_t *boolean; 288 char **string; 289 void **ptr; 290 }; 291 292 /** Data structure holding the default value given by the 293 * initialization macros. 294 */ 295 struct cfg_defvalue_t { 296 long int number; /**< default integer value */ 297 double fpnumber; /**< default floating point value */ 298 cfg_bool_t boolean; /**< default boolean value */ 299 const char *string; /**< default string value */ 300 char *parsed; /**< default value that is parsed by 301 * libConfuse, used for lists and 302 * functions */ 303 }; 304 305 /** Data structure holding information about an option. The value(s) 306 * are stored as an array of fundamental values (strings, numbers, 307 * etc). 308 */ 309 struct cfg_opt_t { 310 const char *name; /**< The name of the option */ 311 char *comment; /**< Optional comment/annotation */ 312 cfg_type_t type; /**< Type of option */ 313 unsigned int nvalues; /**< Number of values parsed */ 314 cfg_value_t **values; /**< Array of found values */ 315 cfg_flag_t flags; /**< Flags */ 316 cfg_opt_t *subopts; /**< Suboptions (only applies to sections) */ 317 cfg_defvalue_t def; /**< Default value */ 318 cfg_func_t func; /**< Function callback for CFGT_FUNC options */ 319 cfg_simple_t simple_value; /**< Pointer to user-specified variable to 320 * store simple values (created with the 321 * CFG_SIMPLE_* initializers) */ 322 cfg_callback_t parsecb; /**< Value parsing callback function */ 323 cfg_validate_callback_t validcb; /**< Value validating parsing callback function */ 324 cfg_validate_callback2_t validcb2; /**< Value validating set callback function */ 325 cfg_print_func_t pf; /**< print callback function */ 326 cfg_free_func_t freecb; /***< user-defined memory release function */ 327 }; 328 329 extern const char __export confuse_copyright[]; 330 extern const char __export confuse_version[]; 331 extern const char __export confuse_author[]; 332 333 #define __CFG_STR(name, def, flags, svalue, cb) \ 334 {name,0,CFGT_STR,0,0,flags,0,{0,0,cfg_false,def,0},0,{.string=svalue},cb,0,0,0,0} 335 #define __CFG_STR_LIST(name, def, flags, svalue, cb) \ 336 {name,0,CFGT_STR,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,{.string=svalue},cb,0,0,0,0} 337 338 /** Initialize a string option 339 */ 340 #define CFG_STR(name, def, flags) \ 341 __CFG_STR(name, def, flags, 0, 0) 342 343 /** Initialize a string list option 344 */ 345 #define CFG_STR_LIST(name, def, flags) \ 346 __CFG_STR_LIST(name, def, flags, 0, 0) 347 348 /** Initialize a string option with a value parsing callback 349 */ 350 #define CFG_STR_CB(name, def, flags, cb) \ 351 __CFG_STR(name, def, flags, 0, cb) 352 353 /** Initialize a string list option with a value parsing callback 354 */ 355 #define CFG_STR_LIST_CB(name, def, flags, cb) \ 356 __CFG_STR_LIST(name, def, flags, 0, cb) 357 358 /** Initialize a "simple" string option. 359 * 360 * "Simple" options (in lack of a better expression) does not support 361 * lists of values or multiple sections. LibConfuse will store the 362 * value of a simple option in the user-defined location specified by 363 * the value parameter in the initializer. Simple options are not 364 * stored in the cfg_t context, only a pointer. Sections can not be 365 * initialized as a "simple" option. 366 * 367 * As of version 2.2, libConfuse can now return the values of simple 368 * options with the cfg_get functions. This allows using the new 369 * cfg_print function with simple options. 370 * 371 * libConfuse doesn't support handling default values for "simple" 372 * options. They are assumed to be set by the calling application 373 * before cfg_parse is called. 374 * 375 * @param name name of the option 376 * @param svalue pointer to a character pointer (a char **). This value 377 * must be initalized either to NULL or to a malloc()'ed string. You 378 * can't use 379 * <pre> 380 * char *user = "joe"; 381 * ... 382 * cfg_opt_t opts[] = { 383 * CFG_SIMPLE_STR("user", &user), 384 * ... 385 * </pre> 386 * since libConfuse will try to free the static string "joe" (which is 387 * an error) when a "user" option is found. Rather, use the following 388 * code snippet: 389 * <pre> 390 * char *user = strdup("joe"); 391 * ... 392 * cfg_opt_t opts[] = { 393 * CFG_SIMPLE_STR("user", &user), 394 * ... 395 * </pre> 396 * Alternatively, the default value can be set after the opts struct 397 * is defined, as in: 398 * <pre> 399 * char *user = 0; 400 * ... 401 * cfg_opt_t opts[] = { 402 * CFG_SIMPLE_STR("user", &user), 403 * ... 404 * user = strdup("joe"); 405 * cfg = cfg_init(opts, 0); 406 * cfg_parse(cfg, filename); 407 * </pre> 408 * 409 */ 410 #define CFG_SIMPLE_STR(name, svalue) \ 411 __CFG_STR(name, 0, CFGF_NONE, svalue, 0) 412 413 414 #define __CFG_INT(name, def, flags, svalue, cb) \ 415 {name,0,CFGT_INT,0,0,flags,0,{def,0,cfg_false,0,0},0,{.number=svalue},cb,0,0,0,0} 416 #define __CFG_INT_LIST(name, def, flags, svalue, cb) \ 417 {name,0,CFGT_INT,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,{.number=svalue},cb,0,0,0,0} 418 419 /** Initialize an integer option 420 */ 421 #define CFG_INT(name, def, flags) \ 422 __CFG_INT(name, def, flags, 0, 0) 423 424 /** Initialize an integer list option 425 */ 426 #define CFG_INT_LIST(name, def, flags) \ 427 __CFG_INT_LIST(name, def, flags, 0, 0) 428 429 /** Initialize an integer option with a value parsing callback 430 */ 431 #define CFG_INT_CB(name, def, flags, cb) \ 432 __CFG_INT(name, def, flags, 0, cb) 433 434 /** Initialize an integer list option with a value parsing callback 435 */ 436 #define CFG_INT_LIST_CB(name, def, flags, cb) \ 437 __CFG_INT_LIST(name, def, flags, 0, cb) 438 439 /** Initialize a "simple" integer option (see documentation for 440 * CFG_SIMPLE_STR for more information). 441 * Note that confuse uses long integers, so make sure that any pointer 442 * you provide for svalue points to a long int rather than a normal int. 443 * Otherwise, you will have strange problems on 64-bit architectures. 444 */ 445 #define CFG_SIMPLE_INT(name, svalue) \ 446 __CFG_INT(name, 0, CFGF_NONE, svalue, 0) 447 448 449 450 #define __CFG_FLOAT(name, def, flags, svalue, cb) \ 451 {name,0,CFGT_FLOAT,0,0,flags,0,{0,def,cfg_false,0,0},0,{.fpnumber=svalue},cb,0,0,0,0} 452 #define __CFG_FLOAT_LIST(name, def, flags, svalue, cb) \ 453 {name,0,CFGT_FLOAT,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,{.fpnumber=svalue},cb,0,0,0,0} 454 455 /** Initialize a floating point option 456 */ 457 #define CFG_FLOAT(name, def, flags) \ 458 __CFG_FLOAT(name, def, flags, 0, 0) 459 460 /** Initialize a floating point list option 461 */ 462 #define CFG_FLOAT_LIST(name, def, flags) \ 463 __CFG_FLOAT_LIST(name, def, flags, 0, 0) 464 465 /** Initialize a floating point option with a value parsing callback 466 */ 467 #define CFG_FLOAT_CB(name, def, flags, cb) \ 468 __CFG_FLOAT(name, def, flags, 0, cb) 469 470 /** Initialize a floating point list option with a value parsing callback 471 */ 472 #define CFG_FLOAT_LIST_CB(name, def, flags, cb) \ 473 __CFG_FLOAT_LIST(name, def, flags, 0, cb) 474 475 /** Initialize a "simple" floating point option (see documentation for 476 * CFG_SIMPLE_STR for more information). 477 */ 478 #define CFG_SIMPLE_FLOAT(name, svalue) \ 479 __CFG_FLOAT(name, 0, CFGF_NONE, svalue, 0) 480 481 482 483 #define __CFG_BOOL(name, def, flags, svalue, cb) \ 484 {name,0,CFGT_BOOL,0,0,flags,0,{0,0,def,0,0},0,{.boolean=svalue},cb,0,0,0,0} 485 #define __CFG_BOOL_LIST(name, def, flags, svalue, cb) \ 486 {name,0,CFGT_BOOL,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,{.boolean=svalue},cb,0,0,0,0} 487 488 /** Initialize a boolean option 489 */ 490 #define CFG_BOOL(name, def, flags) \ 491 __CFG_BOOL(name, def, flags, 0, 0) 492 493 /** Initialize a boolean list option 494 */ 495 #define CFG_BOOL_LIST(name, def, flags) \ 496 __CFG_BOOL_LIST(name, def, flags, 0, 0) 497 498 /** Initialize a boolean option with a value parsing callback 499 */ 500 #define CFG_BOOL_CB(name, def, flags, cb) \ 501 __CFG_BOOL(name, def, flags, 0, cb) 502 503 /** Initialize a boolean list option with a value parsing callback 504 */ 505 #define CFG_BOOL_LIST_CB(name, def, flags, cb) \ 506 __CFG_BOOL_LIST(name, def, flags, 0, cb) 507 508 /** Initialize a "simple" boolean option (see documentation for 509 * CFG_SIMPLE_STR for more information). 510 */ 511 #define CFG_SIMPLE_BOOL(name, svalue) \ 512 __CFG_BOOL(name, cfg_false, CFGF_NONE, svalue, 0) 513 514 515 516 /** Initialize a section 517 * 518 * @param name The name of the option 519 * @param opts Array of options that are valid within this section 520 521 * @param flags Flags, specify CFGF_MULTI if it should be possible to 522 * have multiples of the same section, and CFGF_TITLE if the 523 * section(s) must have a title (which can be used in the 524 * cfg_gettsec() function) 525 * 526 */ 527 #define CFG_SEC(name, opts, flags) \ 528 {name,0,CFGT_SEC,0,0,flags,opts,{0,0,cfg_false,0,0},0,{0},0,0,0,0,0} 529 530 531 532 /** Initialize a function 533 * @param name The name of the option 534 * @param func The callback function. 535 * 536 * @see cfg_func_t 537 */ 538 #define CFG_FUNC(name, func) \ 539 {name,0,CFGT_FUNC,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},func,{0},0,0,0,0,0} 540 541 542 #define __CFG_PTR(name, def, flags, svalue, parsecb, freecb) \ 543 {name,0,CFGT_PTR,0,0,flags,0,{0,0,cfg_false,0,def},0,{.ptr=svalue},parsecb,0,0,0,freecb} 544 #define __CFG_PTR_LIST(name, def, flags, svalue, parsecb, freecb) \ 545 {name,0,CFGT_PTR,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,{.ptr=svalue},parsecb,0,0,0,freecb} 546 547 /** Initialize a user-defined option 548 * 549 * CFG_PTR options can only be used together with a value parsing callback. 550 * 551 * @param name The name of the option 552 * @param def Default value 553 * @param flags Flags 554 * @param parsecb Value parsing callback 555 * @param freecb Memory release function 556 * 557 * @see cfg_callback_t, cfg_free_func_t 558 */ 559 #define CFG_PTR_CB(name, def, flags, parsecb, freecb) \ 560 __CFG_PTR(name, def, flags, 0, parsecb, freecb) 561 562 /** Initialize a list of user-defined options 563 */ 564 #define CFG_PTR_LIST_CB(name, def, flags, parsecb, freecb) \ 565 __CFG_PTR(name, def, flags | CFGF_LIST, 0, parsecb, freecb) 566 567 /*#define CFG_SIMPLE_PTR(name, svalue, cb) \ 568 __CFG_PTR(name, 0, 0, svalue, cb)*/ 569 570 571 /** Terminate list of options. This must be the last initializer in 572 * the option list. 573 */ 574 #define CFG_END() \ 575 {0,0,CFGT_NONE,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},0,{0},0,0,0,0,0} 576 577 578 579 /** Create and initialize a cfg_t structure. This should be the first function 580 * called when setting up the parsing of a configuration file. The options 581 * passed in the first parameter is initialized using the CFG_* initializers. 582 * The last option in the option array must be CFG_END(), unless you like 583 * segmentation faults. 584 * 585 * The options must no longer be defined in the same scope as where the cfg_xxx 586 * functions are used (since version 2.3). 587 * 588 * CFGF_IGNORE_UNKNOWN can be specified to use the "__unknown" option 589 * whenever an unknown option is parsed. Be sure to define an "__unknown" 590 * option in each scope that unknown parameters are allowed. 591 * 592 * Call setlocale() before calling this function to localize handling of 593 * types, LC_CTYPE, and messages, LC_MESSAGES, since version 2.9: 594 * <pre> 595 * setlocale(LC_MESSAGES, ""); 596 * setlocale(LC_CTYPE, ""); 597 * </pre> 598 * @param opts An arrary of options 599 * @param flags One or more flags (bitwise or'ed together). Currently only 600 * CFGF_NOCASE and CFGF_IGNORE_UNKNOWN are available. Use 0 if no flags are 601 * needed. 602 * 603 * @return A configuration context structure. This pointer is passed 604 * to almost all other functions as the first parameter. 605 */ 606 DLLIMPORT cfg_t *__export cfg_init(cfg_opt_t *opts, cfg_flag_t flags); 607 608 /** Add a searchpath directory to the configuration context, the 609 * const char* argument will be duplicated and then freed as part 610 * of the usual context takedown. 611 * 612 * All directories added to the context in this manner will be searched 613 * for the file specified in cfg_parse(), and for those included. 614 * All directories added with this function will be "tilde expanded". 615 * Note that the current directory is not added to the searchpath 616 * by default. 617 * 618 * @param cfg The configuration file context as returned from cfg_init(). 619 * @param dir Directory to be added to the search path. 620 * 621 * @return On success, CFG_SUCCESS, on failure (which can only be 622 * caused by a failed malloc()), CFG_PARSE_ERROR. 623 */ 624 DLLIMPORT int __export cfg_add_searchpath(cfg_t *cfg, const char *dir); 625 626 /** Search the linked-list of cfg_searchpath_t for the specified 627 * file. If not NULL, the return value is freshly allocated and 628 * and should be freed by the caller. 629 * 630 * @param path The linked list of cfg_searchpath_t structs, each 631 * containg a directory to be searched 632 * @param file The file for which to search 633 * 634 * @return If the file is found on the searchpath then the full 635 * path to the file is returned. If not found, NULL is returned. 636 */ 637 DLLIMPORT char *__export cfg_searchpath(cfg_searchpath_t *path, const char *file); 638 639 /** Parse a configuration file. Tilde expansion is performed on the 640 * filename before it is opened. After a configuration file has been 641 * initialized (with cfg_init()) and parsed (with cfg_parse()), the 642 * values can be read with the cfg_getXXX functions. 643 * 644 * @param cfg The configuration file context as returned from cfg_init(). 645 * @param filename The name of the file to parse. 646 * 647 * @return On success, CFG_SUCCESS is returned. If the file couldn't 648 * be opened for reading, CFG_FILE_ERROR is returned. On all other 649 * errors, CFG_PARSE_ERROR is returned and cfg_error() was called with 650 * a descriptive error message. 651 */ 652 DLLIMPORT int __export cfg_parse(cfg_t *cfg, const char *filename); 653 654 /** Same as cfg_parse() above, but takes an already opened file as 655 * argument. Reading begins at the current position. After parsing, 656 * the position is not reset. The caller is responsible for closing 657 * the file. 658 * 659 * @param cfg The configuration file context as returned from cfg_init(). 660 * @param fp An open file stream. 661 * 662 * @see cfg_parse() 663 * 664 * @return POSIX OK(0), or non-zero on failure. 665 */ 666 DLLIMPORT int __export cfg_parse_fp(cfg_t *cfg, FILE *fp); 667 668 /** Same as cfg_parse() above, but takes a character buffer as 669 * argument. 670 * 671 * @param cfg The configuration file context as returned from cfg_init(). 672 * @param buf A zero-terminated string with configuration directives. 673 * 674 * @see cfg_parse() 675 * 676 * @return POSIX OK(0), or non-zero on failure. 677 */ 678 DLLIMPORT int __export cfg_parse_buf(cfg_t *cfg, const char *buf); 679 680 /** Free the memory allocated for the values of a given option. Only 681 * the values are freed, not the option itself (it is freed by cfg_free()). 682 * 683 * @see cfg_free() 684 * 685 * @return POSIX OK(0), or non-zero on failure. 686 */ 687 DLLIMPORT int __export cfg_free_value(cfg_opt_t *opt); 688 689 /** Free a cfg_t context. All memory allocated by the cfg_t context 690 * structure are freed, and can't be used in any further cfg_* calls. 691 * 692 * @return POSIX OK(0), or non-zero on failure. 693 */ 694 DLLIMPORT int __export cfg_free(cfg_t *cfg); 695 696 /** Install a user-defined error reporting function. 697 * @return The old error reporting function is returned. 698 */ 699 DLLIMPORT cfg_errfunc_t __export cfg_set_error_function(cfg_t *cfg, cfg_errfunc_t errfunc); 700 701 /** Show a parser error. Any user-defined error reporting function is called. 702 * @see cfg_set_error_function 703 */ 704 DLLIMPORT void __export cfg_error(cfg_t *cfg, const char *fmt, ...); 705 706 /** Returns the option comment 707 * @param opt The option structure (eg, as returned from cfg_getopt()) 708 * @see cfg_getcomment 709 */ 710 DLLIMPORT char * __export cfg_opt_getcomment(cfg_opt_t *opt); 711 712 /** Returns the option comment 713 * 714 * This function can be used to extract option annotations from a config 715 * file. Only comments preceding the option are read by cfg_parse(). 716 * 717 * @param cfg The configuration file context. 718 * @param name The name of the option. 719 * @see cfg_setcomment 720 * @return The comment for this option, or NULL if unset 721 */ 722 DLLIMPORT char * __export cfg_getcomment(cfg_t *cfg, const char *name); 723 724 /** Returns the value of an integer option, given a cfg_opt_t pointer. 725 * @param opt The option structure (eg, as returned from cfg_getopt()) 726 * @param index Index of the value to get. Zero based. 727 * @see cfg_getnint 728 */ 729 DLLIMPORT signed long __export cfg_opt_getnint(cfg_opt_t *opt, unsigned int index); 730 731 /** Indexed version of cfg_getint(), used for lists. 732 * @param cfg The configuration file context. 733 * @param name The name of the option. 734 * @param index Index of the value to get. Zero based. 735 * @see cfg_getint 736 */ 737 DLLIMPORT long int __export cfg_getnint(cfg_t *cfg, const char *name, unsigned int index); 738 739 /** Returns the value of an integer option. This is the same as 740 * calling cfg_getnint with index 0. 741 * @param cfg The configuration file context. 742 * @param name The name of the option. 743 * @return The requested value is returned. If the option was not set 744 * in the configuration file, the default value given in the 745 * corresponding cfg_opt_t structure is returned. It is an error to 746 * try to get an option that isn't declared. 747 */ 748 DLLIMPORT long int __export cfg_getint(cfg_t *cfg, const char *name); 749 750 /** Returns the value of a floating point option, given a cfg_opt_t pointer. 751 * @param opt The option structure (eg, as returned from cfg_getopt()) 752 * @param index Index of the value to get. Zero based. 753 * @see cfg_getnfloat 754 */ 755 DLLIMPORT double __export cfg_opt_getnfloat(cfg_opt_t *opt, unsigned int index); 756 757 /** Indexed version of cfg_getfloat(), used for lists. 758 * @param cfg The configuration file context. 759 * @param name The name of the option. 760 * @param index Index of the value to get. Zero based. 761 * @see cfg_getfloat 762 */ 763 DLLIMPORT double __export cfg_getnfloat(cfg_t *cfg, const char *name, unsigned int index); 764 765 /** Returns the value of a floating point option. 766 * @param cfg The configuration file context. 767 * @param name The name of the option. 768 * @return The requested value is returned. If the option was not set 769 * in the configuration file, the default value given in the 770 * corresponding cfg_opt_t structure is returned. It is an error to 771 * try to get an option that isn't declared. 772 */ 773 DLLIMPORT double __export cfg_getfloat(cfg_t *cfg, const char *name); 774 775 /** Returns the value of a string option, given a cfg_opt_t pointer. 776 * @param opt The option structure (eg, as returned from cfg_getopt()) 777 * @param index Index of the value to get. Zero based. 778 * @see cfg_getnstr 779 */ 780 DLLIMPORT char *__export cfg_opt_getnstr(cfg_opt_t *opt, unsigned int index); 781 782 /** Indexed version of cfg_getstr(), used for lists. 783 * @param cfg The configuration file context. 784 * @param name The name of the option. 785 * @param index Index of the value to get. Zero based. 786 * @see cfg_getstr 787 */ 788 DLLIMPORT char *__export cfg_getnstr(cfg_t *cfg, const char *name, unsigned int index); 789 790 /** Returns the value of a string option. 791 * @param cfg The configuration file context. 792 * @param name The name of the option. 793 * @return The requested value is returned. If the option was not set 794 * in the configuration file, the default value given in the 795 * corresponding cfg_opt_t structure is returned. It is an error to 796 * try to get an option that isn't declared. 797 */ 798 DLLIMPORT char *__export cfg_getstr(cfg_t *cfg, const char *name); 799 800 /** Returns the value of a boolean option, given a cfg_opt_t pointer. 801 * @param opt The option structure (eg, as returned from cfg_getopt()) 802 * @param index Index of the value to get. Zero based. 803 * @see cfg_getnbool 804 */ 805 DLLIMPORT cfg_bool_t __export cfg_opt_getnbool(cfg_opt_t *opt, unsigned int index); 806 807 /** Indexed version of cfg_getbool(), used for lists. 808 * 809 * @param cfg The configuration file context. 810 * @param name The name of the option. 811 * @param index Index of the value to get. Zero based. 812 * @see cfg_getbool 813 */ 814 DLLIMPORT cfg_bool_t __export cfg_getnbool(cfg_t *cfg, const char *name, unsigned int index); 815 816 /** Returns the value of a boolean option. 817 * @param cfg The configuration file context. 818 * @param name The name of the option. 819 * @return The requested value is returned. If the option was not set 820 * in the configuration file, the default value given in the 821 * corresponding cfg_opt_t structure is returned. It is an error to 822 * try to get an option that isn't declared. 823 */ 824 DLLIMPORT cfg_bool_t __export cfg_getbool(cfg_t *cfg, const char *name); 825 826 827 DLLIMPORT void *__export cfg_opt_getnptr(cfg_opt_t *opt, unsigned int index); 828 DLLIMPORT void *__export cfg_getnptr(cfg_t *cfg, const char *name, unsigned int indx); 829 830 /** Returns the value of a user-defined option (void pointer). 831 * @param cfg The configuration file context. 832 * @param name The name of the option. 833 * @return The requested value is returned. If the option was not set 834 * in the configuration file, the default value given in the 835 * corresponding cfg_opt_t structure is returned. It is an error to 836 * try to get an option that isn't declared. 837 */ 838 DLLIMPORT void *__export cfg_getptr(cfg_t *cfg, const char *name); 839 840 841 /** Returns the value of a section option, given a cfg_opt_t pointer. 842 * @param opt The option structure (eg, as returned from cfg_getopt()) 843 * @param index Index of the value to get. Zero based. 844 * @see cfg_getnsec 845 */ 846 DLLIMPORT cfg_t *__export cfg_opt_getnsec(cfg_opt_t *opt, unsigned int index); 847 848 /** Indexed version of cfg_getsec(), used for sections with the 849 * CFGF_MULTI flag set. 850 * 851 * @param cfg The configuration file context. 852 * @param name The name of the option. 853 * @param index Index of the section to get. Zero based. 854 * @see cfg_getsec 855 */ 856 DLLIMPORT cfg_t *__export cfg_getnsec(cfg_t *cfg, const char *name, unsigned int index); 857 858 /** Returns the value of a section option, given a cfg_opt_t pointer 859 * and the title. 860 * @param opt The option structure (eg, as returned from cfg_getopt()) 861 * @param title The title of this section. The CFGF_TITLE flag must 862 * have been set for this option. 863 * @see cfg_gettsec 864 */ 865 DLLIMPORT cfg_t *__export cfg_opt_gettsec(cfg_opt_t *opt, const char *title); 866 867 /** Return a section given the title, used for section with the 868 * CFGF_TITLE flag set. 869 * 870 * @param cfg The configuration file context. 871 * @param name The name of the option. 872 * @param title The title of this section. The CFGF_TITLE flag must 873 * have been set for this option. 874 * @see cfg_getsec 875 */ 876 DLLIMPORT cfg_t *__export cfg_gettsec(cfg_t *cfg, const char *name, const char *title); 877 878 /** Returns the value of a section option. The returned value is 879 * another cfg_t structure that can be used in following calls to 880 * cfg_getint, cfg_getstr or other get-functions. 881 * @param cfg The configuration file context. 882 * @param name The name of the option. 883 * @return The requested section is returned. If no section is found 884 * with that name, 0 is returned. There can only be default values for 885 * section without the CFGF_MULTI flag set. It is an error to try to 886 * get a section that isn't declared. 887 */ 888 DLLIMPORT cfg_t *__export cfg_getsec(cfg_t *cfg, const char *name); 889 890 /** Return the number of values this option has. If no default value 891 * is given for the option and no value was found in the config file, 892 * 0 will be returned (ie, the option value is not set at all). 893 * @param opt The option structure (eg, as returned from cfg_getopt()) 894 */ 895 DLLIMPORT unsigned int __export cfg_opt_size(cfg_opt_t *opt); 896 897 /** Return the number of values this option has. If no default value 898 * is given for the option and no value was found in the config file, 899 * 0 will be returned (ie, the option value is not set at all). 900 * 901 * Note that there is no way to *not* specify a default value for integers, 902 * floats and booleans. Ie, they always have default values (since 0 or NULL is 903 * a valid integer/float/boolean value). Only strings and lists may have no 904 * default value. 905 * 906 * @param cfg The configuration file context. 907 * @param name The name of the option. 908 */ 909 DLLIMPORT unsigned int __export cfg_size(cfg_t *cfg, const char *name); 910 911 /** Return the title of a section. 912 * 913 * @param cfg The configuration file context. 914 * @return Returns the title, or 0 if there is no title. This string 915 * should not be modified. 916 */ 917 DLLIMPORT const char *__export cfg_title(cfg_t *cfg); 918 919 /** Return the name of a section. 920 * 921 * @param cfg The configuration file context. 922 * @return Returns the title, or 0 if there is no title. This string 923 * should not be modified. 924 */ 925 DLLIMPORT const char *__export cfg_name(cfg_t *cfg); 926 927 /** Return the name of an option. 928 * 929 * @param opt The option structure (eg, as returned from cfg_getopt()) 930 * @return Returns the title, or 0 if there is no title. This string 931 * should not be modified. 932 */ 933 DLLIMPORT const char *__export cfg_opt_name(cfg_opt_t *opt); 934 935 /** Return the string value of a key=value pair 936 * 937 * @param opt The option structure (eg, as returned from cfg_getnopt()) 938 * @see cfg_opt_name 939 * @return The string value for the option, or NULL if it's not a 940 * string. This string must not be modified! 941 */ 942 DLLIMPORT const char *cfg_opt_getstr(cfg_opt_t *opt); 943 944 /** Predefined include-function. This function can be used in the 945 * options passed to cfg_init() to specify a function for including 946 * other configuration files in the parsing. For example: 947 * CFG_FUNC("include", &cfg_include) 948 */ 949 DLLIMPORT int __export cfg_include(cfg_t *cfg, cfg_opt_t *opt, int argc, const char **argv); 950 951 /** Does tilde expansion (~ -> $HOME) on the filename. 952 * @return The expanded filename is returned. If a ~user was not 953 * found, the original filename is returned. In any case, a 954 * dynamically allocated string is returned, which should be free()'d 955 * by the caller. 956 */ 957 DLLIMPORT char *__export cfg_tilde_expand(const char *filename); 958 959 /** Parse a boolean option string. Accepted "true" values are "true", 960 * "on" and "yes", and accepted "false" values are "false", "off" and 961 * "no". 962 * 963 * @return Returns 1 or 0 (true/false) if the string was parsed 964 * correctly, or -1 if an error occurred. 965 */ 966 DLLIMPORT int __export cfg_parse_boolean(const char *s); 967 968 /** Return the nth option in a file or section 969 * 970 * @param cfg The configuration file or section context 971 * @param index Option index 972 * @see cfg_num 973 */ 974 DLLIMPORT cfg_opt_t *cfg_getnopt(cfg_t *cfg, unsigned int index); 975 976 /** Return an option given it's name. 977 * 978 * @param cfg The configuration file context. 979 * @param name The name of the option. 980 * 981 * @return Returns a pointer to the option. If the option isn't declared, 982 * libConfuse will print an error message and return 0. 983 */ 984 DLLIMPORT cfg_opt_t *__export cfg_getopt(cfg_t *cfg, const char *name); 985 986 /** Set an option (create an instance of an option). 987 * 988 * @param cfg The configuration file context. 989 * @param opt The option definition. 990 * @param value The initial value for the option. 991 * 992 * @return Returns a pointer to the value object. 993 */ 994 DLLIMPORT cfg_value_t *cfg_setopt(cfg_t *cfg, cfg_opt_t *opt, const char *value); 995 996 /** Annotate an option 997 * @param opt The option structure (eg, as returned from cfg_getopt()) 998 * @param comment The annotation 999 * @see cfg_setcomment 1000 * @return POSIX OK(0), or non-zero on failure. 1001 */ 1002 DLLIMPORT int __export cfg_opt_setcomment(cfg_opt_t *opt, char *comment); 1003 1004 /** Annotate an option given its name 1005 * 1006 * All options can be annotated as long as the CFGF_COMMENTS flag is 1007 * given to cfg_init(). 1008 * 1009 * When calling cfg_print(), annotations are saved as a C style one-liner 1010 * comment before each option. 1011 * 1012 * When calling cfg_parse(), only one-liner comments preceding an option 1013 * are read and used to annotate the option. 1014 * 1015 * @param cfg The configuration file context. 1016 * @param name The name of the option. 1017 * @param comment The annotation 1018 * 1019 * @return POSIX OK(0), or non-zero on failure. This function will fail 1020 * if memory for the new comment cannot be allocated. 1021 */ 1022 DLLIMPORT int __export cfg_setcomment(cfg_t *cfg, const char *name, char *comment); 1023 1024 /** Set a value of an integer option. 1025 * 1026 * @param opt The option structure (eg, as returned from cfg_getopt()) 1027 * @param value The value to set. 1028 * @param index The index in the option value array that should be 1029 * modified. It is an error to set values with indices larger than 0 1030 * for options without the CFGF_LIST flag set. 1031 * 1032 * @return POSIX OK(0), or non-zero on failure. 1033 */ 1034 DLLIMPORT int __export cfg_opt_setnint(cfg_opt_t *opt, long int value, unsigned int index); 1035 1036 /** Set the value of an integer option given its name. 1037 * 1038 * @param cfg The configuration file context. 1039 * @param name The name of the option. 1040 * @param value The value to set. If the option is a list (the CFGF_LIST flag 1041 * is set), only the first value (with index 0) is set. 1042 * 1043 * @return POSIX OK(0), or non-zero on failure. 1044 */ 1045 DLLIMPORT int __export cfg_setint(cfg_t *cfg, const char *name, long int value); 1046 1047 /** Set a value of an integer option given its name and index. 1048 * 1049 * @param cfg The configuration file context. 1050 * @param name The name of the option. 1051 * @param value The value to set. 1052 * @param index The index in the option value array that should be 1053 * modified. It is an error to set values with indices larger than 0 1054 * for options without the CFGF_LIST flag set. 1055 * 1056 * @return POSIX OK(0), or non-zero on failure. 1057 */ 1058 DLLIMPORT int __export cfg_setnint(cfg_t *cfg, const char *name, long int value, unsigned int index); 1059 1060 /** Set a value of a floating point option. 1061 * 1062 * @param opt The option structure (eg, as returned from cfg_getopt()) 1063 * @param value The value to set. 1064 * @param index The index in the option value array that should be 1065 * modified. It is an error to set values with indices larger than 0 1066 * for options without the CFGF_LIST flag set. 1067 * 1068 * @return POSIX OK(0), or non-zero on failure. 1069 */ 1070 DLLIMPORT int __export cfg_opt_setnfloat(cfg_opt_t *opt, double value, unsigned int index); 1071 1072 /** Set the value of a floating point option given its name. 1073 * 1074 * @param cfg The configuration file context. 1075 * @param name The name of the option. 1076 * @param value The value to set. If the option is a list (the CFGF_LIST flag 1077 * is set), only the first value (with index 0) is set. 1078 * 1079 * @return POSIX OK(0), or non-zero on failure. 1080 */ 1081 DLLIMPORT int __export cfg_setfloat(cfg_t *cfg, const char *name, double value); 1082 1083 /** Set a value of a floating point option given its name and index. 1084 * 1085 * @param cfg The configuration file context. 1086 * @param name The name of the option. 1087 * @param value The value to set. 1088 * @param index The index in the option value array that should be 1089 * modified. It is an error to set values with indices larger than 0 1090 * for options without the CFGF_LIST flag set. 1091 * 1092 * @return POSIX OK(0), or non-zero on failure. 1093 */ 1094 DLLIMPORT int __export cfg_setnfloat(cfg_t *cfg, const char *name, double value, unsigned int index); 1095 1096 /** Set a value of a boolean option. 1097 * 1098 * @param opt The option structure (eg, as returned from cfg_getopt()) 1099 * @param value The value to set. 1100 * @param index The index in the option value array that should be 1101 * modified. It is an error to set values with indices larger than 0 1102 * for options without the CFGF_LIST flag set. 1103 * 1104 * @return POSIX OK(0), or non-zero on failure. 1105 */ 1106 DLLIMPORT int __export cfg_opt_setnbool(cfg_opt_t *opt, cfg_bool_t value, unsigned int index); 1107 1108 /** Set the value of a boolean option given its name. 1109 * 1110 * @param cfg The configuration file context. 1111 * @param name The name of the option. 1112 * @param value The value to set. If the option is a list (the CFGF_LIST flag 1113 * is set), only the first value (with index 0) is set. 1114 * 1115 * @return POSIX OK(0), or non-zero on failure. 1116 */ 1117 DLLIMPORT int __export cfg_setbool(cfg_t *cfg, const char *name, cfg_bool_t value); 1118 1119 /** Set a value of a boolean option given its name and index. 1120 * 1121 * @param cfg The configuration file context. 1122 * @param name The name of the option. 1123 * @param value The value to set. 1124 * @param index The index in the option value array that should be 1125 * modified. It is an error to set values with indices larger than 0 1126 * for options without the CFGF_LIST flag set. 1127 * 1128 * @return POSIX OK(0), or non-zero on failure. 1129 */ 1130 DLLIMPORT int __export cfg_setnbool(cfg_t *cfg, const char *name, cfg_bool_t value, unsigned int index); 1131 1132 /** Set a value of a string option. 1133 * 1134 * @param opt The option structure (eg, as returned from cfg_getopt()) 1135 * @param value The value to set. Memory for the string is allocated 1136 * and the value is copied. Any previous string value is freed. 1137 * @param index The index in the option value array that should be 1138 * modified. It is an error to set values with indices larger than 0 1139 * for options without the CFGF_LIST flag set. 1140 * 1141 * @return POSIX OK(0), or non-zero on failure. 1142 */ 1143 DLLIMPORT int __export cfg_opt_setnstr(cfg_opt_t *opt, const char *value, unsigned int index); 1144 1145 /** Set the value of a string option given its name. 1146 * 1147 * @param cfg The configuration file context. 1148 * @param name The name of the option. 1149 * @param value The value to set. Memory for the string is allocated and the 1150 * value is copied. Any previous string value is freed. If the option is a list 1151 * (the CFGF_LIST flag is set), only the first value (with index 0) is set. 1152 * 1153 * @return POSIX OK(0), or non-zero on failure. 1154 */ 1155 DLLIMPORT int __export cfg_setstr(cfg_t *cfg, const char *name, const char *value); 1156 1157 /** Set a value of a boolean option given its name and index. 1158 * 1159 * @param cfg The configuration file context. 1160 * @param name The name of the option. 1161 * @param value The value to set. Memory for the string is allocated 1162 * and the value is copied. Any privious string value is freed. 1163 * @param index The index in the option value array that should be 1164 * modified. It is an error to set values with indices larger than 0 1165 * for options without the CFGF_LIST flag set. 1166 * 1167 * @return POSIX OK(0), or non-zero on failure. 1168 */ 1169 DLLIMPORT int __export cfg_setnstr(cfg_t *cfg, const char *name, const char *value, unsigned int index); 1170 1171 /** Set values for a list option. All existing values are replaced 1172 * with the new ones. 1173 * 1174 * @param cfg The configuration file context. 1175 * @param name The name of the option. 1176 * @param nvalues Number of values to set. 1177 * @param ... The values to set, the type must match the type of the 1178 * option and the number of values must be equal to the nvalues 1179 * parameter. 1180 * 1181 * @return POSIX OK(0), or non-zero on failure. 1182 */ 1183 DLLIMPORT int __export cfg_setlist(cfg_t *cfg, const char *name, unsigned int nvalues, ...); 1184 1185 DLLIMPORT int __export cfg_numopts(cfg_opt_t *opts); 1186 1187 /** Return number of options in a file or section 1188 * 1189 * @param cfg The configuration file or section context 1190 * 1191 * When a file has been parsed this function returns the number of 1192 * options/settings the file, or a sub-section, has. 1193 * 1194 * @return Number of options in a config file or section. 1195 */ 1196 DLLIMPORT unsigned int __export cfg_num(cfg_t *cfg); 1197 1198 /** Add values for a list option. The new values are appended to any 1199 * current values in the list. 1200 * 1201 * @param cfg The configuration file context. 1202 * @param name The name of the option. 1203 * @param nvalues Number of values to add. 1204 * @param ... The values to add, the type must match the type of the 1205 * option and the number of values must be equal to the nvalues 1206 * parameter. 1207 * 1208 * @return POSIX OK(0), or non-zero on failure. 1209 */ 1210 DLLIMPORT int __export cfg_addlist(cfg_t *cfg, const char *name, unsigned int nvalues, ...); 1211 1212 /** Set an option (create an instance of an option). 1213 * 1214 * @param cfg The configuration file context. 1215 * @param opt The option definition. 1216 * @param nvalues The number of values to set for the option. 1217 * @param values The value(s) for the option. 1218 * 1219 * @return POSIX OK(0), or non-zero on failure. 1220 */ 1221 DLLIMPORT int cfg_opt_setmulti(cfg_t *cfg, cfg_opt_t *opt, unsigned int nvalues, char **values); 1222 1223 /** Set an option (create an instance of an option). 1224 * 1225 * @param cfg The configuration file context. 1226 * @param name The name of the option. 1227 * @param nvalues The number of values to set for the option. 1228 * @param values The value(s) for the option. 1229 * 1230 * @return POSIX OK(0), or non-zero on failure. 1231 */ 1232 DLLIMPORT int cfg_setmulti(cfg_t *cfg, const char *name, unsigned int nvalues, char **values); 1233 1234 /** Create a new titled config section. 1235 * 1236 * @param cfg The configuration file context. 1237 * @param name The name of the option. 1238 * @param title The title of this section. 1239 * 1240 * @return A pointer to the created section or if the section 1241 * already exists a pointer to that section is returned. 1242 * If the section could not be created or found, 0 is returned. 1243 */ 1244 DLLIMPORT cfg_t *cfg_addtsec(cfg_t *cfg, const char *name, const char *title); 1245 1246 /** Removes and frees a config section, given a cfg_opt_t pointer. 1247 * @param opt The option structure (eg, as returned from cfg_getopt()) 1248 * @param index Index of the section to remove. Zero based. 1249 * @see cfg_rmnsec 1250 * 1251 * @return POSIX OK(0), or non-zero on failure. 1252 */ 1253 DLLIMPORT int __export cfg_opt_rmnsec(cfg_opt_t *opt, unsigned int index); 1254 1255 /** Indexed version of cfg_rmsec(), used for CFGF_MULTI sections. 1256 * @param cfg The configuration file context. 1257 * @param name The name of the section. 1258 * @param index Index of the section to remove. Zero based. 1259 * @see cfg_rmsec 1260 * 1261 * @return POSIX OK(0), or non-zero on failure. 1262 */ 1263 DLLIMPORT int __export cfg_rmnsec(cfg_t *cfg, const char *name, unsigned int index); 1264 1265 /** Removes and frees a config section. This is the same as 1266 * calling cfg_rmnsec with index 0. 1267 * @param cfg The configuration file context. 1268 * @param name The name of the section. 1269 * 1270 * @return POSIX OK(0), or non-zero on failure. 1271 */ 1272 DLLIMPORT int __export cfg_rmsec(cfg_t *cfg, const char *name); 1273 1274 /** Removes and frees a config section, given a cfg_opt_t pointer 1275 * and the title. 1276 * @param opt The option structure (eg, as returned from cfg_getopt()) 1277 * @param title The title of this section. The CFGF_TITLE flag must 1278 * have been set for this option. 1279 * @see cfg_rmtsec 1280 * 1281 * @return POSIX OK(0), or non-zero on failure. 1282 */ 1283 DLLIMPORT int __export cfg_opt_rmtsec(cfg_opt_t *opt, const char *title); 1284 1285 /** Removes and frees a section given the title, used for section with the 1286 * CFGF_TITLE flag set. 1287 * 1288 * @param cfg The configuration file context. 1289 * @param name The name of the section. 1290 * @param title The title of this section. The CFGF_TITLE flag must 1291 * have been set for this option. 1292 * @see cfg_rmsec 1293 * 1294 * @return POSIX OK(0), or non-zero on failure. 1295 */ 1296 DLLIMPORT int __export cfg_rmtsec(cfg_t *cfg, const char *name, const char *title); 1297 1298 /** Default value print function. 1299 * 1300 * Print only the value of a given option. Does not handle sections or 1301 * functions. Use cfg_opt_print to print the whole assignment ("option 1302 * = value"), or cfg_print to print the whole config file. 1303 * 1304 * @param opt The option structure (eg, as returned from cfg_getopt()) 1305 * @param index The index in the option value array that should be printed 1306 * @param fp File stream to print to. 1307 * 1308 * @see cfg_print, cfg_opt_print 1309 * 1310 * @return POSIX OK(0), or non-zero on failure. 1311 */ 1312 DLLIMPORT int __export cfg_opt_nprint_var(cfg_opt_t *opt, unsigned int index, FILE *fp); 1313 1314 /** Print an option and its value to a file. 1315 * Same as cfg_opt_print, but with the indentation level specified. 1316 * @see cfg_opt_print 1317 * 1318 * @return POSIX OK(0), or non-zero on failure. 1319 */ 1320 DLLIMPORT int __export cfg_opt_print_indent(cfg_opt_t *opt, FILE *fp, int indent); 1321 1322 /** Print an option and its value to a file. 1323 * 1324 * If a print callback function is specified for the option, it is 1325 * used instead of cfg_opt_nprint_var. 1326 * 1327 * @param opt The option structure (eg, as returned from cfg_getopt()) 1328 * @param fp File stream to print to. 1329 * 1330 * @see cfg_print_func_t 1331 * 1332 * @return POSIX OK(0), or non-zero on failure. 1333 */ 1334 DLLIMPORT int __export cfg_opt_print(cfg_opt_t *opt, FILE *fp); 1335 1336 /** Print the options and values to a file. 1337 * Same as cfg_print, but with the indentation level specified. 1338 * @see cfg_print 1339 * 1340 * @return POSIX OK(0), or non-zero on failure. 1341 */ 1342 DLLIMPORT int __export cfg_print_indent(cfg_t *cfg, FILE *fp, int indent); 1343 1344 /** Print the options and values to a file. 1345 * 1346 * Note that options in any included file are expanded and printed 1347 * directly to the file. Option values given with environment 1348 * variables in the parsed input are also printed expanded. This means 1349 * that if you parse a configuration file you can't expect that the 1350 * output from this function is identical to the initial file. 1351 * 1352 * @param cfg The configuration file context. 1353 * @param fp File stream to print to, use stdout to print to the screen. 1354 * 1355 * @see cfg_print_func_t, cfg_set_print_func 1356 * 1357 * @return POSIX OK(0), or non-zero on failure. 1358 */ 1359 DLLIMPORT int __export cfg_print(cfg_t *cfg, FILE *fp); 1360 1361 /** Set a print callback function for an option. 1362 * 1363 * @param opt The option structure (eg, as returned from cfg_getopt()) 1364 * @param pf The print function callback. 1365 * 1366 * @see cfg_print_func_t 1367 */ 1368 DLLIMPORT cfg_print_func_t __export cfg_opt_set_print_func(cfg_opt_t *opt, cfg_print_func_t pf); 1369 1370 /** Set a print callback function for an option given its name. 1371 * 1372 * @param cfg The configuration file context. 1373 * @param name The name of the option. 1374 * @param pf The print callback function. 1375 * 1376 * @see cfg_print_func_t 1377 */ 1378 DLLIMPORT cfg_print_func_t __export cfg_set_print_func(cfg_t *cfg, const char *name, cfg_print_func_t pf); 1379 1380 /** Install a user-defined print filter function. This callback is 1381 * called for each option when printing cfg, or something above cfg 1382 * if cfg is a section in some parent cfg. When cfg (or something 1383 * above cfg) is printed, this filter is also inherited to child 1384 * sections unless the child section has its own print filter. 1385 * 1386 * @param cfg The configuration file context. 1387 * @param pff The print filter callback function. 1388 * 1389 * @return The old print filter function is returned. 1390 * 1391 * @see cfg_print_filter_func_t 1392 */ 1393 DLLIMPORT cfg_print_filter_func_t __export cfg_set_print_filter_func(cfg_t *cfg, cfg_print_filter_func_t pff); 1394 1395 /** Register a validating callback function for an option. 1396 * 1397 * @param cfg The configuration file context. 1398 * @param name The name of the option. 1399 * @param vf The validating callback function. 1400 * 1401 * @see cfg_validate_callback_t 1402 */ 1403 DLLIMPORT cfg_validate_callback_t __export cfg_set_validate_func(cfg_t *cfg, const char *name, cfg_validate_callback_t vf); 1404 1405 /** Register a validating callback function for an option. 1406 * 1407 * This callback is called for all cfg_set*() functions, although not 1408 * cfg_opt_set*(), and can be used to check and modify a value/string 1409 * *before* it is actually set. The regular callbacks are run after 1410 * the fact and are only called when parsing a buffer or file. 1411 * 1412 * @param cfg The configuration file context. 1413 * @param name The name of the option. 1414 * @param vf The validating callback function. 1415 * 1416 * @see cfg_validate_callback2_t 1417 */ 1418 DLLIMPORT cfg_validate_callback2_t __export cfg_set_validate_func2(cfg_t *cfg, const char *name, cfg_validate_callback2_t vf); 1419 1420 #ifdef __cplusplus 1421 } 1422 #endif 1423 #endif /* CONFUSE_H_ */ 1424 1425 /** @example ftpconf.c 1426 */ 1427 1428 /** @example simple.c 1429 */ 1430 1431 /** @example reread.c 1432 */ 1433 1434 /** 1435 * Local Variables: 1436 * indent-tabs-mode: t 1437 * c-file-style: "linux" 1438 * End: 1439 */ 1440