1/* 2 * Copyright (c) 2002,2003,2007 Martin Hedenfalk <martin@bzero.se> 3 * 4 * Permission to use, copy, modify, and 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-2003 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 _cfg_h_ 37#define _cfg_h_ 38 39#ifdef __cplusplus 40extern "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_DLL 55# define DLLIMPORT __declspec (dllexport) 56# else /* ! BUILDING_DLL */ 57# define DLLIMPORT __declspec (dllimport) 58# endif /* BUILDING_DLL */ 59#else /* ! _WIN32 || __GNUC__ */ 60# define DLLIMPORT 61#endif /* _WIN32 */ 62 63#ifndef __BORLANDC__ 64# define __export 65#endif 66 67/** Fundamental option types */ 68enum cfg_type_t { 69 CFGT_NONE, 70 CFGT_INT, /**< integer */ 71 CFGT_FLOAT, /**< floating point number */ 72 CFGT_STR, /**< string */ 73 CFGT_BOOL, /**< boolean value */ 74 CFGT_SEC, /**< section */ 75 CFGT_FUNC, /**< function */ 76 CFGT_PTR /**< pointer to user-defined value */ 77}; 78typedef enum cfg_type_t cfg_type_t; 79 80/** Flags. */ 81#define CFGF_NONE 0 82#define CFGF_MULTI 1 /**< option may be specified multiple times (only applies to sections) */ 83#define CFGF_LIST 2 /**< option is a list */ 84#define CFGF_NOCASE 4 /**< configuration file is case insensitive */ 85#define CFGF_TITLE 8 /**< option has a title (only applies to sections) */ 86#define CFGF_NODEFAULT 16 /**< option has no default value */ 87#define CFGF_NO_TITLE_DUPES 32 /**< multiple section titles must be unique 88 (duplicates raises an error, only applies to 89 sections) */ 90 91#define CFGF_RESET 64 92#define CFGF_DEFINIT 128 93 94/** Return codes from cfg_parse(). */ 95#define CFG_SUCCESS 0 96#define CFG_FILE_ERROR -1 97#define CFG_PARSE_ERROR 1 98 99typedef union cfg_value_t cfg_value_t; 100typedef struct cfg_opt_t cfg_opt_t; 101typedef struct cfg_t cfg_t; 102typedef struct cfg_defvalue_t cfg_defvalue_t; 103typedef int cfg_flag_t; 104 105/** Function prototype used by CFGT_FUNC options. 106 * 107 * This is a callback function, registered with the CFG_FUNC 108 * initializer. Each time libConfuse finds a function, the registered 109 * callback function is called (parameters are passed as strings, any 110 * conversion to other types should be made in the callback 111 * function). libConfuse does not support any storage of the data 112 * found; these are passed as parameters to the callback, and it's the 113 * responsibility of the callback function to do whatever it should do 114 * with the data. 115 * 116 * @param cfg The configuration file context. 117 * @param opt The option. 118 * @param argc Number of arguments passed. The callback function is 119 * responsible for checking that the correct number of arguments are 120 * passed. 121 * @param argv Arguments as an array of character strings. 122 * 123 * @return On success, 0 should be returned. All other values 124 * indicates an error, and the parsing is aborted. The callback 125 * function should notify the error itself, for example by calling 126 * cfg_error(). 127 * 128 * @see CFG_FUNC 129 */ 130typedef int (*cfg_func_t)(cfg_t *cfg, cfg_opt_t *opt, 131 int argc, const char **argv); 132 133/** Function prototype used by the cfg_print_ functions. 134 * 135 * This callback function is used to print option values. For options 136 * with a value parsing callback, this is often required, especially 137 * if a string is mapped to an integer by the callback. This print 138 * callback must then map the integer back to the appropriate string. 139 * 140 * Except for functions, the print callback function should only print 141 * the value of the option, not the name and the equal sign (that is 142 * handled by the cfg_opt_print function). For function options 143 * however, the name and the parenthesis must be printed by this 144 * function. The value to print can be accessed with the cfg_opt_get 145 * functions. 146 * 147 * @param opt The option structure (eg, as returned from cfg_getopt()) 148 * @param index Index of the value to get. Zero based. 149 * @param fp File stream to print to, use stdout to print to the screen. 150 * 151 * @see cfg_print, cfg_set_print_func 152 */ 153typedef void (*cfg_print_func_t)(cfg_opt_t *opt, unsigned int index, FILE *fp); 154 155/** Value parsing callback prototype 156 * 157 * This is a callback function (different from the one registered with the 158 * CFG_FUNC initializer) used to parse a value. This can be used to override 159 * the internal parsing of a value. 160 * 161 * Suppose you want an integer option that only can have certain values, for 162 * example 1, 2 and 3, and these should be written in the configuration file as 163 * "yes", "no" and "maybe". The callback function would be called with the 164 * found value ("yes", "no" or "maybe") as a string, and the result should be 165 * stored in the result parameter. 166 * 167 * @param cfg The configuration file context. 168 * @param opt The option. 169 * @param value The value found in the configuration file. 170 * @param result Pointer to storage for the result, cast to a void pointer. 171 * 172 * @return On success, 0 should be returned. All other values indicates an 173 * error, and the parsing is aborted. The callback function should notify the 174 * error itself, for example by calling cfg_error(). 175 */ 176typedef int (*cfg_callback_t)(cfg_t *cfg, cfg_opt_t *opt, 177 const char *value, void *result); 178 179/** Validating callback prototype 180 * 181 * This callback function is called after an option has been parsed and set. 182 * The function is called for both fundamental values (strings, integers etc) 183 * as well as lists and sections. This can for example be used to validate that 184 * all required options in a section has been set to sane values. 185 * 186 * @return On success, 0 should be returned. All other values indicates an 187 * error, and the parsing is aborted. The callback function should notify the 188 * error itself, for example by calling cfg_error(). 189 * 190 * @see cfg_set_validate_func 191 */ 192typedef int (*cfg_validate_callback_t)(cfg_t *cfg, cfg_opt_t *opt); 193 194/** User-defined memory release function for CFG_PTR values 195 * 196 * This callback is used to free memory allocated in a value parsing callback 197 * function. Especially useful for CFG_PTR options, since libConfuse will not 198 * itself release such values. If the values are simply allocated with a 199 * malloc(3), one can use the standard free(3) function here. 200 * 201 */ 202typedef void (*cfg_free_func_t)(void *value); 203 204/** Boolean values. */ 205typedef enum {cfg_false, cfg_true} cfg_bool_t; 206 207/** Error reporting function. */ 208typedef void (*cfg_errfunc_t)(cfg_t *cfg, const char *fmt, va_list ap); 209 210/** Data structure holding information about a "section". Sections can 211 * be nested. A section has a list of options (strings, numbers, 212 * booleans or other sections) grouped together. 213 */ 214struct cfg_t { 215 cfg_flag_t flags; /**< Any flags passed to cfg_init() */ 216 char *name; /**< The name of this section, the root 217 * section returned from cfg_init() is 218 * always named "root" */ 219 cfg_opt_t *opts; /**< Array of options */ 220 char *title; /**< Optional title for this section, only 221 * set if CFGF_TITLE flag is set */ 222 char *filename; /**< Name of the file being parsed */ 223 int line; /**< Line number in the config file */ 224 cfg_errfunc_t errfunc; /**< This function (if set with 225 * cfg_set_error_function) is called for 226 * any error message. */ 227}; 228 229/** Data structure holding the value of a fundamental option value. 230 */ 231union cfg_value_t { 232 long int number; /**< integer value */ 233 double fpnumber; /**< floating point value */ 234 cfg_bool_t boolean; /**< boolean value */ 235 char *string; /**< string value */ 236 cfg_t *section; /**< section value */ 237 void *ptr; /**< user-defined value */ 238}; 239 240/** Data structure holding the default value given by the 241 * initialization macros. 242 */ 243struct cfg_defvalue_t { 244 long int number; /**< default integer value */ 245 double fpnumber; /**< default floating point value */ 246 cfg_bool_t boolean; /**< default boolean value */ 247 char *string; /**< default string value */ 248 char *parsed; /**< default value that is parsed by 249 * libConfuse, used for lists and 250 * functions */ 251}; 252 253/** Data structure holding information about an option. The value(s) 254 * are stored as an array of fundamental values (strings, numbers, 255 * etc). 256 */ 257struct cfg_opt_t { 258 char *name; /**< The name of the option */ 259 cfg_type_t type; /**< Type of option */ 260 unsigned int nvalues; /**< Number of values parsed */ 261 cfg_value_t **values; /**< Array of found values */ 262 cfg_flag_t flags; /**< Flags */ 263 cfg_opt_t *subopts; /**< Suboptions (only applies to sections) */ 264 cfg_defvalue_t def; /**< Default value */ 265 cfg_func_t func; /**< Function callback for CFGT_FUNC options */ 266 void *simple_value; /**< Pointer to user-specified variable to 267 * store simple values (created with the 268 * CFG_SIMPLE_* initializers) */ 269 cfg_callback_t parsecb; /**< Value parsing callback function */ 270 cfg_validate_callback_t validcb; /**< Value validating callback function */ 271 cfg_print_func_t pf; /**< print callback function */ 272 cfg_free_func_t freecb; /***< user-defined memory release function */ 273}; 274 275extern const char __export confuse_copyright[]; 276extern const char __export confuse_version[]; 277extern const char __export confuse_author[]; 278 279#define __CFG_STR(name, def, flags, svalue, cb) \ 280 {name,CFGT_STR,0,0,flags,0,{0,0,cfg_false,def,0},0,svalue,cb,0,0,0} 281#define __CFG_STR_LIST(name, def, flags, svalue, cb) \ 282 {name,CFGT_STR,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,svalue,cb,0,0,0} 283 284/** Initialize a string option 285 */ 286#define CFG_STR(name, def, flags) \ 287 __CFG_STR(name, def, flags, 0, 0) 288 289/** Initialize a string list option 290 */ 291#define CFG_STR_LIST(name, def, flags) \ 292 __CFG_STR_LIST(name, def, flags, 0, 0) 293 294/** Initialize a string option with a value parsing callback 295 */ 296#define CFG_STR_CB(name, def, flags, cb) \ 297 __CFG_STR(name, def, flags, 0, cb) 298 299/** Initialize a string list option with a value parsing callback 300 */ 301#define CFG_STR_LIST_CB(name, def, flags, cb) \ 302 __CFG_STR_LIST(name, def, flags, 0, cb) 303 304/** Initialize a "simple" string option. 305 * 306 * "Simple" options (in lack of a better expression) does not support 307 * lists of values or multiple sections. LibConfuse will store the 308 * value of a simple option in the user-defined location specified by 309 * the value parameter in the initializer. Simple options are not 310 * stored in the cfg_t context, only a pointer. Sections can not be 311 * initialized as a "simple" option. 312 * 313 * As of version 2.2, libConfuse can now return the values of simple 314 * options with the cfg_get functions. This allows using the new 315 * cfg_print function with simple options. 316 * 317 * libConfuse doesn't support handling default values for "simple" 318 * options. They are assumed to be set by the calling application 319 * before cfg_parse is called. 320 * 321 * @param name name of the option 322 * @param svalue pointer to a character pointer (a char **). This value 323 * must be initalized either to NULL or to a malloc()'ed string. You 324 * can't use 325 * <pre> 326 * char *user = "joe"; 327 * ... 328 * cfg_opt_t opts[] = { 329 * CFG_SIMPLE_STR("user", &user), 330 * ... 331 * </pre> 332 * since libConfuse will try to free the static string "joe" (which is 333 * an error) when a "user" option is found. Rather, use the following 334 * code snippet: 335 * <pre> 336 * char *user = strdup("joe"); 337 * ... 338 * cfg_opt_t opts[] = { 339 * CFG_SIMPLE_STR("user", &user), 340 * ... 341 * </pre> 342 * Alternatively, the default value can be set after the opts struct 343 * is defined, as in: 344 * <pre> 345 * char *user = 0; 346 * ... 347 * cfg_opt_t opts[] = { 348 * CFG_SIMPLE_STR("user", &user), 349 * ... 350 * user = strdup("joe"); 351 * cfg = cfg_init(opts, 0); 352 * cfg_parse(cfg, filename); 353 * </pre> 354 * 355 */ 356#define CFG_SIMPLE_STR(name, svalue) \ 357 __CFG_STR(name, 0, CFGF_NONE, svalue, 0) 358 359 360#define __CFG_INT(name, def, flags, svalue, cb) \ 361 {name,CFGT_INT,0,0,flags,0,{def,0,cfg_false,0,0},0,svalue,cb,0,0,0} 362#define __CFG_INT_LIST(name, def, flags, svalue, cb) \ 363 {name,CFGT_INT,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,svalue,cb,0,0,0} 364 365/** Initialize an integer option 366 */ 367#define CFG_INT(name, def, flags) \ 368 __CFG_INT(name, def, flags, 0, 0) 369 370/** Initialize an integer list option 371 */ 372#define CFG_INT_LIST(name, def, flags) \ 373 __CFG_INT_LIST(name, def, flags, 0, 0) 374 375/** Initialize an integer option with a value parsing callback 376 */ 377#define CFG_INT_CB(name, def, flags, cb) \ 378 __CFG_INT(name, def, flags, 0, cb) 379 380/** Initialize an integer list option with a value parsing callback 381 */ 382#define CFG_INT_LIST_CB(name, def, flags, cb) \ 383 __CFG_INT_LIST(name, def, flags, 0, cb) 384 385/** Initialize a "simple" integer option (see documentation for 386 * CFG_SIMPLE_STR for more information). 387 */ 388#define CFG_SIMPLE_INT(name, svalue) \ 389 __CFG_INT(name, 0, CFGF_NONE, svalue, 0) 390 391 392 393#define __CFG_FLOAT(name, def, flags, svalue, cb) \ 394 {name,CFGT_FLOAT,0,0,flags,0,{0,def,cfg_false,0,0},0,svalue,cb,0,0,0} 395#define __CFG_FLOAT_LIST(name, def, flags, svalue, cb) \ 396 {name,CFGT_FLOAT,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,svalue,cb,0,0,0} 397 398/** Initialize a floating point option 399 */ 400#define CFG_FLOAT(name, def, flags) \ 401 __CFG_FLOAT(name, def, flags, 0, 0) 402 403/** Initialize a floating point list option 404 */ 405#define CFG_FLOAT_LIST(name, def, flags) \ 406 __CFG_FLOAT_LIST(name, def, flags, 0, 0) 407 408/** Initialize a floating point option with a value parsing callback 409 */ 410#define CFG_FLOAT_CB(name, def, flags, cb) \ 411 __CFG_FLOAT(name, def, flags, 0, cb) 412 413/** Initialize a floating point list option with a value parsing callback 414 */ 415#define CFG_FLOAT_LIST_CB(name, def, flags, cb) \ 416 __CFG_FLOAT_LIST(name, def, flags, 0, cb) 417 418/** Initialize a "simple" floating point option (see documentation for 419 * CFG_SIMPLE_STR for more information). 420 */ 421#define CFG_SIMPLE_FLOAT(name, svalue) \ 422 __CFG_FLOAT(name, 0, CFGF_NONE, svalue, 0) 423 424 425 426#define __CFG_BOOL(name, def, flags, svalue, cb) \ 427 {name,CFGT_BOOL,0,0,flags,0,{0,0,def,0,0},0,svalue,cb,0,0,0} 428#define __CFG_BOOL_LIST(name, def, flags, svalue, cb) \ 429 {name,CFGT_BOOL,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,svalue,cb,0,0,0} 430 431/** Initialize a boolean option 432 */ 433#define CFG_BOOL(name, def, flags) \ 434 __CFG_BOOL(name, def, flags, 0, 0) 435 436/** Initialize a boolean list option 437 */ 438#define CFG_BOOL_LIST(name, def, flags) \ 439 __CFG_BOOL_LIST(name, def, flags, 0, 0) 440 441/** Initialize a boolean option with a value parsing callback 442 */ 443#define CFG_BOOL_CB(name, def, flags, cb) \ 444 __CFG_BOOL(name, def, flags, 0, cb) 445 446/** Initialize a boolean list option with a value parsing callback 447 */ 448#define CFG_BOOL_LIST_CB(name, def, flags, cb) \ 449 __CFG_BOOL_LIST(name, def, flags, 0, cb) 450 451/** Initialize a "simple" boolean option (see documentation for 452 * CFG_SIMPLE_STR for more information). 453 */ 454#define CFG_SIMPLE_BOOL(name, svalue) \ 455 __CFG_BOOL(name, cfg_false, CFGF_NONE, svalue, 0) 456 457 458 459/** Initialize a section 460 * 461 * @param name The name of the option 462 * @param opts Array of options that are valid within this section 463 464 * @param flags Flags, specify CFGF_MULTI if it should be possible to 465 * have multiples of the same section, and CFGF_TITLE if the 466 * section(s) must have a title (which can be used in the 467 * cfg_gettsec() function) 468 * 469 */ 470#define CFG_SEC(name, opts, flags) \ 471 {name,CFGT_SEC,0,0,flags,opts,{0,0,cfg_false,0,0},0,0,0,0,0,0} 472 473 474 475/** Initialize a function 476 * @param name The name of the option 477 * @param func The callback function. 478 * 479 * @see cfg_func_t 480 */ 481#define CFG_FUNC(name, func) \ 482 {name,CFGT_FUNC,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},func,0,0,0,0,0} 483 484 485#define __CFG_PTR(name, def, flags, svalue, parsecb, freecb) \ 486 {name,CFGT_PTR,0,0,flags,0,{0,0,cfg_false,0,def},0,svalue,parsecb,0,0,freecb} 487#define __CFG_PTR_LIST(name, def, flags, svalue, parsecb, freecb) \ 488 {name,CFGT_PTR,0,0,flags | CFGF_LIST,0,{0,0,cfg_false,0,def},0,svalue,parsecb,0,0,freecb} 489 490/** Initialize a user-defined option 491 * 492 * CFG_PTR options can only be used together with a value parsing callback. 493 * 494 * @param name The name of the option 495 * @param def Default value 496 * @param flags Flags 497 * @param parsecb Value parsing callback 498 * @param freecb Memory release function 499 * 500 * @see cfg_callback_t, cfg_free_func_t 501 */ 502#define CFG_PTR_CB(name, def, flags, parsecb, freecb) \ 503 __CFG_PTR(name, def, flags, 0, parsecb, freecb) 504 505/** Initialize a list of user-defined options 506 */ 507#define CFG_PTR_LIST_CB(name, def, flags, parsecb, freecb) \ 508 __CFG_PTR(name, def, flags | CFGF_LIST, 0, parsecb, freecb) 509 510/*#define CFG_SIMPLE_PTR(name, svalue, cb) \ 511 __CFG_PTR(name, 0, 0, svalue, cb)*/ 512 513 514/** Terminate list of options. This must be the last initializer in 515 * the option list. 516 */ 517#define CFG_END() \ 518 {0,CFGT_NONE,0,0,CFGF_NONE,0,{0,0,cfg_false,0,0},0,0,0,0,0,0} 519 520 521 522/** Create and initialize a cfg_t structure. This should be the first function 523 * called when setting up the parsing of a configuration file. The options 524 * passed in the first parameter is initialized using the CFG_* initializers. 525 * The last option in the option array must be CFG_END(), unless you like 526 * segmentation faults. 527 * 528 * The options must no longer be defined in the same scope as where the cfg_xxx 529 * functions are used (since version 2.3). 530 * 531 * @param opts An arrary of options 532 * @param flags One or more flags (bitwise or'ed together). Currently only 533 * CFGF_NOCASE is available. Use 0 if no flags are needed. 534 * 535 * @return A configuration context structure. This pointer is passed 536 * to almost all other functions as the first parameter. 537 */ 538DLLIMPORT cfg_t * __export cfg_init(cfg_opt_t *opts, cfg_flag_t flags); 539 540/** Parse a configuration file. Tilde expansion is performed on the 541 * filename before it is opened. After a configuration file has been 542 * initialized (with cfg_init()) and parsed (with cfg_parse()), the 543 * values can be read with the cfg_getXXX functions. 544 * 545 * @param cfg The configuration file context as returned from cfg_init(). 546 * @param filename The name of the file to parse. 547 * 548 * @return On success, CFG_SUCCESS is returned. If the file couldn't 549 * be opened for reading, CFG_FILE_ERROR is returned. On all other 550 * errors, CFG_PARSE_ERROR is returned and cfg_error() was called with 551 * a descriptive error message. 552 */ 553DLLIMPORT int __export cfg_parse(cfg_t *cfg, const char *filename); 554 555/** Same as cfg_parse() above, but takes an already opened file as 556 * argument. Reading begins at the current position. After parsing, 557 * the position is not reset. The caller is responsible for closing 558 * the file. 559 * 560 * @param cfg The configuration file context as returned from cfg_init(). 561 * @param fp An open file stream. 562 * 563 * @see cfg_parse() 564 */ 565DLLIMPORT int __export cfg_parse_fp(cfg_t *cfg, FILE *fp); 566 567/** Same as cfg_parse() above, but takes a character buffer as 568 * argument. 569 * 570 * @param cfg The configuration file context as returned from cfg_init(). 571 * @param buf A zero-terminated string with configuration directives. 572 * 573 * @see cfg_parse() 574 */ 575DLLIMPORT int __export cfg_parse_buf(cfg_t *cfg, const char *buf); 576 577/** Free the memory allocated for the values of a given option. Only 578 * the values are freed, not the option itself (it is freed by cfg_free()). 579 * 580 * @see cfg_free() 581 */ 582DLLIMPORT void __export cfg_free_value(cfg_opt_t *opt); 583 584/** Free a cfg_t context. All memory allocated by the cfg_t context 585 * structure are freed, and can't be used in any further cfg_* calls. 586 */ 587DLLIMPORT void __export cfg_free(cfg_t *cfg); 588 589/** Install a user-defined error reporting function. 590 * @return The old error reporting function is returned. 591 */ 592DLLIMPORT cfg_errfunc_t __export cfg_set_error_function(cfg_t *cfg, 593 cfg_errfunc_t errfunc); 594 595/** Show a parser error. Any user-defined error reporting function is called. 596 * @see cfg_set_error_function 597 */ 598DLLIMPORT void __export cfg_error(cfg_t *cfg, const char *fmt, ...); 599 600/** Returns the value of an integer option, given a cfg_opt_t pointer. 601 * @param opt The option structure (eg, as returned from cfg_getopt()) 602 * @param index Index of the value to get. Zero based. 603 * @see cfg_getnint 604 */ 605DLLIMPORT signed long __export cfg_opt_getnint(cfg_opt_t *opt, unsigned int index); 606 607/** Indexed version of cfg_getint(), used for lists. 608 * @param cfg The configuration file context. 609 * @param name The name of the option. 610 * @param index Index of the value to get. Zero based. 611 * @see cfg_getint 612 */ 613DLLIMPORT long int __export cfg_getnint(cfg_t *cfg, const char *name, 614 unsigned int index); 615 616/** Returns the value of an integer option. This is the same as 617 * calling cfg_getnint with index 0. 618 * @param cfg The configuration file context. 619 * @param name The name of the option. 620 * @return The requested value is returned. If the option was not set 621 * in the configuration file, the default value given in the 622 * corresponding cfg_opt_t structure is returned. It is an error to 623 * try to get an option that isn't declared. 624 */ 625DLLIMPORT long int __export cfg_getint(cfg_t *cfg, const char *name); 626 627/** Returns the value of a floating point option, given a cfg_opt_t pointer. 628 * @param opt The option structure (eg, as returned from cfg_getopt()) 629 * @param index Index of the value to get. Zero based. 630 * @see cfg_getnfloat 631 */ 632DLLIMPORT double __export cfg_opt_getnfloat(cfg_opt_t *opt, unsigned int index); 633 634/** Indexed version of cfg_getfloat(), used for lists. 635 * @param cfg The configuration file context. 636 * @param name The name of the option. 637 * @param index Index of the value to get. Zero based. 638 * @see cfg_getfloat 639 */ 640DLLIMPORT double __export cfg_getnfloat(cfg_t *cfg, const char *name, 641 unsigned int index); 642 643/** Returns the value of a floating point option. 644 * @param cfg The configuration file context. 645 * @param name The name of the option. 646 * @return The requested value is returned. If the option was not set 647 * in the configuration file, the default value given in the 648 * corresponding cfg_opt_t structure is returned. It is an error to 649 * try to get an option that isn't declared. 650 */ 651DLLIMPORT double __export cfg_getfloat(cfg_t *cfg, const char *name); 652 653/** Returns the value of a string option, given a cfg_opt_t pointer. 654 * @param opt The option structure (eg, as returned from cfg_getopt()) 655 * @param index Index of the value to get. Zero based. 656 * @see cfg_getnstr 657 */ 658DLLIMPORT char * __export cfg_opt_getnstr(cfg_opt_t *opt, unsigned int index); 659 660/** Indexed version of cfg_getstr(), used for lists. 661 * @param cfg The configuration file context. 662 * @param name The name of the option. 663 * @param index Index of the value to get. Zero based. 664 * @see cfg_getstr 665 */ 666DLLIMPORT char * __export cfg_getnstr(cfg_t *cfg, const char *name, 667 unsigned int index); 668 669/** Returns the value of a string option. 670 * @param cfg The configuration file context. 671 * @param name The name of the option. 672 * @return The requested value is returned. If the option was not set 673 * in the configuration file, the default value given in the 674 * corresponding cfg_opt_t structure is returned. It is an error to 675 * try to get an option that isn't declared. 676 */ 677DLLIMPORT char * __export cfg_getstr(cfg_t *cfg, const char *name); 678 679/** Returns the value of a boolean option, given a cfg_opt_t pointer. 680 * @param opt The option structure (eg, as returned from cfg_getopt()) 681 * @param index Index of the value to get. Zero based. 682 * @see cfg_getnbool 683 */ 684DLLIMPORT cfg_bool_t __export cfg_opt_getnbool(cfg_opt_t *opt, unsigned int index); 685 686/** Indexed version of cfg_getbool(), used for lists. 687 * 688 * @param cfg The configuration file context. 689 * @param name The name of the option. 690 * @param index Index of the value to get. Zero based. 691 * @see cfg_getbool 692 */ 693DLLIMPORT cfg_bool_t __export cfg_getnbool(cfg_t *cfg, const char *name, 694 unsigned int index); 695 696/** Returns the value of a boolean option. 697 * @param cfg The configuration file context. 698 * @param name The name of the option. 699 * @return The requested value is returned. If the option was not set 700 * in the configuration file, the default value given in the 701 * corresponding cfg_opt_t structure is returned. It is an error to 702 * try to get an option that isn't declared. 703 */ 704DLLIMPORT cfg_bool_t __export cfg_getbool(cfg_t *cfg, const char *name); 705 706 707DLLIMPORT void * __export cfg_opt_getnptr(cfg_opt_t *opt, unsigned int index); 708DLLIMPORT void * __export cfg_getnptr(cfg_t *cfg, const char *name, unsigned int indx); 709 710/** Returns the value of a user-defined option (void pointer). 711 * @param cfg The configuration file context. 712 * @param name The name of the option. 713 * @return The requested value is returned. If the option was not set 714 * in the configuration file, the default value given in the 715 * corresponding cfg_opt_t structure is returned. It is an error to 716 * try to get an option that isn't declared. 717 */ 718DLLIMPORT void * __export cfg_getptr(cfg_t *cfg, const char *name); 719 720 721/** Returns the value of a section option, given a cfg_opt_t pointer. 722 * @param opt The option structure (eg, as returned from cfg_getopt()) 723 * @param index Index of the value to get. Zero based. 724 * @see cfg_getnsec 725 */ 726DLLIMPORT cfg_t * __export cfg_opt_getnsec(cfg_opt_t *opt, unsigned int index); 727 728/** Indexed version of cfg_getsec(), used for sections with the 729 * CFGF_MULTI flag set. 730 * 731 * @param cfg The configuration file context. 732 * @param name The name of the option. 733 * @param index Index of the section to get. Zero based. 734 * @see cfg_getsec 735 */ 736DLLIMPORT cfg_t * __export cfg_getnsec(cfg_t *cfg, const char *name, 737 unsigned int index); 738 739/** Returns the value of a section option, given a cfg_opt_t pointer 740 * and the title. 741 * @param opt The option structure (eg, as returned from cfg_getopt()) 742 * @param title The title of this section. The CFGF_TITLE flag must 743 * have been set for this option. 744 * @see cfg_gettsec 745 */ 746DLLIMPORT cfg_t * __export cfg_opt_gettsec(cfg_opt_t *opt, const char *title); 747 748/** Return a section given the title, used for section with the 749 * CFGF_TITLE flag set. 750 * 751 * @param cfg The configuration file context. 752 * @param name The name of the option. 753 * @param title The title of this section. The CFGF_TITLE flag must 754 * have been set for this option. 755 * @see cfg_getsec 756 */ 757DLLIMPORT cfg_t * __export cfg_gettsec(cfg_t *cfg, const char *name, 758 const char *title); 759 760/** Returns the value of a section option. The returned value is 761 * another cfg_t structure that can be used in following calls to 762 * cfg_getint, cfg_getstr or other get-functions. 763 * @param cfg The configuration file context. 764 * @param name The name of the option. 765 * @return The requested section is returned. If no section is found 766 * with that name, 0 is returned. There can only be default values for 767 * section without the CFGF_MULTI flag set. It is an error to try to 768 * get a section that isn't declared. 769 */ 770DLLIMPORT cfg_t * __export cfg_getsec(cfg_t *cfg, const char *name); 771 772/** Return the number of values this option has. If no default value 773 * is given for the option and no value was found in the config file, 774 * 0 will be returned (ie, the option value is not set at all). 775 * @param opt The option structure (eg, as returned from cfg_getopt()) 776 */ 777DLLIMPORT unsigned int __export cfg_opt_size(cfg_opt_t *opt); 778 779/** Return the number of values this option has. If no default value 780 * is given for the option and no value was found in the config file, 781 * 0 will be returned (ie, the option value is not set at all). 782 * 783 * Note that there is no way to *not* specify a default value for integers, 784 * floats and booleans. Ie, they always have default values (since 0 or NULL is 785 * a valid integer/float/boolean value). Only strings and lists may have no 786 * default value. 787 * 788 * @param cfg The configuration file context. 789 * @param name The name of the option. 790 */ 791DLLIMPORT unsigned int __export cfg_size(cfg_t *cfg, const char *name); 792 793/** Return the title of a section. 794 * 795 * @param cfg The configuration file context. 796 * @return Returns the title, or 0 if there is no title. This string 797 * should not be modified. 798 */ 799DLLIMPORT const char * __export cfg_title(cfg_t *cfg); 800 801/** Return the name of a section. 802 * 803 * @param cfg The configuration file context. 804 * @return Returns the title, or 0 if there is no title. This string 805 * should not be modified. 806 */ 807DLLIMPORT const char * __export cfg_name(cfg_t *cfg); 808 809/** Return the name of an option. 810 * 811 * @param opt The option structure (eg, as returned from cfg_getopt()) 812 * @return Returns the title, or 0 if there is no title. This string 813 * should not be modified. 814 */ 815DLLIMPORT const char * __export cfg_opt_name(cfg_opt_t *opt); 816 817/** Predefined include-function. This function can be used in the 818 * options passed to cfg_init() to specify a function for including 819 * other configuration files in the parsing. For example: 820 * CFG_FUNC("include", &cfg_include) 821 */ 822DLLIMPORT int __export cfg_include(cfg_t *cfg, cfg_opt_t *opt, int argc, 823 const char **argv); 824 825/** Does tilde expansion (~ -> $HOME) on the filename. 826 * @return The expanded filename is returned. If a ~user was not 827 * found, the original filename is returned. In any case, a 828 * dynamically allocated string is returned, which should be free()'d 829 * by the caller. 830 */ 831DLLIMPORT char * __export cfg_tilde_expand(const char *filename); 832 833/** Parse a boolean option string. Accepted "true" values are "true", 834 * "on" and "yes", and accepted "false" values are "false", "off" and 835 * "no". 836 * 837 * @return Returns 1 or 0 (true/false) if the string was parsed 838 * correctly, or -1 if an error occurred. 839 */ 840DLLIMPORT int __export cfg_parse_boolean(const char *s); 841 842/** Return an option given it's name. 843 * 844 * @param cfg The configuration file context. 845 * @param name The name of the option. 846 * 847 * @return Returns a pointer to the option. If the option isn't declared, 848 * libConfuse will print an error message and return 0. 849 */ 850DLLIMPORT cfg_opt_t * __export cfg_getopt(cfg_t *cfg, const char *name); 851 852/** Set an option (create an instance of an option). 853 * 854 * @param cfg The configuration file context. 855 * @param opt The option definition. 856 * @param value The initial value for the option. 857 * 858 * @return Returns a pointer to the value object. 859 */ 860DLLIMPORT cfg_value_t *cfg_setopt(cfg_t *cfg, cfg_opt_t *opt, char *value); 861 862/** Set a value of an integer option. 863 * 864 * @param opt The option structure (eg, as returned from cfg_getopt()) 865 * @param value The value to set. 866 * @param index The index in the option value array that should be 867 * modified. It is an error to set values with indices larger than 0 868 * for options without the CFGF_LIST flag set. 869 */ 870DLLIMPORT void __export cfg_opt_setnint(cfg_opt_t *opt, 871 long int value, unsigned int index); 872 873/** Set the value of an integer option given its name. 874 * 875 * @param cfg The configuration file context. 876 * @param name The name of the option. 877 * @param value The value to set. If the option is a list (the CFGF_LIST flag 878 * is set), only the first value (with index 0) is set. 879 */ 880DLLIMPORT void __export cfg_setint(cfg_t *cfg, const char *name, 881 long int value); 882 883/** Set a value of an integer option given its name and index. 884 * 885 * @param cfg The configuration file context. 886 * @param name The name of the option. 887 * @param value The value to set. 888 * @param index The index in the option value array that should be 889 * modified. It is an error to set values with indices larger than 0 890 * for options without the CFGF_LIST flag set. 891 */ 892DLLIMPORT void __export cfg_setnint(cfg_t *cfg, const char *name, 893 long int value, unsigned int index); 894 895/** Set a value of a floating point option. 896 * 897 * @param opt The option structure (eg, as returned from cfg_getopt()) 898 * @param value The value to set. 899 * @param index The index in the option value array that should be 900 * modified. It is an error to set values with indices larger than 0 901 * for options without the CFGF_LIST flag set. 902 */ 903DLLIMPORT void __export cfg_opt_setnfloat(cfg_opt_t *opt, 904 double value, unsigned int index); 905 906/** Set the value of a floating point option given its name. 907 * 908 * @param cfg The configuration file context. 909 * @param name The name of the option. 910 * @param value The value to set. If the option is a list (the CFGF_LIST flag 911 * is set), only the first value (with index 0) is set. 912 */ 913DLLIMPORT void __export cfg_setfloat(cfg_t *cfg, const char *name, 914 double value); 915 916/** Set a value of a floating point option given its name and index. 917 * 918 * @param cfg The configuration file context. 919 * @param name The name of the option. 920 * @param value The value to set. 921 * @param index The index in the option value array that should be 922 * modified. It is an error to set values with indices larger than 0 923 * for options without the CFGF_LIST flag set. 924 */ 925DLLIMPORT void __export cfg_setnfloat(cfg_t *cfg, const char *name, 926 double value, unsigned int index); 927 928/** Set a value of a boolean option. 929 * 930 * @param opt The option structure (eg, as returned from cfg_getopt()) 931 * @param value The value to set. 932 * @param index The index in the option value array that should be 933 * modified. It is an error to set values with indices larger than 0 934 * for options without the CFGF_LIST flag set. 935 */ 936DLLIMPORT void __export cfg_opt_setnbool(cfg_opt_t *opt, 937 cfg_bool_t value, unsigned int index); 938 939/** Set the value of a boolean option given its name. 940 * 941 * @param cfg The configuration file context. 942 * @param name The name of the option. 943 * @param value The value to set. If the option is a list (the CFGF_LIST flag 944 * is set), only the first value (with index 0) is set. 945 */ 946DLLIMPORT void __export cfg_setbool(cfg_t *cfg, const char *name, 947 cfg_bool_t value); 948 949/** Set a value of a boolean option given its name and index. 950 * 951 * @param cfg The configuration file context. 952 * @param name The name of the option. 953 * @param value The value to set. 954 * @param index The index in the option value array that should be 955 * modified. It is an error to set values with indices larger than 0 956 * for options without the CFGF_LIST flag set. 957 */ 958DLLIMPORT void __export cfg_setnbool(cfg_t *cfg, const char *name, 959 cfg_bool_t value, unsigned int index); 960 961/** Set a value of a string option. 962 * 963 * @param opt The option structure (eg, as returned from cfg_getopt()) 964 * @param value The value to set. Memory for the string is allocated 965 * and the value is copied. Any previous string value is freed. 966 * @param index The index in the option value array that should be 967 * modified. It is an error to set values with indices larger than 0 968 * for options without the CFGF_LIST flag set. 969 */ 970DLLIMPORT void __export cfg_opt_setnstr(cfg_opt_t *opt, 971 const char *value, unsigned int index); 972 973/** Set the value of a string option given its name. 974 * 975 * @param cfg The configuration file context. 976 * @param name The name of the option. 977 * @param value The value to set. Memory for the string is allocated and the 978 * value is copied. Any previous string value is freed. If the option is a list 979 * (the CFGF_LIST flag is set), only the first value (with index 0) is set. 980 */ 981DLLIMPORT void __export cfg_setstr(cfg_t *cfg, const char *name, 982 const char *value); 983 984/** Set a value of a boolean option given its name and index. 985 * 986 * @param cfg The configuration file context. 987 * @param name The name of the option. 988 * @param value The value to set. Memory for the string is allocated 989 * and the value is copied. Any privious string value is freed. 990 * @param index The index in the option value array that should be 991 * modified. It is an error to set values with indices larger than 0 992 * for options without the CFGF_LIST flag set. 993 */ 994DLLIMPORT void __export cfg_setnstr(cfg_t *cfg, const char *name, 995 const char *value, unsigned int index); 996 997/** Set values for a list option. All existing values are replaced 998 * with the new ones. 999 * 1000 * @param cfg The configuration file context. 1001 * @param name The name of the option. 1002 * @param nvalues Number of values to set. 1003 * @param ... The values to set, the type must match the type of the 1004 * option and the number of values must be equal to the nvalues 1005 * parameter. 1006 */ 1007DLLIMPORT void __export cfg_setlist(cfg_t *cfg, const char *name, 1008 unsigned int nvalues, ...); 1009 1010DLLIMPORT int __export cfg_numopts(cfg_opt_t *opts); 1011 1012/** Add values for a list option. The new values are appended to any 1013 * current values in the list. 1014 * 1015 * @param cfg The configuration file context. 1016 * @param name The name of the option. 1017 * @param nvalues Number of values to add. 1018 * @param ... The values to add, the type must match the type of the 1019 * option and the number of values must be equal to the nvalues 1020 * parameter. 1021 */ 1022DLLIMPORT void __export cfg_addlist(cfg_t *cfg, const char *name, 1023 unsigned int nvalues, ...); 1024 1025/** Default value print function. 1026 * 1027 * Print only the value of a given option. Does not handle sections or 1028 * functions. Use cfg_opt_print to print the whole assignment ("option 1029 * = value"), or cfg_print to print the whole config file. 1030 * 1031 * @param opt The option structure (eg, as returned from cfg_getopt()) 1032 * @param index The index in the option value array that should be printed 1033 * @param fp File stream to print to. 1034 * 1035 * @see cfg_print, cfg_opt_print 1036 */ 1037DLLIMPORT void __export cfg_opt_nprint_var(cfg_opt_t *opt, unsigned int index, 1038 FILE *fp); 1039 1040/** Print an option and its value to a file. 1041 * Same as cfg_opt_print, but with the indentation level specified. 1042 * @see cfg_opt_print 1043 */ 1044DLLIMPORT void __export cfg_opt_print_indent(cfg_opt_t *opt, FILE *fp, int indent); 1045 1046/** Print an option and its value to a file. 1047 * 1048 * If a print callback function is specified for the option, it is 1049 * used instead of cfg_opt_nprint_var. 1050 * 1051 * @param opt The option structure (eg, as returned from cfg_getopt()) 1052 * @param fp File stream to print to. 1053 * 1054 * @see cfg_print_func_t 1055 */ 1056DLLIMPORT void __export cfg_opt_print(cfg_opt_t *opt, FILE *fp); 1057 1058/** Print the options and values to a file. 1059 * Same as cfg_print, but with the indentation level specified. 1060 * @see cfg_print 1061 */ 1062DLLIMPORT void __export cfg_print_indent(cfg_t *cfg, FILE *fp, int indent); 1063 1064/** Print the options and values to a file. 1065 * 1066 * Note that options in any included file are expanded and printed 1067 * directly to the file. Option values given with environment 1068 * variables in the parsed input are also printed expanded. This means 1069 * that if you parse a configuration file you can't expect that the 1070 * output from this function is identical to the initial file. 1071 * 1072 * @param cfg The configuration file context. 1073 * @param fp File stream to print to, use stdout to print to the screen. 1074 * 1075 * @see cfg_print_func_t, cfg_set_print_func 1076 */ 1077DLLIMPORT void __export cfg_print(cfg_t *cfg, FILE *fp); 1078 1079/** Set a print callback function for an option. 1080 * 1081 * @param opt The option structure (eg, as returned from cfg_getopt()) 1082 * @param pf The print function callback. 1083 * 1084 * @see cfg_print_func_t 1085 */ 1086DLLIMPORT cfg_print_func_t __export cfg_opt_set_print_func(cfg_opt_t *opt, 1087 cfg_print_func_t pf); 1088 1089/** Set a print callback function for an option given its name. 1090 * 1091 * @param cfg The configuration file context. 1092 * @param name The name of the option. 1093 * @param pf The print callback function. 1094 * 1095 * @see cfg_print_func_t 1096 */ 1097DLLIMPORT cfg_print_func_t __export cfg_set_print_func(cfg_t *cfg, const char *name, 1098 cfg_print_func_t pf); 1099 1100/** Register a validating callback function for an option. 1101 * 1102 * @param cfg The configuration file context. 1103 * @param name The name of the option. 1104 * @param vf The validating callback function. 1105 * 1106 * @see cfg_validate_callback_t 1107 */ 1108DLLIMPORT cfg_validate_callback_t __export cfg_set_validate_func(cfg_t *cfg, 1109 const char *name, 1110 cfg_validate_callback_t vf); 1111 1112#ifdef __cplusplus 1113} 1114#endif 1115 1116#endif 1117 1118/** @example ftpconf.c 1119 */ 1120 1121/** @example simple.c 1122 */ 1123 1124/** @example reread.c 1125 */ 1126