---
name: "confuse.h"
section: "3"
platform: "linux"
package: "libconfuse-doc"
version: "3.3-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/confuse.h"
---

# confuse.h(3)

A configuration file parser library.

## NAME

confuse.h - A configuration file parser library.

## SYNOPSIS

`#include <stdio.h>`\
 `#include <stdarg.h>`\

### Data Structures

struct **cfg\_t**\
 Data structure holding information about a 'section'.  union **cfg\_value\_t**\
 Data structure holding the value of a fundamental option value.  union **cfg\_simple\_t**\
 Data structure holding the pointer to a user provided variable defined with CFG\_SIMPLE\_\*.  struct **cfg\_defvalue\_t**\
 Data structure holding the default value given by the initialization macros.  struct **cfg\_opt\_t**\
 Data structure holding information about an option.

### Macros

\#define **CFGF\_NONE**   (0)\
 Flags.  #define **CFGF\_MULTI**   (1 \<\<  0)\
 option may be specified multiple times (only applies to sections)  #define **CFGF\_LIST**   (1 \<\<  1)\
 option is a list  #define **CFGF\_NOCASE**   (1 \<\<  2)\
 configuration file is case insensitive  #define **CFGF\_TITLE**   (1 \<\<  3)\
 option has a title (only applies to sections)  #define **CFGF\_NODEFAULT**   (1 \<\<  4)\
 option has no default value  #define **CFGF\_NO\_TITLE\_DUPES**   (1 \<\<  5)\
 multiple section titles must be unique (duplicates raises an error, only applies to sections)  #define **CFGF\_IGNORE\_UNKNOWN**   (1 \<\<  8)\
 ignore unknown options in configuration files  #define **CFGF\_DEPRECATED**   (1 \<\<  9)\
 option is deprecated and should be ignored.  #define **CFGF\_DROP**   (1 \<\< 10)\
 option should be dropped after parsing  #define **CFGF\_COMMENTS**   (1 \<\< 11)\
 Enable option annotation/comments support.  #define **CFGF\_MODIFIED**   (1 \<\< 12)\
 option has been changed from its default value  #define **CFGF\_KEYSTRVAL**   (1 \<\< 13)\
 section has free-form key=value string options created when parsing file  #define **CFG\_SUCCESS**   0\
 Return codes from **cfg\_parse()**, **cfg\_parse\_boolean()**, and cfg\_set\*() functions.  #define **CFG\_STR**(name,  def,  flags)     \_\_CFG\_STR(name, def, flags, 0, 0)\
 Initialize a string option.  #define **CFG\_STR\_LIST**(name,  def,  flags)     \_\_CFG\_STR\_LIST(name, def, flags, 0, 0)\
 Initialize a string list option.  #define **CFG\_STR\_CB**(name,  def,  flags,  cb)     \_\_CFG\_STR(name, def, flags, 0, cb)\
 Initialize a string option with a value parsing callback.  #define **CFG\_STR\_LIST\_CB**(name,  def,  flags,  cb)     \_\_CFG\_STR\_LIST(name, def, flags, 0, cb)\
 Initialize a string list option with a value parsing callback.  #define **CFG\_SIMPLE\_STR**(name,  svalue)     \_\_CFG\_STR(name, 0, **CFGF\_NONE**, svalue, 0)\
 Initialize a 'simple' string option.  #define **CFG\_INT**(name,  def,  flags)     \_\_CFG\_INT(name, def, flags, 0, 0)\
 Initialize an integer option.  #define **CFG\_INT\_LIST**(name,  def,  flags)     \_\_CFG\_INT\_LIST(name, def, flags, 0, 0)\
 Initialize an integer list option.  #define **CFG\_INT\_CB**(name,  def,  flags,  cb)     \_\_CFG\_INT(name, def, flags, 0, cb)\
 Initialize an integer option with a value parsing callback.  #define **CFG\_INT\_LIST\_CB**(name,  def,  flags,  cb)     \_\_CFG\_INT\_LIST(name, def, flags, 0, cb)\
 Initialize an integer list option with a value parsing callback.  #define **CFG\_SIMPLE\_INT**(name,  svalue)     \_\_CFG\_INT(name, 0, **CFGF\_NONE**, svalue, 0)\
 Initialize a 'simple' integer option (see documentation for CFG\_SIMPLE\_STR for more information).  #define **CFG\_FLOAT**(name,  def,  flags)     \_\_CFG\_FLOAT(name, def, flags, 0, 0)\
 Initialize a floating point option.  #define **CFG\_FLOAT\_LIST**(name,  def,  flags)     \_\_CFG\_FLOAT\_LIST(name, def, flags, 0, 0)\
 Initialize a floating point list option.  #define **CFG\_FLOAT\_CB**(name,  def,  flags,  cb)     \_\_CFG\_FLOAT(name, def, flags, 0, cb)\
 Initialize a floating point option with a value parsing callback.  #define **CFG\_FLOAT\_LIST\_CB**(name,  def,  flags,  cb)     \_\_CFG\_FLOAT\_LIST(name, def, flags, 0, cb)\
 Initialize a floating point list option with a value parsing callback.  #define **CFG\_SIMPLE\_FLOAT**(name,  svalue)     \_\_CFG\_FLOAT(name, 0, **CFGF\_NONE**, svalue, 0)\
 Initialize a 'simple' floating point option (see documentation for CFG\_SIMPLE\_STR for more information).  #define **CFG\_BOOL**(name,  def,  flags)     \_\_CFG\_BOOL(name, def, flags, 0, 0)\
 Initialize a boolean option.  #define **CFG\_BOOL\_LIST**(name,  def,  flags)     \_\_CFG\_BOOL\_LIST(name, def, flags, 0, 0)\
 Initialize a boolean list option.  #define **CFG\_BOOL\_CB**(name,  def,  flags,  cb)     \_\_CFG\_BOOL(name, def, flags, 0, cb)\
 Initialize a boolean option with a value parsing callback.  #define **CFG\_BOOL\_LIST\_CB**(name,  def,  flags,  cb)     \_\_CFG\_BOOL\_LIST(name, def, flags, 0, cb)\
 Initialize a boolean list option with a value parsing callback.  #define **CFG\_SIMPLE\_BOOL**(name,  svalue)     \_\_CFG\_BOOL(name, cfg\_false, **CFGF\_NONE**, svalue, 0)\
 Initialize a 'simple' boolean option (see documentation for CFG\_SIMPLE\_STR for more information).  #define **CFG\_SEC**(name,  opts,  flags)     {name,0,**CFGT\_SEC**,0,0,flags,opts,{0,0,cfg\_false,0,0},0,{0},0,0,0,0,0}\
 Initialize a section.  #define **CFG\_FUNC**(name,  func)     {name,0,**CFGT\_FUNC**,0,0,**CFGF\_NONE**,0,{0,0,cfg\_false,0,0},func,{0},0,0,0,0,0}\
 Initialize a function.  #define **CFG\_PTR\_CB**(name,  def,  flags,  parsecb,  freecb)     \_\_CFG\_PTR(name, def, flags, 0, parsecb, freecb)\
 Initialize a user-defined option.  #define **CFG\_PTR\_LIST\_CB**(name,  def,  flags,  parsecb,  freecb)     \_\_CFG\_PTR(name, def, flags \| **CFGF\_LIST**, 0, parsecb, freecb)\
 Initialize a list of user-defined options.  #define **CFG\_END**()     {0,0,CFGT\_NONE,0,0,**CFGF\_NONE**,0,{0,0,cfg\_false,0,0},0,{0},0,0,0,0,0}\
 Terminate list of options.

### Typedefs

typedef int(\* **cfg\_func\_t**) (**cfg\_t** \*cfg, **cfg\_opt\_t** \*opt, int argc, const char \*\*argv)\
 Function prototype used by CFGT\_FUNC options.  typedef void(\* **cfg\_print\_func\_t**) (**cfg\_opt\_t** \*opt, unsigned int index, FILE \*fp)\
 Function prototype used by the cfg\_print\_ functions.  typedef int(\* **cfg\_callback\_t**) (**cfg\_t** \*cfg, **cfg\_opt\_t** \*opt, const char \*value, void \*result)\
 Value parsing callback prototype.  typedef int(\* **cfg\_validate\_callback\_t**) (**cfg\_t** \*cfg, **cfg\_opt\_t** \*opt)\
 Validating callback prototype.  typedef int(\* **cfg\_validate\_callback2\_t**) (**cfg\_t** \*cfg, **cfg\_opt\_t** \*opt, void \*value)\
 Validating callback2 prototype.  typedef void(\* **cfg\_free\_func\_t**) (void \*value)\
 User-defined memory release function for CFG\_PTR values.  typedef void(\* **cfg\_errfunc\_t**) (**cfg\_t** \*cfg, const char \*fmt, va\_list ap)\
 Error reporting function.  typedef int(\* **cfg\_print\_filter\_func\_t**) (**cfg\_t** \*cfg, **cfg\_opt\_t** \*opt)\
 Print filter function.

