---
name: "libeconf"
section: "3"
platform: "linux"
package: "libeconf-dev"
version: "0.7.7+dfsg1-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/libeconf"
---

# libeconf(3)

Public API for the econf library. include/libeconf\_ext.h - Public extended API for the econf library.

## NAME

include/libeconf.h - Public API for the econf library.\
 include/libeconf\_ext.h - Public extended API for the econf library.

## DESCRIPTION

**libeconf** is a highly flexible and configurable library to parse and manage key=value configuration files.\
 It reads configuration file snippets from different directories and builds the final configuration file for the application from it.

The first file is the vendor provided configuration file places in /usr/\_vendordir\_/\_project\_. Optionally, /run/\_project\_ is also supported for ephemeral overrides.

Defining \_project\_ sub directory is optional.

There are two methods of overriding this vendor settings: Copy the file from /usr/\_vendordir\_/\_project\_ to /etc/\_project\_ and modify the settings (see **Example 1**).

Alternatively, a directory named \_file\_.\_suffix\_.d/ within /etc/\_project\_ can be created, with drop-in files in the form \_name\_.\_suffix\_ (see **Example 2**).

These files contain only the changes of the specific settings the user is interested in.\
 There can be several such drop-in files, they are processed in lexicographic order of their filename.

The first method is useful to override the complete configuration file with an own one, the vendor supplied configuration is ignored.

So, if /etc/\_project\_/\_example\_.\_suffix\_ exists, /usr/\_vendor\_/\_project\_/\_example\_.\_suffix\_ and /run/\_project\_/\_example\_.\_suffix\_ will not be read.\
 The disadvantage is, that changes of the vendor configuration file, due e.g. an package update, are ignored and the user has to manually merge them.

The other method will continue to use /usr/\_vendor\_/\_project\_/\_example\_.\_suffix\_ as base configuration file and merge all changes from /etc/\_project\_/\_example\_.\_suffix\_.d/\*.\_suffix\_.\
 So the user will automatically get improvements of the vendor, with the drawback, that they could be incompatible with the user made changes.\
 If there is a file with the same name in /usr/\_vendor\_/\_project\_/\_example\_.\_suffix\_.d/ and in /etc/\_project\_/\_example\_.\_suffix\_.d/\*.\_suffix\_., the file in /usr/\_project\_/\_vendor\_/\_example\_.\_suffix\_.d/ will completely ignored.\
 To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to /dev/null in the configuration directory in /etc/\_project\_/, with the same filename as the vendor configuration file.

Optionally, schemes with only drop-ins and without a ‘main’ configuration file will be supported too. In such schemes many drop-ins are loaded from a common directory in each hierarchy. For example, /usr/lib/\<project\>.d/\*, /run/\<project\>.d/\* and /etc/\<project\>.d/c.conf are all loaded and parsed in this scheme.

### Example 1

If a /etc/\_example\_.\_suffix\_ file exists:

\* /etc/\_example\_.\_suffix\_

\* /usr/\_vendor\_/\_project\_/\_example\_.\_suffix\_.d/\*.\_suffix\_

\* /run/\_project\_/\_example\_.\_suffix\_.d/\*.\_suffix\_

\* /etc/\_project\_/\_example\_.\_suffix\_.d/\*.\_suffix\_

### Example 2

The list of files and directories read if \*\*no\*\* /etc/\_example\_.\_suffix\_ file exists:

\* /usr/\_vendor\_/\_project\_/\_example\_.\_suffix\_ if no /run/\_project\_/\_example\_.\_suffix\_ exist

\* /usr/\_vendor\_/\_project\_/\_example\_.\_suffix\_.d/\*.\_suffix\_

\* /run/\_project\_/\_example\_.\_suffix\_.d/\*.\_suffix\_

\* /etc/\_project\_/\_example\_.\_suffix\_.d/\*.\_suffix\_

### UAPI Configuration Files Specification

The libeconf library fulfills all requirements defined by the Linux Userspace API (UAPI) Group chapter "Configuration Files Specification".\
 See: https://uapi-group.org/specifications/specs/configuration\_files\_specification/

### Bindings

**Python** Documentation: *https://github.com/openSUSE/libeconf/blob/master/bindings/python3/docs/python-libeconf.3*

**C#** Documentation: *https://github.com/openSUSE/libeconf/blob/master/bindings/csharp/docs/README.md*

## SYNOPSIS

`#include <stdbool.h>`\
 `#include <stdint.h>`\
 `#include <stdlib.h>`\
 `#include 'libeconf.h'`\
 `#include 'libeconf_ext.h'`\

### Typedefs

typedef enum **econf\_err** **econf\_err**\
 typedef struct **econf\_file** **econf\_file**\
 typedef struct **econf\_ext\_value** **econf\_ext\_value**\