### Enumerations

enum **cfg\_type\_t** {  }\
 Fundamental option types.  enum **cfg\_bool\_t** \
 Boolean values.

### Functions

DLLIMPORT **cfg\_t** \*\_\_export **cfg\_init** (**cfg\_opt\_t** \*opts, cfg\_flag\_t flags)\
 Create and initialize a **cfg\_t** structure.  DLLIMPORT int \_\_export **cfg\_add\_searchpath** (**cfg\_t** \*cfg, const char \*dir)\
 Add a searchpath directory to the configuration context, the const char\* argument will be duplicated and then freed as part of the usual context takedown.  DLLIMPORT char \*\_\_export **cfg\_searchpath** (cfg\_searchpath\_t \*path, const char \*file)\
 Search the linked-list of cfg\_searchpath\_t for the specified file.  DLLIMPORT int \_\_export **cfg\_parse** (**cfg\_t** \*cfg, const char \*filename)\
 Parse a configuration file.  DLLIMPORT int \_\_export **cfg\_parse\_fp** (**cfg\_t** \*cfg, FILE \*fp)\
 Same as **cfg\_parse()** above, but takes an already opened file as argument.  DLLIMPORT int \_\_export **cfg\_parse\_buf** (**cfg\_t** \*cfg, const char \*buf)\
 Same as **cfg\_parse()** above, but takes a character buffer as argument.  DLLIMPORT int \_\_export **cfg\_free\_value** (**cfg\_opt\_t** \*opt)\
 Free the memory allocated for the values of a given option.  DLLIMPORT int \_\_export **cfg\_free** (**cfg\_t** \*cfg)\
 Free a **cfg\_t** context.  DLLIMPORT **cfg\_errfunc\_t** \_\_export **cfg\_set\_error\_function** (**cfg\_t** \*cfg, **cfg\_errfunc\_t** errfunc)\
 Install a user-defined error reporting function.  DLLIMPORT void \_\_export **cfg\_error** (**cfg\_t** \*cfg, const char \*fmt,...)\
 Show a parser error.  DLLIMPORT char \*\_\_export **cfg\_opt\_getcomment** (**cfg\_opt\_t** \*opt)\
 Returns the option comment.  DLLIMPORT char \*\_\_export **cfg\_getcomment** (**cfg\_t** \*cfg, const char \*name)\
 Returns the option comment.  DLLIMPORT signed long \_\_export **cfg\_opt\_getnint** (**cfg\_opt\_t** \*opt, unsigned int index)\
 Returns the value of an integer option, given a **cfg\_opt\_t** pointer.  DLLIMPORT long int \_\_export **cfg\_getnint** (**cfg\_t** \*cfg, const char \*name, unsigned int index)\
 Indexed version of **cfg\_getint()**, used for lists.  DLLIMPORT long int \_\_export **cfg\_getint** (**cfg\_t** \*cfg, const char \*name)\
 Returns the value of an integer option.  DLLIMPORT double \_\_export **cfg\_opt\_getnfloat** (**cfg\_opt\_t** \*opt, unsigned int index)\
 Returns the value of a floating point option, given a **cfg\_opt\_t** pointer.  DLLIMPORT double \_\_export **cfg\_getnfloat** (**cfg\_t** \*cfg, const char \*name, unsigned int index)\
 Indexed version of **cfg\_getfloat()**, used for lists.  DLLIMPORT double \_\_export **cfg\_getfloat** (**cfg\_t** \*cfg, const char \*name)\
 Returns the value of a floating point option.  DLLIMPORT char \*\_\_export **cfg\_opt\_getnstr** (**cfg\_opt\_t** \*opt, unsigned int index)\
 Returns the value of a string option, given a **cfg\_opt\_t** pointer.  DLLIMPORT char \*\_\_export **cfg\_getnstr** (**cfg\_t** \*cfg, const char \*name, unsigned int index)\
 Indexed version of **cfg\_getstr()**, used for lists.  DLLIMPORT char \*\_\_export **cfg\_getstr** (**cfg\_t** \*cfg, const char \*name)\
 Returns the value of a string option.  DLLIMPORT **cfg\_bool\_t** \_\_export **cfg\_opt\_getnbool** (**cfg\_opt\_t** \*opt, unsigned int index)\
 Returns the value of a boolean option, given a **cfg\_opt\_t** pointer.  DLLIMPORT **cfg\_bool\_t** \_\_export **cfg\_getnbool** (**cfg\_t** \*cfg, const char \*name, unsigned int index)\
 Indexed version of **cfg\_getbool()**, used for lists.  DLLIMPORT **cfg\_bool\_t** \_\_export **cfg\_getbool** (**cfg\_t** \*cfg, const char \*name)\
 Returns the value of a boolean option.  DLLIMPORT void \*\_\_export **cfg\_getptr** (**cfg\_t** \*cfg, const char \*name)\
 Returns the value of a user-defined option (void pointer).  DLLIMPORT **cfg\_t** \*\_\_export **cfg\_opt\_getnsec** (**cfg\_opt\_t** \*opt, unsigned int index)\
 Returns the value of a section option, given a **cfg\_opt\_t** pointer.  DLLIMPORT **cfg\_t** \*\_\_export **cfg\_getnsec** (**cfg\_t** \*cfg, const char \*name, unsigned int index)\
 Indexed version of **cfg\_getsec()**, used for sections with the CFGF\_MULTI flag set.  DLLIMPORT **cfg\_t** \*\_\_export **cfg\_opt\_gettsec** (**cfg\_opt\_t** \*opt, const char \*title)\
 Returns the value of a section option, given a **cfg\_opt\_t** pointer and the title.  DLLIMPORT **cfg\_t** \*\_\_export **cfg\_gettsec** (**cfg\_t** \*cfg, const char \*name, const char \*title)\
 Return a section given the title, used for section with the CFGF\_TITLE flag set.  DLLIMPORT **cfg\_t** \*\_\_export **cfg\_getsec** (**cfg\_t** \*cfg, const char \*name)\
 Returns the value of a section option.  DLLIMPORT unsigned int \_\_export **cfg\_opt\_size** (**cfg\_opt\_t** \*opt)\
 Return the number of values this option has.  DLLIMPORT unsigned int \_\_export **cfg\_size** (**cfg\_t** \*cfg, const char \*name)\
 Return the number of values this option has.  DLLIMPORT const char \*\_\_export **cfg\_title** (**cfg\_t** \*cfg)\
 Return the title of a section.  DLLIMPORT const char \*\_\_export **cfg\_name** (**cfg\_t** \*cfg)\
 Return the name of a section.  DLLIMPORT const char \*\_\_export **cfg\_opt\_name** (**cfg\_opt\_t** \*opt)\
 Return the name of an option.  DLLIMPORT const char \* **cfg\_opt\_getstr** (**cfg\_opt\_t** \*opt)\
 Return the string value of a key=value pair.  DLLIMPORT int \_\_export **cfg\_include** (**cfg\_t** \*cfg, **cfg\_opt\_t** \*opt, int argc, const char \*\*argv)\
 Predefined include-function.  DLLIMPORT char \*\_\_export **cfg\_tilde\_expand** (const char \*filename)\
 Does tilde expansion (~ -\> $HOME) on the filename.  DLLIMPORT int \_\_export **cfg\_parse\_boolean** (const char \*s)\
 Parse a boolean option string.  DLLIMPORT **cfg\_opt\_t** \* **cfg\_getnopt** (**cfg\_t** \*cfg, unsigned int index)\
 Return the nth option in a file or section.  DLLIMPORT **cfg\_opt\_t** \*\_\_export **cfg\_getopt** (**cfg\_t** \*cfg, const char \*name)\
 Return an option given it's name.  DLLIMPORT **cfg\_value\_t** \* **cfg\_setopt** (**cfg\_t** \*cfg, **cfg\_opt\_t** \*opt, const char \*value)\
 Set an option (create an instance of an option).  DLLIMPORT int \_\_export **cfg\_opt\_setcomment** (**cfg\_opt\_t** \*opt, char \*comment)\
 Annotate an option.  DLLIMPORT int \_\_export **cfg\_setcomment** (**cfg\_t** \*cfg, const char \*name, char \*comment)\
 Annotate an option given its name.  DLLIMPORT int \_\_export **cfg\_opt\_setnint** (**cfg\_opt\_t** \*opt, long int value, unsigned int index)\
 Set a value of an integer option.  DLLIMPORT int \_\_export **cfg\_setint** (**cfg\_t** \*cfg, const char \*name, long int value)\
 Set the value of an integer option given its name.  DLLIMPORT int \_\_export **cfg\_setnint** (**cfg\_t** \*cfg, const char \*name, long int value, unsigned int index)\
 Set a value of an integer option given its name and index.  DLLIMPORT int \_\_export **cfg\_opt\_setnfloat** (**cfg\_opt\_t** \*opt, double value, unsigned int index)\
 Set a value of a floating point option.  DLLIMPORT int \_\_export **cfg\_setfloat** (**cfg\_t** \*cfg, const char \*name, double value)\
 Set the value of a floating point option given its name.  DLLIMPORT int \_\_export **cfg\_setnfloat** (**cfg\_t** \*cfg, const char \*name, double value, unsigned int index)\
 Set a value of a floating point option given its name and index.  DLLIMPORT int \_\_export **cfg\_opt\_setnbool** (**cfg\_opt\_t** \*opt, **cfg\_bool\_t** value, unsigned int index)\
 Set a value of a boolean option.  DLLIMPORT int \_\_export **cfg\_setbool** (**cfg\_t** \*cfg, const char \*name, **cfg\_bool\_t** value)\
 Set the value of a boolean option given its name.  DLLIMPORT int \_\_export **cfg\_setnbool** (**cfg\_t** \*cfg, const char \*name, **cfg\_bool\_t** value, unsigned int index)\
 Set a value of a boolean option given its name and index.  DLLIMPORT int \_\_export **cfg\_opt\_setnstr** (**cfg\_opt\_t** \*opt, const char \*value, unsigned int index)\
 Set a value of a string option.  DLLIMPORT int \_\_export **cfg\_setstr** (**cfg\_t** \*cfg, const char \*name, const char \*value)\
 Set the value of a string option given its name.  DLLIMPORT int \_\_export **cfg\_setnstr** (**cfg\_t** \*cfg, const char \*name, const char \*value, unsigned int index)\
 Set a value of a boolean option given its name and index.  DLLIMPORT int \_\_export **cfg\_setlist** (**cfg\_t** \*cfg, const char \*name, unsigned int nvalues,...)\
 Set values for a list option.  DLLIMPORT unsigned int \_\_export **cfg\_num** (**cfg\_t** \*cfg)\
 Return number of options in a file or section.  DLLIMPORT int \_\_export **cfg\_addlist** (**cfg\_t** \*cfg, const char \*name, unsigned int nvalues,...)\
 Add values for a list option.  DLLIMPORT int **cfg\_opt\_setmulti** (**cfg\_t** \*cfg, **cfg\_opt\_t** \*opt, unsigned int nvalues, char \*\*values)\
 Set an option (create an instance of an option).  DLLIMPORT int **cfg\_setmulti** (**cfg\_t** \*cfg, const char \*name, unsigned int nvalues, char \*\*values)\
 Set an option (create an instance of an option).  DLLIMPORT **cfg\_t** \* **cfg\_addtsec** (**cfg\_t** \*cfg, const char \*name, const char \*title)\
 Create a new titled config section.  DLLIMPORT int \_\_export **cfg\_opt\_rmnsec** (**cfg\_opt\_t** \*opt, unsigned int index)\
 Removes and frees a config section, given a **cfg\_opt\_t** pointer.  DLLIMPORT int \_\_export **cfg\_rmnsec** (**cfg\_t** \*cfg, const char \*name, unsigned int index)\
 Indexed version of **cfg\_rmsec()**, used for CFGF\_MULTI sections.  DLLIMPORT int \_\_export **cfg\_rmsec** (**cfg\_t** \*cfg, const char \*name)\
 Removes and frees a config section.  DLLIMPORT int \_\_export **cfg\_opt\_rmtsec** (**cfg\_opt\_t** \*opt, const char \*title)\
 Removes and frees a config section, given a **cfg\_opt\_t** pointer and the title.  DLLIMPORT int \_\_export **cfg\_rmtsec** (**cfg\_t** \*cfg, const char \*name, const char \*title)\
 Removes and frees a section given the title, used for section with the CFGF\_TITLE flag set.  DLLIMPORT int \_\_export **cfg\_opt\_nprint\_var** (**cfg\_opt\_t** \*opt, unsigned int index, FILE \*fp)\
 Default value print function.  DLLIMPORT int \_\_export **cfg\_opt\_print\_indent** (**cfg\_opt\_t** \*opt, FILE \*fp, int indent)\
 Print an option and its value to a file.  DLLIMPORT int \_\_export **cfg\_opt\_print** (**cfg\_opt\_t** \*opt, FILE \*fp)\
 Print an option and its value to a file.  DLLIMPORT int \_\_export **cfg\_print\_indent** (**cfg\_t** \*cfg, FILE \*fp, int indent)\
 Print the options and values to a file.  DLLIMPORT int \_\_export **cfg\_print** (**cfg\_t** \*cfg, FILE \*fp)\
 Print the options and values to a file.  DLLIMPORT **cfg\_print\_func\_t** \_\_export **cfg\_opt\_set\_print\_func** (**cfg\_opt\_t** \*opt, **cfg\_print\_func\_t** pf)\
 Set a print callback function for an option.  DLLIMPORT **cfg\_print\_func\_t** \_\_export **cfg\_set\_print\_func** (**cfg\_t** \*cfg, const char \*name, **cfg\_print\_func\_t** pf)\
 Set a print callback function for an option given its name.  DLLIMPORT **cfg\_print\_filter\_func\_t** \_\_export **cfg\_set\_print\_filter\_func** (**cfg\_t** \*cfg, **cfg\_print\_filter\_func\_t** pff)\
 Install a user-defined print filter function.  DLLIMPORT **cfg\_validate\_callback\_t** \_\_export **cfg\_set\_validate\_func** (**cfg\_t** \*cfg, const char \*name, **cfg\_validate\_callback\_t** vf)\
 Register a validating callback function for an option.  DLLIMPORT **cfg\_validate\_callback2\_t** \_\_export **cfg\_set\_validate\_func2** (**cfg\_t** \*cfg, const char \*name, **cfg\_validate\_callback2\_t** vf)\
 Register a validating callback function for an option.