### Enumerations

enum **econf\_err** { **ECONF\_SUCCESS** = 0, **ECONF\_ERROR** = 1, **ECONF\_NOMEM** = 2, **ECONF\_NOFILE** = 3, **ECONF\_NOGROUP** = 4, **ECONF\_NOKEY** = 5, **ECONF\_EMPTYKEY** = 6, **ECONF\_WRITEERROR** = 7, **ECONF\_PARSE\_ERROR** = 8, **ECONF\_MISSING\_BRACKET** = 9, **ECONF\_MISSING\_DELIMITER** = 10, **ECONF\_EMPTY\_SECTION\_NAME** = 11, **ECONF\_TEXT\_AFTER\_SECTION** = 12, **ECONF\_FILE\_LIST\_IS\_NULL** = 13, **ECONF\_WRONG\_BOOLEAN\_VALUE** = 14, **ECONF\_KEY\_HAS\_NULL\_VALUE** = 15, **ECONF\_WRONG\_OWNER** = 16, **ECONF\_WRONG\_GROUP** = 17, **ECONF\_WRONG\_FILE\_PERMISSION** = 18, **ECONF\_WRONG\_DIR\_PERMISSION** = 19, **ECONF\_ERROR\_FILE\_IS\_SYM\_LINK** = 20, **ECONF\_PARSING\_CALLBACK\_FAILED** = 21 }\
 libeconf error codes

### Functions

**econf\_err** **econf\_readConfig** (**econf\_file** \*\*key\_file, const char \*project, const char \*usr\_subdir, const char \*config\_name, const char \*config\_suffix, const char \*delim, const char \*comment)\
 Evaluating key/values of a given configuration by reading and merging all needed/available files in three different directories (normally in /usr/etc, /run and /etc).  **econf\_err** **econf\_readConfigWithCallback** (**econf\_file** \*\*key\_file, const char \*project, const char \*usr\_subdir, const char \*config\_name, const char \*config\_suffix, const char \*delim, const char \*comment, bool (\*callback)(const char \*filename, const void \*data), const void \*callback\_data)\
 Has the same functionality like **econf\_readConfig**. The user can additionally define a callback in order e.g. to check all parsed file.  **econf\_err** **econf\_readFile** (**econf\_file** \*\*result, const char \*file\_name, const char \*delim, const char \*comment)\
 Process the file of the given file\_name and save its contents into key\_file object.  **econf\_err** **econf\_readFileWithCallback** (**econf\_file** \*\*result, const char \*file\_name, const char \*delim, const char \*comment, bool (\*callback)(const char \*filename, const void \*data), const void \*callback\_data)\
 Has the same functionality like **econf\_readFile**. The user can additionally define a callback in order to check the parsed file.  **econf\_err** **econf\_mergeFiles** (**econf\_file** \*\*merged\_file, **econf\_file** \*usr\_file, **econf\_file** \*etc\_file)\
 Merge the contents of two key\_files objects.  **econf\_err** **econf\_newKeyFile** (**econf\_file** \*\*result, char delimiter, char comment)\
 Create a new econf\_file object.  **econf\_err** **econf\_newIniFile** (**econf\_file** \*\*result)\
 Create a new econf\_file object in IniFile format.  **econf\_err** **econf\_writeFile** (**econf\_file** \*key\_file, const char \*save\_to\_dir, const char \*file\_name)\
 Write content of an econf\_file struct to specified location.  char \* **econf\_getPath** (**econf\_file** \*kf)\
 Evaluating path name of the regarding configuration file.  **econf\_err** **econf\_getGroups** (**econf\_file** \*kf, size\_t \*length, char \*\*\*groups)\
 Evaluating all group entries.  **econf\_err** **econf\_getKeys** (**econf\_file** \*kf, const char \*group, size\_t \*length, char \*\*\*keys)\
 Evaluating all keys.  **econf\_err** **econf\_getIntValue** (**econf\_file** \*kf, const char \*group, const char \*key, int32\_t \*result)\
 Evaluating int32 value for given group/key.  **econf\_err** **econf\_getInt64Value** (**econf\_file** \*kf, const char \*group, const char \*key, int64\_t \*result)\
 Evaluating int64 value for given group/key.  **econf\_err** **econf\_getUIntValue** (**econf\_file** \*kf, const char \*group, const char \*key, uint32\_t \*result)\
 Evaluating uint32 value for given group/key.  **econf\_err** **econf\_getUInt64Value** (**econf\_file** \*kf, const char \*group, const char \*key, uint64\_t \*result)\
 Evaluating uint64 value for given group/key.  **econf\_err** **econf\_getFloatValue** (**econf\_file** \*kf, const char \*group, const char \*key, float \*result)\
 Evaluating float value for given group/key.  **econf\_err** **econf\_getDoubleValue** (**econf\_file** \*kf, const char \*group, const char \*key, double \*result)\
 Evaluating double value for given group/key.  **econf\_err** **econf\_getStringValue** (**econf\_file** \*kf, const char \*group, const char \*key, char \*\*result)\
 Evaluating string value for given group/key.  **econf\_err** **econf\_getBoolValue** (**econf\_file** \*kf, const char \*group, const char \*key, bool \*result)\
 Evaluating bool value for given group/key.  **econf\_err** **econf\_getIntValueDef** (**econf\_file** \*kf, const char \*group, const char \*key, int32\_t \*result, int32\_t def)\
 Evaluating int32 value for given group/key.  **econf\_err** **econf\_getInt64ValueDef** (**econf\_file** \*kf, const char \*group, const char \*key, int64\_t \*result, int64\_t def)\
 Evaluating int64 value for given group/key.  **econf\_err** **econf\_getUIntValueDef** (**econf\_file** \*kf, const char \*group, const char \*key, uint32\_t \*result, uint32\_t def)\
 Evaluating uint32 value for given group/key.  **econf\_err** **econf\_getUInt64ValueDef** (**econf\_file** \*kf, const char \*group, const char \*key, uint64\_t \*result, uint64\_t def)\
 Evaluating uint64 value for given group/key.  **econf\_err** **econf\_getFloatValueDef** (**econf\_file** \*kf, const char \*group, const char \*key, float \*result, float def)\
 Evaluating float value for given group/key.  **econf\_err** **econf\_getDoubleValueDef** (**econf\_file** \*kf, const char \*group, const char \*key, double \*result, double def)\
 Evaluating double value for given group/key.  **econf\_err** **econf\_getStringValueDef** (**econf\_file** \*kf, const char \*group, const char \*key, char \*\*result, char \*def)\
 Evaluating string value for given group/key.  **econf\_err** **econf\_getBoolValueDef** (**econf\_file** \*kf, const char \*group, const char \*key, bool \*result, bool def)\
 Evaluating bool value for given group/key.  **econf\_err** **econf\_setIntValue** (**econf\_file** \*kf, const char \*group, const char \*key, int32\_t value)\
 Set int32 value for given group/key.  **econf\_err** **econf\_setInt64Value** (**econf\_file** \*kf, const char \*group, const char \*key, int64\_t value)\
 Set int64 value for given group/key.  **econf\_err** **econf\_setUIntValue** (**econf\_file** \*kf, const char \*group, const char \*key, uint32\_t value)\
 Set uint32 value for given group/key.  **econf\_err** **econf\_setUInt64Value** (**econf\_file** \*kf, const char \*group, const char \*key, uint64\_t value)\
 Set uint64 value for given group/key.  **econf\_err** **econf\_setFloatValue** (**econf\_file** \*kf, const char \*group, const char \*key, float value)\
 Set float value for given group/key.  **econf\_err** **econf\_setDoubleValue** (**econf\_file** \*kf, const char \*group, const char \*key, double value)\
 Set double value for given group/key.  **econf\_err** **econf\_setStringValue** (**econf\_file** \*kf, const char \*group, const char \*key, const char \*value)\
 Set string value for given group/key.  **econf\_err** **econf\_setBoolValue** (**econf\_file** \*kf, const char \*group, const char \*key, const char \*value)\
 Set bool value for given group/key.  const char \* **econf\_errString** (const **econf\_err** error)\
 Convert an econf\_err type to a string.  void **econf\_errLocation** (char \*\*filename, uint64\_t \*line\_nr)\
 Info about where the error has happened.  void **econf\_freeArray** (char \*\*array)\
 Free an array of type char\*\* created by **econf\_getGroups()** or **econf\_getKeys()**.  void **econf\_freeFile** (**econf\_file** \*key\_file)\
 Free memory allocated by e.g.  char **econf\_comment\_tag** (**econf\_file** \*key\_file)\
 Returns the comment character tag of the given econf\_file object.  char **econf\_delimiter\_tag** (**econf\_file** \*key\_file)\
 Returns the delimiter character of the given econf\_file object.  void **econf\_set\_comment\_tag** (**econf\_file** \*key\_file, const char comment)\
 Set the comment character tag of the given econf\_file object.  void **econf\_set\_delimiter\_tag** (**econf\_file** \*key\_file, const char delimiter)\
 Set the delimiter character of the given econf\_file object.  **econf\_err** **econf\_getExtValue** (**econf\_file** \*kf, const char \*group, const char \*key, **econf\_ext\_value** \*\*result) Evaluating more information for given group/key.  void **econf\_freeExtValue** (**econf\_ext\_value** \*to\_free)\
 Free an complete **econf\_ext\_value** struct.  **econf\_err** **econf\_set\_conf\_dirs** (const char \*\*dir\_postfix\_list)\
 Set a list of directory structures (with order) which describes the directories in which the files have to be parsed.