## Detailed Description

A configuration file parser library.

## Macro Definition Documentation

### #define CFG\_END() {0,0,CFGT\_NONE,0,0,CFGF\_NONE,0,{0,0,cfg\_false,0,0},0,{0},0,0,0,0,0}

Terminate list of options. This must be the last initializer in the option list.

**Examples** **ftpconf.c**, **reread.c**, and **simple.c**.

### #define CFG\_FUNC(name, func) {name,0,CFGT\_FUNC,0,0,CFGF\_NONE,0,{0,0,cfg\_false,0,0},func,{0},0,0,0,0,0}

Initialize a function.

**Parameters**

*name* The name of the option \
 *func* The callback function.

**See also**

**cfg\_func\_t**

**Examples** **ftpconf.c**.

### #define CFG\_PTR\_CB(name, def, flags, parsecb, freecb) \_\_CFG\_PTR(name, def, flags, 0, parsecb, freecb)

Initialize a user-defined option. CFG\_PTR options can only be used together with a value parsing callback.

**Parameters**

*name* The name of the option \
 *def* Default value \
 *flags* Flags \
 *parsecb* Value parsing callback \
 *freecb* Memory release function

**See also**

**cfg\_callback\_t**, **cfg\_free\_func\_t**

### #define CFG\_SEC(name, opts, flags) {name,0,CFGT\_SEC,0,0,flags,opts,{0,0,cfg\_false,0,0},0,{0},0,0,0,0,0}

Initialize a section.

**Parameters**

*name* The name of the option \
 *opts* Array of options that are valid within this section\
 *flags* Flags, specify CFGF\_MULTI if it should be possible to have multiples of the same section, and CFGF\_TITLE if the section(s) must have a title (which can be used in the **cfg\_gettsec()** function)