## Detailed Description

Public API for the econf library.

Definition in file **libeconf.h** and **libeconf\_ext.h**.

## Typedef Documentation

### typedef struct econf\_file econf\_file

Container which includes all information about the configuration file(s).

### typedef struct econf\_ext\_value econf\_ext\_value

char \*\* **values**\
 Values of a given key in form of an string array.  char \* **file**\
 Path of the configuration file where this value has been read.  uint64\_t **line\_number**\
 Line number of the configuration key/value.  char \* **comment\_before\_key**\
 Comment before the key/value entry.  char \* **comment\_after\_value**\
 Comment after the value entry.

## Enumeration Type Documentation

### enum econf\_err

libeconf error codes

**Enumerator**

- *ECONF\_SUCCESS*

  *General purpose success code.*

- *ECONF\_ERROR*

  *Generic Error.*

- *ECONF\_NOMEM*

  *Out of memory.*

- *ECONF\_NOFILE*

  *Config file not found.*

- *ECONF\_NOGROUP*

  *Group not found.*

- *ECONF\_NOKEY*

  *Key not found.*

- *ECONF\_EMPTYKEY*

  *Key has empty value.*

- *ECONF\_WRITEERROR*

  *Error creating or writing to a file.*

- *ECONF\_PARSE\_ERROR*

  *General syntax error in input file.*

- *ECONF\_MISSING\_BRACKET*

  *Missing closing section bracket.*

- *ECONF\_MISSING\_DELIMITER*

  *Missing delimiter.*

- *ECONF\_EMPTY\_SECTION\_NAME*

  *Empty section name.*

- *ECONF\_TEXT\_AFTER\_SECTION*

  *Text after section.*

- *ECONF\_FILE\_LIST\_IS\_NULL*

  *Parsed file list is NULL.*

- *ECONF\_WRONG\_BOOLEAN\_VALUE*

  *Wrong boolean value (1/0 true/false yes/no)*

- *ECONF\_KEY\_HAS\_NULL\_VALUE*

  *Given key has NULL value.*

- *ECONF\_WRONG\_OWNER*

  *File has wrong owner.*

- *ECONF\_WRONG\_GROUP*

  *File has wrong group.*

- *ECONF\_WRONG\_FILE\_PERMISSION*

  *File has wrong file permissions.*

- *ECONF\_WRONG\_DIR\_PERMISSION*

  *File has wrong dir permissions.*

- *ECONF\_ERROR\_FILE\_IS\_SYM\_LINK*

  *File is a sym link which is not permitted.*

- *ECONF\_PARSING\_CALLBACK\_FAILED*

  *User defined parsing callback has failed.*

## Function Documentation

### econf\_err econf\_readConfig (econf\_file \*\* key\_file, const char \*project, const char \*usr\_subdir, const char \*config\_name, const char \*config\_suffix, const char \*delim, const char \*comment)

 *Evaluating key/values of a given configuration by reading and merging all needed/available files from different directories. Order is:*

   */etc/$project/$config\_name.$config\_suffix does exist:*

     *-- /etc/$project/$config\_name.$config\_suffix*\
      *-- $usr\_subdir/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*     \
      *-- /run/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*\
      *-- /etc/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*

   */etc/$project/$config\_name.$config\_suffix does NOT exist:*

     *- /run/$project/$config\_name.$config\_suffix does exist:*

      *-- /run/$project/$config\_name.$config\_suffix*\
       *-- $usr\_subdir/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*      \
       *-- /run/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*\
       *-- /etc/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*

     *- /run/$project/$config\_name.$config\_suffix does NOT exist:*

      *-- $usr\_subdir/$project/$config\_name.$config\_suffix*\
       *-- $usr\_subdir/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*      \
       *-- /run/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*\
       *-- /etc/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*

   *No main $config\_name.$config\_suffix file is defined or must not be parsed:*

      *-- $usr\_subdir/$project.d/\*.$config\_suffix*      \
       *-- /run/$project.d/\*.$config\_suffix*\
       *-- /etc/$project.d/\*.$config\_suffix*

**Parameters:**

*key\_file content of parsed file(s)* \
 *project name of the project used as subdirectory, can be NULL*\
 *usr\_subdir absolute path of the first directory (often "/usr/lib")*\
 *config\_name basename of the configuration file. If it is NULL, drop-ins without* *a main configuration file will be parsed only.*\
 *config\_suffix suffix of the configuration file. Can also be NULL.* \
 *delim delimiters of key/value e.g. '\\t ='. If delim contains space characters* *AND none space characters, multiline values are not parseable.*\
 *comment array of characters which define the start of a comment*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

*Example: Reading content in different cases in following order:*

   */etc/foo/example.conf does exist:*

   *- /etc/foo/example.conf*\
    *- /usr/lib/foo/example.conf.d/ \*.conf*   \
    *- /run/foo/example.conf.d/ \*.conf*\
    *- /etc/foo/example.conf.d/ \*.conf*

   */etc/foo/example.conf does NOT exist:*

     */run/foo/example.conf does exist:*

     *- /run/foo/example.conf*\
      *- /usr/lib/foo/example.conf.d/ \*.conf*     \
      *- /run/foo/example.conf.d/ \*.conf*\
      *- /etc/foo/example.conf.d/ \*.conf*

     */run/foo/example.conf does NOT exist:*

     *- /usr/lib/foo/example.conf*\
      *- /usr/lib/foo/example.conf.d/ \*.conf*     \
      *- /run/foo/example.conf.d/ \*.conf*\
      *- /etc/foo/example.conf.d/ \*.conf*

```
#include "libeconf.h"
econf_file *key_file = NULL;
econf_err error;
error = econf_readConfig (&key_file,
                          "foo",
                          "/usr/lib",
                          "example",
                          "conf",
                          "=", "#");
econf_free (key_file);
```

### econf\_err econf\_readConfigWithCallback (econf\_file \*\* key\_file, const char \*project, const char \*usr\_subdir, const char \*config\_name, const char \*config\_suffix, const char \*delim, const char \*comment, bool (\*callback)(const char \*filename, const void \*data), const void \*callback\_data)

 *Evaluating key/values of a given configuration by reading and merging all needed/available files from different directories. Order is:*

   */etc/$project/$config\_name.$config\_suffix does exist:*

     *-- /etc/$project/$config\_name.$config\_suffix*\
      *-- $usr\_subdir/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*     \
      *-- /run/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*\
      *-- /etc/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*

   */etc/$project/$config\_name.$config\_suffix does NOT exist:*

     *- /run/$project/$config\_name.$config\_suffix does exist:*

      *-- /run/$project/$config\_name.$config\_suffix*\
       *-- $usr\_subdir/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*      \
       *-- /run/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*\
       *-- /etc/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*

     *- /run/$project/$config\_name.$config\_suffix does NOT exist:*

      *-- $usr\_subdir/$project/$config\_name.$config\_suffix*\
       *-- $usr\_subdir/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*      \
       *-- /run/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*\
       *-- /etc/$project/$config\_name.$config\_suffix.d/ \*.$config\_suffix*

   *No main $config\_name.$config\_suffix file is defined or must not be parsed:*

      *-- $usr\_subdir/$project.d/\*.$config\_suffix*      \
       *-- /run/$project.d/\*.$config\_suffix*\
       *-- /etc/$project.d/\*.$config\_suffix*\

*For each parsed file the user defined function will be called in order e.g.* *to check the correct file permissions.*

**Parameters:**

*key\_file content of parsed file(s)*\
 *project name of the project used as subdirectory, can be NULL*\
 *usr\_subdir absolute path of the first directory (often "/usr/lib")*\
 *config\_name basename of the configuration file. If it is NULL, drop-ins without* *a main configuration file will be parsed only.*\
 *config\_suffix suffix of the configuration file. Can also be NULL.*\
 *delim delimiters of key/value e.g. '\\t ='. If delim contains space characters* *AND none space characters, multiline values are not parseable.*\
 *comment array of characters which define the start of a comment*\
 *callback function which will be called for each file. This user defined function has the* *pathname as parameter and returns true if this file can be parsed. If not, the parsing of* *all files will be aborted and ECONF\_PARSING\_CALLBACK\_FAILED will be returned.*\
 *callback\_data pointer which will be given to the callback function.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

*Example: Reading content in different cases in following order:*

   */etc/foo/example.conf does exist:*

   *- /etc/foo/example.conf*\
    *- /usr/lib/foo/example.conf.d/ \*.conf*   \
    *- /run/foo/example.conf.d/ \*.conf*\
    *- /etc/foo/example.conf.d/ \*.conf*

   */etc/foo/example.conf does NOT exist:*

     */run/foo/example.conf does exist:*

     *- /run/foo/example.conf*\
      *- /usr/lib/foo/example.conf.d/ \*.conf*     \
      *- /run/foo/example.conf.d/ \*.conf*\
      *- /etc/foo/example.conf.d/ \*.conf*

     */run/foo/example.conf does NOT exist:*

     *- /usr/lib/foo/example.conf*\
      *- /usr/lib/foo/example.conf.d/ \*.conf*     \
      *- /run/foo/example.conf.d/ \*.conf*\
      *- /etc/foo/example.conf.d/ \*.conf*