**Examples** **ftpconf.c**, and **reread.c**.

### #define CFG\_SIMPLE\_INT(name, svalue) \_\_CFG\_INT(name, 0, CFGF\_NONE, svalue, 0)

Initialize a 'simple' integer option (see documentation for CFG\_SIMPLE\_STR for more information). Note that confuse uses long integers, so make sure that any pointer you provide for svalue points to a long int rather than a normal int. Otherwise, you will have strange problems on 64-bit architectures.

**Examples** **simple.c**.

### #define CFG\_SIMPLE\_STR(name, svalue) \_\_CFG\_STR(name, 0, CFGF\_NONE, svalue, 0)

Initialize a 'simple' string option. 'Simple' options (in lack of a better expression) does not support lists of values or multiple sections. LibConfuse will store the value of a simple option in the user-defined location specified by the value parameter in the initializer. Simple options are not stored in the **cfg\_t** context, only a pointer. Sections can not be initialized as a 'simple' option.

As of version 2.2, libConfuse can now return the values of simple options with the cfg\_get functions. This allows using the new cfg\_print function with simple options.

libConfuse doesn't support handling default values for 'simple' options. They are assumed to be set by the calling application before cfg\_parse is called.

**Parameters**

*name* name of the option \
 *svalue* pointer to a character pointer (a char \*\*). This value must be initialized either to NULL or to a malloc()'ed string. You can't use

```
char *user = 'joe';
...
cfg_opt_t opts[] = {
    CFG_SIMPLE_STR('user', &user),
...
```

 since libConfuse will try to free the static string 'joe' (which is an error) when a 'user' option is found. Rather, use the following code snippet:

```
char *user = strdup('joe');
...
cfg_opt_t opts[] = {
     CFG_SIMPLE_STR('user', &user),
...
```

 Alternatively, the default value can be set after the opts struct is defined, as in:

```
char *user = 0;
...
cfg_opt_t opts[] = {
     CFG_SIMPLE_STR('user', &user),
...
user = strdup('joe');
cfg = cfg_init(opts, 0);
cfg_parse(cfg, filename);
```

**Examples** **simple.c**.

### #define CFG\_SUCCESS 0

Return codes from **cfg\_parse()**, **cfg\_parse\_boolean()**, and cfg\_set\*() functions.

**Examples** **ftpconf.c**, and **reread.c**.

### #define CFGF\_DEPRECATED (1 \<\< 9)

option is deprecated and should be ignored.

### #define CFGF\_NONE (0)

Flags.

**Examples** **ftpconf.c**, and **reread.c**.

## Typedef Documentation

### typedef int(\* cfg\_callback\_t) (cfg\_t \*cfg, cfg\_opt\_t \*opt, const char \*value, void \*result)

Value parsing callback prototype. This is a callback function (different from the one registered with the CFG\_FUNC initializer) used to parse a value. This can be used to override the internal parsing of a value.

Suppose you want an integer option that only can have certain values, for example 1, 2 and 3, and these should be written in the configuration file as 'yes', 'no' and 'maybe'. The callback function would be called with the found value ('yes', 'no' or 'maybe') as a string, and the result should be stored in the result parameter.

**Parameters**

*cfg* The configuration file context. \
 *opt* The option. \
 *value* The value found in the configuration file. \
 *result* Pointer to storage for the result, cast to a void pointer.

**Returns**

On success, 0 should be returned. All other values indicates an error, and the parsing is aborted. The callback function should notify the error itself, for example by calling **cfg\_error()**.

### typedef void(\* cfg\_errfunc\_t) (cfg\_t \*cfg, const char \*fmt, va\_list ap)

Error reporting function.

### typedef void(\* cfg\_free\_func\_t) (void \*value)

User-defined memory release function for CFG\_PTR values. This callback is used to free memory allocated in a value parsing callback function. Especially useful for CFG\_PTR options, since libConfuse will not itself release such values. If the values are simply allocated with a [malloc(3)](/malloc/3.md), one can use the standard [free(3)](/free/3.md) function here.

### typedef int(\* cfg\_func\_t) (cfg\_t \*cfg, cfg\_opt\_t \*opt, int argc, const char \*\*argv)

Function prototype used by CFGT\_FUNC options. This is a callback function, registered with the CFG\_FUNC initializer. Each time libConfuse finds a function, the registered callback function is called (parameters are passed as strings, any conversion to other types should be made in the callback function). libConfuse does not support any storage of the data found; these are passed as parameters to the callback, and it's the responsibility of the callback function to do whatever it should do with the data.

**Parameters**

*cfg* The configuration file context. \
 *opt* The option. \
 *argc* Number of arguments passed. The callback function is responsible for checking that the correct number of arguments are passed. \
 *argv* Arguments as an array of character strings.

**Returns**

On success, 0 should be returned. All other values indicates an error, and the parsing is aborted. The callback function should notify the error itself, for example by calling **cfg\_error()**.

**See also**

**CFG\_FUNC**

### typedef int(\* cfg\_print\_filter\_func\_t) (cfg\_t \*cfg, cfg\_opt\_t \*opt)

Print filter function.

**Parameters**

*cfg* The configuration file context that opt belongs to. \
 *opt* The configuration option that is about to be printed, or not.

**Returns**

Zero if opt should be printed, non-zero if it should be filtered out.

**See also**

**cfg\_set\_print\_filter\_func()**

### typedef void(\* cfg\_print\_func\_t) (cfg\_opt\_t \*opt, unsigned int index, FILE \*fp)

Function prototype used by the cfg\_print\_ functions. This callback function is used to print option values. For options with a value parsing callback, this is often required, especially if a string is mapped to an integer by the callback. This print callback must then map the integer back to the appropriate string.

Except for functions, the print callback function should only print the value of the option, not the name and the equal sign (that is handled by the cfg\_opt\_print function). For function options however, the name and the parenthesis must be printed by this function. The value to print can be accessed with the cfg\_opt\_get functions.

**Parameters**

*opt* The option structure (eg, as returned from **cfg\_getopt()**) \
 *index* Index of the value to get. Zero based. \
 *fp* File stream to print to, use stdout to print to the screen.

**See also**

**cfg\_print**, **cfg\_set\_print\_func**

### typedef int(\* cfg\_validate\_callback2\_t) (cfg\_t \*cfg, cfg\_opt\_t \*opt, void \*value)

Validating callback2 prototype. This callback function is called before an option is set using the cfg\_set\*() APIs. The function is called only for strings, integers, and floats. Compared to the regular callback function this takes a value pointer argument which must be cast before use, but can also be used to correct a value before it is set, e.g. when a too large value is set this can be used to set the MAX.

**Returns**

On success, 0 should be returned. All other values indicates an error, and the cfg\_set\*() function will return without setting the value.

**See also**

**cfg\_set\_validate\_func2()**

### typedef int(\* cfg\_validate\_callback\_t) (cfg\_t \*cfg, cfg\_opt\_t \*opt)

Validating callback prototype. This callback function is called after an option has been parsed and set. The function is called for both fundamental values (strings, integers etc) as well as lists and sections. This can for example be used to validate that all required options in a section has been set to sane values.

**Returns**

On success, 0 should be returned. All other values indicates an error, and the parsing is aborted. The callback function should notify the error itself, for example by calling **cfg\_error()**.

**See also**

**cfg\_set\_validate\_func**

## Enumeration Type Documentation

### enum cfg\_bool\_t

Boolean values.

### enum cfg\_type\_t

Fundamental option types.

**Enumerator**

- *CFGT\_INT*

  *integer*

- *CFGT\_FLOAT*

  *floating point number*

- *CFGT\_STR*

  *string*

- *CFGT\_BOOL*

  *boolean value*

- *CFGT\_SEC*

  *section*

- *CFGT\_FUNC*

  *function*

- *CFGT\_PTR*

  *pointer to user-defined value*

- *CFGT\_COMMENT*

  *comment/annotation*

## Function Documentation

### DLLIMPORT int \_\_export cfg\_add\_searchpath (cfg\_t \* cfg, const char \* dir)

*Add a searchpath directory to the configuration context, the const char\* argument will be duplicated and then freed as part of the usual context takedown. All directories added to the context in this manner will be searched for the file specified in* **cfg\_parse()***, and for those included. All directories added with this function will be 'tilde expanded'. Note that the current directory is not added to the searchpath by default.*

**Parameters**

*cfg The configuration file context as returned from* **cfg\_init()***.* \
 *dir Directory to be added to the search path.*

**Returns**

*On success, CFG\_SUCCESS, on failure (which can only be caused by a failed malloc()), CFG\_PARSE\_ERROR.*

*References* **CFG\_SUCCESS***, and* **cfg\_t::path***.*

### DLLIMPORT int \_\_export cfg\_addlist (cfg\_t \* cfg, const char \* name, unsigned int nvalues, ...)

*Add values for a list option. The new values are appended to any current values in the list.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *nvalues Number of values to add.* \
 *... The values to add, the type must match the type of the option and the number of values must be equal to the nvalues parameter.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **CFG\_SUCCESS***,* **CFGF\_LIST***, and* **cfg\_opt\_t::flags***.*

### DLLIMPORT cfg\_t \* cfg\_addtsec (cfg\_t \* cfg, const char \* name, const char \* title)

*Create a new titled config section.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *title The title of this section.*

**Returns**

*A pointer to the created section or if the section already exists a pointer to that section is returned. If the section could not be created or found, 0 is returned.*

*References* **cfg\_t::errfunc***,* **cfg\_t::line***,* **cfg\_t::path***, and* **cfg\_value\_t::section***.*

### DLLIMPORT void \_\_export cfg\_error (cfg\_t \* cfg, const char \* fmt, ...)

*Show a parser error. Any user-defined error reporting function is called.*

**See also**

**cfg\_set\_error\_function**

*References* **cfg\_t::errfunc***,* **cfg\_t::filename***, and* **cfg\_t::line***.*

### DLLIMPORT int \_\_export cfg\_free (cfg\_t \* cfg)

*Free a* **cfg\_t** *context. All memory allocated by the* **cfg\_t** *context structure are freed, and can't be used in any further cfg\_\* calls.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **CFG\_SUCCESS***,* **cfg\_t::comment***,* **cfg\_t::filename***,* **cfg\_t::name***,* **cfg\_opt\_t::name***,* **cfg\_t::opts***,* **cfg\_t::path***, and* **cfg\_t::title***.*

### DLLIMPORT int \_\_export cfg\_free\_value (cfg\_opt\_t \* opt)

*Free the memory allocated for the values of a given option. Only the values are freed, not the option itself (it is freed by* **cfg\_free()***).*

**See also**

**cfg\_free()**

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **CFG\_SUCCESS***,* **CFGT\_PTR***,* **CFGT\_SEC***,* **CFGT\_STR***,* **cfg\_opt\_t::comment***,* **cfg\_opt\_t::flags***,* **cfg\_opt\_t::nvalues***,* **cfg\_t::path***,* **cfg\_value\_t::ptr***,* **cfg\_value\_t::section***,* **cfg\_value\_t::string***,* **cfg\_opt\_t::type***, and* **cfg\_opt\_t::values***.*

### DLLIMPORT cfg\_bool\_t \_\_export cfg\_getbool (cfg\_t \* cfg, const char \* name)

*Returns the value of a boolean option.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.*

**Returns**

*The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding* **cfg\_opt\_t** *structure is returned. It is an error to try to get an option that isn't declared.*

### DLLIMPORT char \*\_\_export cfg\_getcomment (cfg\_t \* cfg, const char \* name)

*Returns the option comment. This function can be used to extract option annotations from a config file. Only comments preceding the option are read by* **cfg\_parse()***.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.*

**See also**

**cfg\_setcomment**

**Returns**

*The comment for this option, or NULL if unset*

### DLLIMPORT double \_\_export cfg\_getfloat (cfg\_t \* cfg, const char \* name)

*Returns the value of a floating point option.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.*

**Returns**

*The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding* **cfg\_opt\_t** *structure is returned. It is an error to try to get an option that isn't declared.*

### DLLIMPORT long int \_\_export cfg\_getint (cfg\_t \* cfg, const char \* name)

*Returns the value of an integer option. This is the same as calling cfg\_getnint with index 0.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.*

**Returns**

*The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding* **cfg\_opt\_t** *structure is returned. It is an error to try to get an option that isn't declared.*

### DLLIMPORT cfg\_bool\_t \_\_export cfg\_getnbool (cfg\_t \* cfg, const char \* name, unsigned int index)

*Indexed version of* **cfg\_getbool()***, used for lists.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *index Index of the value to get. Zero based.*

**See also**

**cfg\_getbool**

### DLLIMPORT double \_\_export cfg\_getnfloat (cfg\_t \* cfg, const char \* name, unsigned int index)

*Indexed version of* **cfg\_getfloat()***, used for lists.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *index Index of the value to get. Zero based.*

**See also**

**cfg\_getfloat**

### DLLIMPORT long int \_\_export cfg\_getnint (cfg\_t \* cfg, const char \* name, unsigned int index)

*Indexed version of* **cfg\_getint()***, used for lists.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *index Index of the value to get. Zero based.*

**See also**

**cfg\_getint**

### DLLIMPORT cfg\_opt\_t \* cfg\_getnopt (cfg\_t \* cfg, unsigned int index)

*Return the nth option in a file or section.*

**Parameters**

*cfg The configuration file or section context* \
 *index Option index*

**See also**

**cfg\_num**

*References* **cfg\_opt\_t::name***, and* **cfg\_t::opts***.*

### DLLIMPORT cfg\_t \*\_\_export cfg\_getnsec (cfg\_t \* cfg, const char \* name, unsigned int index)

*Indexed version of* **cfg\_getsec()***, used for sections with the CFGF\_MULTI flag set.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *index Index of the section to get. Zero based.*

**See also**

**cfg\_getsec**

### DLLIMPORT char \*\_\_export cfg\_getnstr (cfg\_t \* cfg, const char \* name, unsigned int index)

*Indexed version of* **cfg\_getstr()***, used for lists.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *index Index of the value to get. Zero based.*

**See also**

**cfg\_getstr**

### DLLIMPORT cfg\_opt\_t \*\_\_export cfg\_getopt (cfg\_t \* cfg, const char \* name)

*Return an option given it's name.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.*

**Returns**

*Returns a pointer to the option. If the option isn't declared, libConfuse will print an error message and return 0.*

### DLLIMPORT void \*\_\_export cfg\_getptr (cfg\_t \* cfg, const char \* name)

*Returns the value of a user-defined option (void pointer).*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.*

**Returns**

*The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding* **cfg\_opt\_t** *structure is returned. It is an error to try to get an option that isn't declared.*

### DLLIMPORT cfg\_t \*\_\_export cfg\_getsec (cfg\_t \* cfg, const char \* name)

*Returns the value of a section option. The returned value is another* **cfg\_t** *structure that can be used in following calls to cfg\_getint, cfg\_getstr or other get-functions.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.*

**Returns**

*The requested section is returned. If no section is found with that name, 0 is returned. There can only be default values for section without the CFGF\_MULTI flag set. It is an error to try to get a section that isn't declared.*

### DLLIMPORT char \*\_\_export cfg\_getstr (cfg\_t \* cfg, const char \* name)

*Returns the value of a string option.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.*

**Returns**

*The requested value is returned. If the option was not set in the configuration file, the default value given in the corresponding* **cfg\_opt\_t** *structure is returned. It is an error to try to get an option that isn't declared.*

### DLLIMPORT cfg\_t \*\_\_export cfg\_gettsec (cfg\_t \* cfg, const char \* name, const char \* title)

*Return a section given the title, used for section with the CFGF\_TITLE flag set.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *title The title of this section. The CFGF\_TITLE flag must have been set for this option.*

**See also**

**cfg\_getsec**

### DLLIMPORT int \_\_export cfg\_include (cfg\_t \* cfg, cfg\_opt\_t \* opt, int argc, const char \*\* argv)

*Predefined include-function. This function can be used in the options passed to* **cfg\_init()** *to specify a function for including other configuration files in the parsing. For example: CFG\_FUNC('include', &cfg\_include)*

### DLLIMPORT cfg\_t \*\_\_export cfg\_init (cfg\_opt\_t \* opts, cfg\_flag\_t flags)

*Create and initialize a* **cfg\_t** *structure. This should be the first function called when setting up the parsing of a configuration file. The options passed in the first parameter is initialized using the CFG\_\* initializers. The last option in the option array must be* **CFG\_END()***, unless you like segmentation faults.*

*The options must no longer be defined in the same scope as where the cfg\_xxx functions are used (since version 2.3).*