```
#include "libeconf.h"
bool checkFile(const char *filename, const void *data) {
  /* checking code which returns true or false */
  return true;
}
econf_file *key_file = NULL;
econf_err error;
error = econf_readConfigWithCallback (&key_file,
                                      "foo",
                                      "/usr/lib",
                                      "example",
                                      "conf",
                                      "=", "#",
                                      checkFile,
                                      NULL);
econf_free (key_file);
```

### econf\_err econf\_readFile (econf\_file \*\* result, const char \* file\_name, const char \* delim, const char \* comment)

*Process the file of the given file\_name and save its contents into key\_file object.*

**Parameters:**

*result content of parsed file* \
 *file\_name absolute path of parsed file* \
 *delim delimiters of key/value e.g. '\\t ='* \
 *comment array of characters which define the start of a comment*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

*Usage:*

```
#include "libeconf.h"
econf_file *key_file = NULL;
econf_err error;
error = econf_readFile (&key_file, "/etc/test.conf", "=", "#");
econf_free (key_file);
```

*Default behaviour if entries have the same name in one file: The first hit will be returned. Further entries will be ignored. This can be changed by setting the environment variable JOIN\_SAME\_ENTRIES (see econf\_set\_opt). In that case entries with the same name will be joined to one single entry.*

### econf\_err econf\_readFileWithCallback (econf\_file \*\* result, const char \* file\_name, const char \* delim, const char \* comment, bool (\*callback)(const char \*filename, const void \*data), const void \*callback\_data)

*Process the file of the given file\_name and save its contents into key\_file object. The user defined function will be called in order e.g. to check the correct file permissions.*

**Parameters:**

*result content of parsed file*\
 *file\_name absolute path of parsed file*\
 *delim delimiters of key/value e.g. '\\t ='*\
 *comment array of characters which define the start of a comment*\
 *callback function which will be called for the given filename. This user defined function has the pathname as parameter and returns true if this file can be parsed. If not, the parsing will be aborted and ECONF\_PARSING\_CALLBACK\_FAILED will be returned.*\
 *callback\_data pointer which will be given to the callback function.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

*Usage:*

```
#include "libeconf.h"
bool checkFile(const char *filename, const void *data) {
  /* checking code which returns true or false */
  return true;
}
econf_file *key_file = NULL;
econf_err error;
error = econf_readFileWithCallback (&key_file, "/etc/test.conf", "=", "#", checkFile, NULL);
econf_free (key_file);
```

*Default behaviour if entries have the same name in one file: The first hit will be returned. Further entries will be ignored. This can be changed by setting the environment variable JOIN\_SAME\_ENTRIES (see econf\_set\_opt). In that case entries with the same name will be joined to one single entry.*

### econf\_err econf\_mergeFiles (econf\_file \*\* merged\_file, econf\_file \* usr\_file, econf\_file \* etc\_file)

*Merge the contents of two key\_files objects. Entries in etc\_file will be preferred. Comment and delimiter tag will be taken from usr\_file. This can be changed by calling the functions econf\_set\_comment\_tag and econf\_set\_delimiter\_tag.*

**Parameters:**

*merged\_file merged data* \
 *usr\_file First data block which has to be merged.* \
 *etc\_file Second data block which has to be merged.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

*Usage:*

```
#include "libeconf.h"
econf_file *key_file_1 = NULL, *key_file_2 = NULL, *key_file_ret = NULL
econf_err error;
error = econf_readFile (&key_file1, "/usr/etc/test.conf", "=", "#");
error = econf_readFile (&key_file2, /etc/test.conf", "=", "#");
error = econf_mergeFiles (&key_file_ret, key_file_1, key_file_2);
econf_free (key_file_ret);
econf_free (key_file_1);
econf_free (key_file_2);
```

### econf\_err econf\_newKeyFile (econf\_file \*\* result, char delimiter, char comment)

*Create a new econf\_file object.*

**Parameters:**

*result Pointer to the allocated econf\_file object.* \
 *delimiter delimiter of key/value e.g. '='* \
 *comment Character which defines the start of a comment.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_newIniFile (econf\_file \*\* result)

*Create a new econf\_file object in IniFile format. So the delimiter will be '=' and comments are beginning with '#'.*

**Parameters:**

*result Pointer to the allocated econf\_file object.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_writeFile (econf\_file \* key\_file, const char \* save\_to\_dir, const char \* file\_name)