*CFGF\_IGNORE\_UNKNOWN can be specified to use the '\_\_unknown' option whenever an unknown option is parsed. Be sure to define an '\_\_unknown' option in each scope that unknown parameters are allowed.*

*Call setlocale() before calling this function to localize handling of types, LC\_CTYPE, and messages, LC\_MESSAGES, since version 2.9:*

```
    setlocale(LC_MESSAGES, '');
    setlocale(LC_CTYPE, '');
```

**Parameters**

*opts An array of options* \
 *flags One or more flags (bitwise or'ed together). Currently only CFGF\_NOCASE and CFGF\_IGNORE\_UNKNOWN are available. Use 0 if no flags are needed.*

**Returns**

*A configuration context structure. This pointer is passed to almost all other functions as the first parameter.*

*References* **cfg\_t::errfunc***,* **cfg\_t::filename***,* **cfg\_t::flags***,* **cfg\_t::line***,* **cfg\_t::name***, and* **cfg\_t::opts***.*

### DLLIMPORT const char \*\_\_export cfg\_name (cfg\_t \* cfg)

*Return the name of a section.*

**Parameters**

*cfg The configuration file context.*

**Returns**

*Returns the title, or 0 if there is no title. This string should not be modified.*

*References* **cfg\_t::name***.*

### DLLIMPORT unsigned int \_\_export cfg\_num (cfg\_t \* cfg)

*Return number of options in a file or section.*

**Parameters**

*cfg The configuration file or section context*

*When a file has been parsed this function returns the number of options/settings the file, or a sub-section, has.*

**Returns**

*Number of options in a config file or section.*

*References* **cfg\_t::opts***.*

### DLLIMPORT char \*\_\_export cfg\_opt\_getcomment (cfg\_opt\_t \* opt)

*Returns the option comment.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)*

**See also**

**cfg\_getcomment**

*References* **cfg\_opt\_t::comment***.*

### DLLIMPORT cfg\_bool\_t \_\_export cfg\_opt\_getnbool (cfg\_opt\_t \* opt, unsigned int index)

*Returns the value of a boolean option, given a* **cfg\_opt\_t** *pointer.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *index Index of the value to get. Zero based.*

**See also**

**cfg\_getnbool**

*References* **cfg\_value\_t::boolean***,* **CFGT\_BOOL***,* **cfg\_opt\_t::simple\_value***,* **cfg\_opt\_t::type***, and* **cfg\_opt\_t::values***.*

### DLLIMPORT double \_\_export cfg\_opt\_getnfloat (cfg\_opt\_t \* opt, unsigned int index)

*Returns the value of a floating point option, given a* **cfg\_opt\_t** *pointer.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *index Index of the value to get. Zero based.*

**See also**

**cfg\_getnfloat**

*References* **CFGT\_FLOAT***,* **cfg\_value\_t::fpnumber***,* **cfg\_opt\_t::simple\_value***,* **cfg\_opt\_t::type***, and* **cfg\_opt\_t::values***.*

### DLLIMPORT signed long \_\_export cfg\_opt\_getnint (cfg\_opt\_t \* opt, unsigned int index)

*Returns the value of an integer option, given a* **cfg\_opt\_t** *pointer.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *index Index of the value to get. Zero based.*

**See also**

**cfg\_getnint**

*References* **CFGT\_INT***,* **cfg\_value\_t::number***,* **cfg\_opt\_t::simple\_value***,* **cfg\_opt\_t::type***, and* **cfg\_opt\_t::values***.*

### DLLIMPORT cfg\_t \*\_\_export cfg\_opt\_getnsec (cfg\_opt\_t \* opt, unsigned int index)

*Returns the value of a section option, given a* **cfg\_opt\_t** *pointer.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *index Index of the value to get. Zero based.*

**See also**

**cfg\_getnsec**

*References* **CFGT\_SEC***,* **cfg\_value\_t::section***,* **cfg\_opt\_t::type***, and* **cfg\_opt\_t::values***.*

### DLLIMPORT char \*\_\_export cfg\_opt\_getnstr (cfg\_opt\_t \* opt, unsigned int index)

*Returns the value of a string option, given a* **cfg\_opt\_t** *pointer.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *index Index of the value to get. Zero based.*

**See also**

**cfg\_getnstr**

*References* **CFGT\_STR***,* **cfg\_opt\_t::simple\_value***,* **cfg\_value\_t::string***,* **cfg\_opt\_t::type***, and* **cfg\_opt\_t::values***.*

### DLLIMPORT const char \* cfg\_opt\_getstr (cfg\_opt\_t \* opt)

*Return the string value of a key=value pair.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getnopt()***)*

**See also**

**cfg\_opt\_name**

**Returns**

*The string value for the option, or NULL if it's not a string. This string must not be modified!*

### DLLIMPORT cfg\_t \*\_\_export cfg\_opt\_gettsec (cfg\_opt\_t \* opt, const char \* title)

*Returns the value of a section option, given a* **cfg\_opt\_t** *pointer and the title.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *title The title of this section. The CFGF\_TITLE flag must have been set for this option.*

**See also**

**cfg\_gettsec**

*References* **CFGF\_TITLE***, and* **cfg\_opt\_t::flags***.*

### DLLIMPORT const char \*\_\_export cfg\_opt\_name (cfg\_opt\_t \* opt)

*Return the name of an option.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)*

**Returns**

*Returns the title, or 0 if there is no title. This string should not be modified.*

*References* **cfg\_opt\_t::name***.*

### DLLIMPORT int \_\_export cfg\_opt\_nprint\_var (cfg\_opt\_t \* opt, unsigned int index, FILE \* fp)

*Default value print function. Print only the value of a given option. Does not handle sections or functions. Use cfg\_opt\_print to print the whole assignment ('option* *= value'), or cfg\_print to print the whole config file.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *index The index in the option value array that should be printed* \
 *fp File stream to print to.*

**See also**

**cfg\_print***,* **cfg\_opt\_print**

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **CFG\_SUCCESS***,* **CFGT\_BOOL***,* **CFGT\_COMMENT***,* **CFGT\_FLOAT***,* **CFGT\_FUNC***,* **CFGT\_INT***,* **CFGT\_PTR***,* **CFGT\_SEC***,* **CFGT\_STR***, and* **cfg\_opt\_t::type***.*

### DLLIMPORT int \_\_export cfg\_opt\_print (cfg\_opt\_t \* opt, FILE \* fp)

*Print an option and its value to a file. If a print callback function is specified for the option, it is used instead of cfg\_opt\_nprint\_var.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *fp File stream to print to.*

**See also**

**cfg\_print\_func\_t**

**Returns**

*POSIX OK(0), or non-zero on failure.*

### DLLIMPORT int \_\_export cfg\_opt\_print\_indent (cfg\_opt\_t \* opt, FILE \* fp, int indent)

*Print an option and its value to a file. Same as cfg\_opt\_print, but with the indentation level specified.*

**See also**

**cfg\_opt\_print**

**Returns**

*POSIX OK(0), or non-zero on failure.*

### DLLIMPORT int \_\_export cfg\_opt\_rmnsec (cfg\_opt\_t \* opt, unsigned int index)

*Removes and frees a config section, given a* **cfg\_opt\_t** *pointer.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *index Index of the section to remove. Zero based.*

**See also**

**cfg\_rmnsec**

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **CFG\_SUCCESS***,* **CFGT\_SEC***,* **cfg\_opt\_t::nvalues***,* **cfg\_value\_t::section***,* **cfg\_opt\_t::type***, and* **cfg\_opt\_t::values***.*

### DLLIMPORT int \_\_export cfg\_opt\_rmtsec (cfg\_opt\_t \* opt, const char \* title)

*Removes and frees a config section, given a* **cfg\_opt\_t** *pointer and the title.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *title The title of this section. The CFGF\_TITLE flag must have been set for this option.*

**See also**

**cfg\_rmtsec**

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **CFGF\_NOCASE***,* **CFGF\_TITLE***,* **cfg\_opt\_t::flags***, and* **cfg\_t::title***.*

### DLLIMPORT cfg\_print\_func\_t \_\_export cfg\_opt\_set\_print\_func (cfg\_opt\_t \* opt, cfg\_print\_func\_t pf)

*Set a print callback function for an option.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *pf The print function callback.*

**See also**

**cfg\_print\_func\_t**

*References* **cfg\_opt\_t::pf***.*

### DLLIMPORT int \_\_export cfg\_opt\_setcomment (cfg\_opt\_t \* opt, char \* comment)