*Write content of an econf\_file struct to specified location.*

**Parameters:**

*key\_file Data which has to be written.* \
 *save\_to\_dir Directory into which the file has to be written.* \
 *file\_name filename (with suffix)*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### char\* econf\_getPath (econf\_file \* kf)

*Evaluating path name.*

**Parameters:**

*kf given/parsed data*

**Returns:**

*Absolute path name or an empty string if kf is a result of already merged data (e.G. returned by econf\_readDirs).*

### econf\_err econf\_getGroups (econf\_file \* kf, size\_t \* length, char \*\*\* groups)

*Evaluating all group entries.*

**Parameters:**

*kf given/parsed data* \
 *length Length of the returned group array.* \
 *groups String array of evaluated groups.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getKeys (econf\_file \* kf, const char \* group, size\_t \* length, char \*\*\* keys)

*Evaluating all keys.*

**Parameters:**

*kf given/parsed data* \
 *group Group name for which the keys have to be evaluated or NULL for keys, which do not belong to a group.*\
 *length Length of the returned key array.* \
 *keys String array of evaluated keys.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getIntValue (econf\_file \* kf, const char \* group, const char \* key, int32\_t \* result)

*Evaluating int32 value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result determined value*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getInt64Value (econf\_file \* kf, const char \* group, const char \* key, int64\_t \* result)

*Evaluating int64 value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result determined value*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getUIntValue (econf\_file \* kf, const char \* group, const char \* key, uint32\_t \* result)

*Evaluating uint32 value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result determined value*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getUInt64Value (econf\_file \* kf, const char \* group, const char \* key, uint64\_t \* result)

*Evaluating uint64 value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result determined value*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getFloatValue (econf\_file \* kf, const char \* group, const char \* key, float \* result)

*Evaluating float value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result determined value*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getDoubleValue (econf\_file \* kf, const char \* group, const char \* key, double \* result)

*Evaluating double value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result determined value*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getStringValue (econf\_file \* kf, const char \* group, const char \* key, char \*\* result)

*Evaluating string value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result A newly allocated string or NULL in error case.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getBoolValue (econf\_file \* kf, const char \* group, const char \* key, bool \* result)

*Evaluating bool value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result determined value*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getIntValueDef (econf\_file \* kf, const char \* group, const char \* key, int32\_t \* result, int32\_t def)

*Evaluating int32 value for given group/key. If key is not found, the default value is returned and error is ECONF\_NOKEY.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result determined value* \
 *def Default value if the value has not been found.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getInt64ValueDef (econf\_file \* kf, const char \* group, const char \* key, int64\_t \* result, int64\_t def)

*Evaluating int64 value for given group/key. If key is not found, the default value is returned and error is ECONF\_NOKEY.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result determined value* \
 *def Default value if the value has not been found.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getUIntValueDef (econf\_file \* kf, const char \* group, const char \* key, uint32\_t \* result, uint32\_t def)

*Evaluating uint32 value for given group/key. If key is not found, the default value is returned and error is ECONF\_NOKEY.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result determined value* \
 *def Default value if the value has not been found.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getUInt64ValueDef (econf\_file \* kf, const char \* group, const char \* key, uint64\_t \* result, uint64\_t def)

*Evaluating uint64 value for given group/key. If key is not found, the default value is returned and error is ECONF\_NOKEY.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result determined value* \
 *def Default value if the value has not been found.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getFloatValueDef (econf\_file \* kf, const char \* group, const char \* key, float \* result, float def)

*Evaluating float value for given group/key. If key is not found, the default value is returned and error is ECONF\_NOKEY.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result determined value* \
 *def Default value if the value has not been found.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getDoubleValueDef (econf\_file \* kf, const char \* group, const char \* key, double \* result, double def)

*Evaluating double value for given group/key. If key is not found, the default value is returned and error is ECONF\_NOKEY.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result determined value* \
 *def Default value if the value has not been found.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getStringValueDef (econf\_file \* kf, const char \* group, const char \* key, char \*\* result, char \* def)

*Evaluating string value for given group/key. If key is not found, the default value is returned and error is ECONF\_NOKEY.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result Returns a newly allocated string, even if 'default' is returned.* \
 *def Default value if the value has not been found.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_getBoolValueDef (econf\_file \* kf, const char \* group, const char \* key, bool \* result, bool def)

*Evaluating bool value for given group/key. If key is not found, the default value is returned and error is ECONF\_NOKEY.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value is requested.* \
 *result determined value* \
 *def Default value if the value has not been found.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_setIntValue (econf\_file \* kf, const char \* group, const char \* key, int32\_t value)