*Annotate an option.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *comment The annotation*

**See also**

**cfg\_setcomment**

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **CFG\_SUCCESS***,* **CFGF\_COMMENTS***,* **CFGF\_MODIFIED***,* **cfg\_opt\_t::comment***, and* **cfg\_opt\_t::flags***.*

### DLLIMPORT int cfg\_opt\_setmulti (cfg\_t \* cfg, cfg\_opt\_t \* opt, unsigned int nvalues, char \*\* values)

*Set an option (create an instance of an option).*

**Parameters**

*cfg The configuration file context.* \
 *opt The option definition.* \
 *nvalues The number of values to set for the option.* \
 *values The value(s) for the option.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **CFG\_SUCCESS***,* **CFGF\_MODIFIED***,* **cfg\_opt\_t::flags***,* **cfg\_opt\_t::nvalues***, and* **cfg\_opt\_t::values***.*

### DLLIMPORT int \_\_export cfg\_opt\_setnbool (cfg\_opt\_t \* opt, cfg\_bool\_t value, unsigned int index)

*Set a value of a boolean option.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *value The value to set.* \
 *index The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF\_LIST flag set.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **cfg\_value\_t::boolean***,* **CFG\_SUCCESS***,* **CFGF\_MODIFIED***,* **CFGT\_BOOL***,* **cfg\_opt\_t::flags***, and* **cfg\_opt\_t::type***.*

### DLLIMPORT int \_\_export cfg\_opt\_setnfloat (cfg\_opt\_t \* opt, double value, unsigned int index)

*Set a value of a floating point option.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *value The value to set.* \
 *index The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF\_LIST flag set.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **CFG\_SUCCESS***,* **CFGF\_MODIFIED***,* **CFGT\_FLOAT***,* **cfg\_opt\_t::flags***,* **cfg\_value\_t::fpnumber***, and* **cfg\_opt\_t::type***.*

### DLLIMPORT int \_\_export cfg\_opt\_setnint (cfg\_opt\_t \* opt, long int value, unsigned int index)

*Set a value of an integer option.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *value The value to set.* \
 *index The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF\_LIST flag set.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **CFG\_SUCCESS***,* **CFGF\_MODIFIED***,* **CFGT\_INT***,* **cfg\_opt\_t::flags***,* **cfg\_value\_t::number***, and* **cfg\_opt\_t::type***.*

### DLLIMPORT int \_\_export cfg\_opt\_setnstr (cfg\_opt\_t \* opt, const char \* value, unsigned int index)

*Set a value of a string option.*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)* \
 *value The value to set. Memory for the string is allocated and the value is copied. Any previous string value is freed.* \
 *index The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF\_LIST flag set.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **CFG\_SUCCESS***,* **CFGF\_MODIFIED***,* **CFGT\_STR***,* **cfg\_opt\_t::flags***,* **cfg\_value\_t::string***, and* **cfg\_opt\_t::type***.*

### DLLIMPORT unsigned int \_\_export cfg\_opt\_size (cfg\_opt\_t \* opt)

*Return the number of values this option has. If no default value is given for the option and no value was found in the config file, 0 will be returned (ie, the option value is not set at all).*

**Parameters**

*opt The option structure (eg, as returned from* **cfg\_getopt()***)*

*References* **cfg\_opt\_t::nvalues***.*

### DLLIMPORT int \_\_export cfg\_parse (cfg\_t \* cfg, const char \* filename)

*Parse a configuration file. Tilde expansion is performed on the filename before it is opened. After a configuration file has been initialized (with* **cfg\_init()***) and parsed (with* **cfg\_parse()***), the values can be read with the cfg\_getXXX functions.*

**Parameters**

*cfg The configuration file context as returned from* **cfg\_init()***.* \
 *filename The name of the file to parse.*

**Returns**

*On success, CFG\_SUCCESS is returned. If the file couldn't be opened for reading, CFG\_FILE\_ERROR is returned. On all other errors, CFG\_PARSE\_ERROR is returned and* **cfg\_error()** *was called with a descriptive error message.*

*References* **cfg\_t::filename***, and* **cfg\_t::path***.*

### DLLIMPORT int \_\_export cfg\_parse\_boolean (const char \* s)

*Parse a boolean option string. Accepted 'true' values are 'true', 'on' and 'yes', and accepted 'false' values are 'false', 'off' and 'no'.*

**Returns**

*Returns 1 or 0 (true/false) if the string was parsed correctly, or -1 if an error occurred.*

### DLLIMPORT int \_\_export cfg\_parse\_buf (cfg\_t \* cfg, const char \* buf)

*Same as* **cfg\_parse()** *above, but takes a character buffer as argument.*

**Parameters**

*cfg The configuration file context as returned from* **cfg\_init()***.* \
 *buf A zero-terminated string with configuration directives.*

**See also**

**cfg\_parse()**

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **CFG\_SUCCESS***, and* **cfg\_t::filename***.*

### DLLIMPORT int \_\_export cfg\_parse\_fp (cfg\_t \* cfg, FILE \* fp)

*Same as* **cfg\_parse()** *above, but takes an already opened file as argument. Reading begins at the current position. After parsing, the position is not reset. The caller is responsible for closing the file.*

**Parameters**

*cfg The configuration file context as returned from* **cfg\_init()***.* \
 *fp An open file stream.*

**See also**

**cfg\_parse()**

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **CFG\_SUCCESS***,* **cfg\_t::filename***, and* **cfg\_t::line***.*

### DLLIMPORT int \_\_export cfg\_print (cfg\_t \* cfg, FILE \* fp)

*Print the options and values to a file. Note that options in any included file are expanded and printed directly to the file. Option values given with environment variables in the parsed input are also printed expanded. This means that if you parse a configuration file you can't expect that the output from this function is identical to the initial file.*

**Parameters**

*cfg The configuration file context.* \
 *fp File stream to print to, use stdout to print to the screen.*

**See also**

**cfg\_print\_func\_t***,* **cfg\_set\_print\_func**

**Returns**

*POSIX OK(0), or non-zero on failure.*

### DLLIMPORT int \_\_export cfg\_print\_indent (cfg\_t \* cfg, FILE \* fp, int indent)

*Print the options and values to a file. Same as cfg\_print, but with the indentation level specified.*

**See also**

**cfg\_print**

**Returns**

*POSIX OK(0), or non-zero on failure.*

### DLLIMPORT int \_\_export cfg\_rmnsec (cfg\_t \* cfg, const char \* name, unsigned int index)

*Indexed version of* **cfg\_rmsec()***, used for CFGF\_MULTI sections.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the section.* \
 *index Index of the section to remove. Zero based.*

**See also**

**cfg\_rmsec**

**Returns**

*POSIX OK(0), or non-zero on failure.*

### DLLIMPORT int \_\_export cfg\_rmsec (cfg\_t \* cfg, const char \* name)

*Removes and frees a config section. This is the same as calling cfg\_rmnsec with index 0.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the section.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

### DLLIMPORT int \_\_export cfg\_rmtsec (cfg\_t \* cfg, const char \* name, const char \* title)

*Removes and frees a section given the title, used for section with the CFGF\_TITLE flag set.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the section.* \
 *title The title of this section. The CFGF\_TITLE flag must have been set for this option.*

**See also**

**cfg\_rmsec**

**Returns**

*POSIX OK(0), or non-zero on failure.*

### DLLIMPORT char \*\_\_export cfg\_searchpath (cfg\_searchpath\_t \* path, const char \* file)

*Search the linked-list of cfg\_searchpath\_t for the specified file. If not NULL, the return value is freshly allocated and and should be freed by the caller.*

**Parameters**

*path The linked list of cfg\_searchpath\_t structs, each containing a directory to be searched* \
 *file The file for which to search*

**Returns**

*If the file is found on the searchpath then the full path to the file is returned. If not found, NULL is returned.*

### DLLIMPORT cfg\_errfunc\_t \_\_export cfg\_set\_error\_function (cfg\_t \* cfg, cfg\_errfunc\_t errfunc)

*Install a user-defined error reporting function.*

**Returns**

*The old error reporting function is returned.*

*References* **cfg\_t::errfunc***.*

### DLLIMPORT cfg\_print\_filter\_func\_t \_\_export cfg\_set\_print\_filter\_func (cfg\_t \* cfg, cfg\_print\_filter\_func\_t pff)

*Install a user-defined print filter function. This callback is called for each option when printing cfg, or something above cfg if cfg is a section in some parent cfg. When cfg (or something above cfg) is printed, this filter is also inherited to child sections unless the child section has its own print filter.*

**Parameters**

*cfg The configuration file context.* \
 *pff The print filter callback function.*

**Returns**

*The old print filter function is returned.*

**See also**

**cfg\_print\_filter\_func\_t**

*References* **cfg\_t::pff***.*

### DLLIMPORT cfg\_print\_func\_t \_\_export cfg\_set\_print\_func (cfg\_t \* cfg, const char \* name, cfg\_print\_func\_t pf)

*Set a print callback function for an option given its name.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *pf The print callback function.*

**See also**

**cfg\_print\_func\_t**

### DLLIMPORT cfg\_validate\_callback\_t \_\_export cfg\_set\_validate\_func (cfg\_t \* cfg, const char \* name, cfg\_validate\_callback\_t vf)

*Register a validating callback function for an option.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *vf The validating callback function.*

**See also**

**cfg\_validate\_callback\_t**

*References* **cfg\_t::flags***,* **cfg\_t::opts***, and* **cfg\_opt\_t::validcb***.*

### DLLIMPORT cfg\_validate\_callback2\_t \_\_export cfg\_set\_validate\_func2 (cfg\_t \* cfg, const char \* name, cfg\_validate\_callback2\_t vf)

*Register a validating callback function for an option. This callback is called for all cfg\_set\*() functions, although not cfg\_opt\_set\*(), and can be used to check and modify a value/string \*before\* it is actually set. The regular callbacks are run after the fact and are only called when parsing a buffer or file.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *vf The validating callback function.*

**See also**

**cfg\_validate\_callback2\_t**

*References* **cfg\_t::flags***,* **cfg\_t::opts***, and* **cfg\_opt\_t::validcb2***.*

### DLLIMPORT int \_\_export cfg\_setbool (cfg\_t \* cfg, const char \* name, cfg\_bool\_t value)

*Set the value of a boolean option given its name.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *value The value to set. If the option is a list (the CFGF\_LIST flag is set), only the first value (with index 0) is set.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

### DLLIMPORT int \_\_export cfg\_setcomment (cfg\_t \* cfg, const char \* name, char \* comment)

*Annotate an option given its name. All options can be annotated as long as the CFGF\_COMMENTS flag is given to* **cfg\_init()***.*

*When calling* **cfg\_print()***, annotations are saved as a C style one-liner comment before each option.*

*When calling* **cfg\_parse()***, only one-liner comments preceding an option are read and used to annotate the option.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *comment The annotation*

**Returns**

*POSIX OK(0), or non-zero on failure. This function will fail if memory for the new comment cannot be allocated.*

### DLLIMPORT int \_\_export cfg\_setfloat (cfg\_t \* cfg, const char \* name, double value)

*Set the value of a floating point option given its name.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *value The value to set. If the option is a list (the CFGF\_LIST flag is set), only the first value (with index 0) is set.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

### DLLIMPORT int \_\_export cfg\_setint (cfg\_t \* cfg, const char \* name, long int value)

*Set the value of an integer option given its name.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *value The value to set. If the option is a list (the CFGF\_LIST flag is set), only the first value (with index 0) is set.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

### DLLIMPORT int \_\_export cfg\_setlist (cfg\_t \* cfg, const char \* name, unsigned int nvalues, ...)

*Set values for a list option. All existing values are replaced with the new ones.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *nvalues Number of values to set.* \
 *... The values to set, the type must match the type of the option and the number of values must be equal to the nvalues parameter.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **CFG\_SUCCESS***,* **CFGF\_LIST***, and* **cfg\_opt\_t::flags***.*

### DLLIMPORT int cfg\_setmulti (cfg\_t \* cfg, const char \* name, unsigned int nvalues, char \*\* values)

*Set an option (create an instance of an option).*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *nvalues The number of values to set for the option.* \
 *values The value(s) for the option.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

### DLLIMPORT int \_\_export cfg\_setnbool (cfg\_t \* cfg, const char \* name, cfg\_bool\_t value, unsigned int index)

*Set a value of a boolean option given its name and index.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *value The value to set.* \
 *index The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF\_LIST flag set.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

### DLLIMPORT int \_\_export cfg\_setnfloat (cfg\_t \* cfg, const char \* name, double value, unsigned int index)

*Set a value of a floating point option given its name and index.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *value The value to set.* \
 *index The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF\_LIST flag set.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **cfg\_opt\_t::validcb2***.*

### DLLIMPORT int \_\_export cfg\_setnint (cfg\_t \* cfg, const char \* name, long int value, unsigned int index)

*Set a value of an integer option given its name and index.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *value The value to set.* \
 *index The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF\_LIST flag set.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **cfg\_opt\_t::validcb2***.*

### DLLIMPORT int \_\_export cfg\_setnstr (cfg\_t \* cfg, const char \* name, const char \* value, unsigned int index)

*Set a value of a boolean option given its name and index.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *value The value to set. Memory for the string is allocated and the value is copied. Any privious string value is freed.* \
 *index The index in the option value array that should be modified. It is an error to set values with indices larger than 0 for options without the CFGF\_LIST flag set.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

*References* **cfg\_opt\_t::validcb2***.*

### DLLIMPORT cfg\_value\_t \* cfg\_setopt (cfg\_t \* cfg, cfg\_opt\_t \* opt, const char \* value)

*Set an option (create an instance of an option).*

**Parameters**

*cfg The configuration file context.* \
 *opt The option definition.* \
 *value The initial value for the option.*

**Returns**

*Returns a pointer to the value object.*

*References* **cfg\_value\_t::boolean***,* **CFGF\_KEYSTRVAL***,* **CFGF\_LIST***,* **CFGF\_MODIFIED***,* **CFGF\_MULTI***,* **CFGF\_NO\_TITLE\_DUPES***,* **CFGF\_NOCASE***,* **CFGF\_TITLE***,* **CFGT\_BOOL***,* **CFGT\_FLOAT***,* **CFGT\_INT***,* **CFGT\_PTR***,* **CFGT\_SEC***,* **CFGT\_STR***,* **cfg\_t::errfunc***,* **cfg\_t::filename***,* **cfg\_t::flags***,* **cfg\_opt\_t::flags***,* **cfg\_value\_t::fpnumber***,* **cfg\_t::line***,* **cfg\_t::name***,* **cfg\_opt\_t::name***,* **cfg\_value\_t::number***,* **cfg\_opt\_t::nvalues***,* **cfg\_t::opts***,* **cfg\_opt\_t::parsecb***,* **cfg\_t::path***,* **cfg\_value\_t::ptr***,* **cfg\_value\_t::section***,* **cfg\_opt\_t::simple\_value***,* **cfg\_value\_t::string***,* **cfg\_opt\_t::subopts***,* **cfg\_t::title***,* **cfg\_opt\_t::type***, and* **cfg\_opt\_t::values***.*

### DLLIMPORT int \_\_export cfg\_setstr (cfg\_t \* cfg, const char \* name, const char \* value)

*Set the value of a string option given its name.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.* \
 *value The value to set. Memory for the string is allocated and the value is copied. Any previous string value is freed. If the option is a list (the CFGF\_LIST flag is set), only the first value (with index 0) is set.*

**Returns**

*POSIX OK(0), or non-zero on failure.*

### DLLIMPORT unsigned int \_\_export cfg\_size (cfg\_t \* cfg, const char \* name)

*Return the number of values this option has. If no default value is given for the option and no value was found in the config file, 0 will be returned (ie, the option value is not set at all).*

*Note that there is no way to \*not\* specify a default value for integers, floats and booleans. Ie, they always have default values (since 0 or NULL is a valid integer/float/boolean value). Only strings and lists may have no default value.*

**Parameters**

*cfg The configuration file context.* \
 *name The name of the option.*

### DLLIMPORT char \*\_\_export cfg\_tilde\_expand (const char \* filename)

*Does tilde expansion (~ -\> $HOME) on the filename.*

**Returns**

*The expanded filename is returned. If a ~user was not found, the original filename is returned. In any case, a dynamically allocated string is returned, which should be free()'d by the caller.*

### DLLIMPORT const char \*\_\_export cfg\_title (cfg\_t \* cfg)

*Return the title of a section.*

**Parameters**

*cfg The configuration file context.*

**Returns**

*Returns the title, or 0 if there is no title. This string should not be modified.*

*References* **cfg\_t::title***.*

## Author

*Generated automatically by Doxygen for confuse from the source code.*