*Set int32 value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value has to be set.* \
 *value Value which has to be set.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_setInt64Value (econf\_file \* kf, const char \* group, const char \* key, int64\_t value)

*Set int64 value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value has to be set.* \
 *value Value which has to be set.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_setUIntValue (econf\_file \* kf, const char \* group, const char \* key, uint32\_t value)

*Set uint32 value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value has to be set.* \
 *value Value which has to be set.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_setUInt64Value (econf\_file \* kf, const char \* group, const char \* key, uint64\_t value)

*Set uint64 value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value has to be set.* \
 *value Value which has to be set.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_setFloatValue (econf\_file \* kf, const char \* group, const char \* key, float value)

*Set float value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value has to be set.* \
 *value Value which has to be set.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_setDoubleValue (econf\_file \* kf, const char \* group, const char \* key, double value)

*Set double value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value has to be set.* \
 *value Value which has to be set.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_setStringValue (econf\_file \* kf, const char \* group, const char \* key, const char \* value)

*Set string value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value has to be set.* \
 *value Value which has to be set.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### econf\_err econf\_setBoolValue (econf\_file \* kf, const char \* group, const char \* key, const char \* value)

*Set bool value for given group/key.*

**Parameters:**

*kf given/parsed data* \
 *group Desired group or NULL if there is no group defined.* \
 *key Key for which the value has to be set.* \
 *value Value which has to be set.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### const char\* econf\_errString (const econf\_err error)

*Convert an econf\_err type to a string.*

**Parameters:**

*error error enum*

**Returns:**

*human readable string*

### void econf\_errLocation (char \*\* filename, uint64\_t \* line\_nr)

*Info about where the error has happened.*

**Parameters:**

*filename Path of the last scanned file.* \
 *line\_nr Number of the last handled line.*

### void econf\_freeArray (char \*\* array)

*Free an array of type char\*\* created by* **econf\_getGroups()** *or* **econf\_getKeys()***.*

**Parameters:**

*array array of strings*

**Returns:**

*void*

### void econf\_freeFile (econf\_file \* key\_file)

*Free memory allocated by e.g.* **econf\_readFile()***,* **econf\_readDirs()***,...*

**Parameters:**

*key\_file allocated data*

**Returns:**

*void*

### char econf\_comment\_tag (econf\_file \* key\_file)

*Returns the comment character tag of the given econf\_file object. This tag will be taken while writing comments to file.*

**Parameters:**

*key\_file econf\_file object.*

**Returns:**

*char comment character tag*

### char econf\_delimiter\_tag (econf\_file \* key\_file)

*Returns the delimiter character of the given econf\_file object. This delimiter will be taken while writing the data to file.*

**Parameters:**

*key\_file econf\_file object.*

**Returns:**

*char delimiter of key/value*

### void econf\_set\_comment\_tag (econf\_file \* key\_file, const char comment)

*Set the comment character tag of the given econf\_file object. This tag will be taken while writing comments to file.*

**Parameters:**

*key\_file econf\_file object.*\
 *comment comment tag*

### void econf\_set\_delimiter\_tag (econf\_file \* key\_file, const char delimiter)

*Set the delimiter character of the given econf\_file object. This delimiter will be taken while writing the data to file.*

**Parameters:**

*key\_file econf\_file object.*\
 *delimiter delimiter of key/value*

### econf\_err econf\_getExtValue (econf\_file \* kf, const char \* group, const char \* key, econf\_ext\_value \*\* result)

*Evaluating more information for given group/key.*

**Parameters:**

*kf given/parsed data*\
 *group Desired group or NULL if there is no group defined.*\
 *key Key for which the value is requested.* \
 *result A newly allocated struct or NULL in error case.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

### void econf\_freeExtValue (econf\_ext\_value \* to\_free)

*Free an complete* **econf\_ext\_value** *struct.*

**Parameters:**

*to\_free struct which has to be freed*

**Returns:**

*void*

### econf\_err econf\_set\_conf\_dirs (const char \*\*dir\_postfix\_list)

*Set a list of directory structures (with order) which describes the directories* *in which the files have to be parsed.*

**Parameters:**

*dir\_postfix\_list list of directory structures.* *E.G. with the given list: {"/conf.d/", ".d/", "/", NULL} files in following* *directories will be parsed: \<default\_dirs\>/\<project\_name\>.\<suffix\>.d/* *\<default\_dirs\>/\<project\_name\>/conf.d/, \<default\_dirs\>/\<project\_name\>.d/,* *\<default\_dirs\>/\<project\_name\>/. The entry \<default\_dirs\>/\<project\_name\>.\<suffix\>.d/* *will be added automatically.*

**Returns:**

*econf\_err ECONF\_SUCCESS or error code*

## SEE ALSO

*econftool*