libeconf: include/libeconf.h File Reference

libeconf 0.5.2

Macros | Typedefs | Enumerations | Functions | Variables
libeconf.h File Reference

Public API for the econf library. More...

`#include <stdbool.h>`
`#include <stdint.h>`
`#include <stdlib.h>`
`#include <sys/types.h>`

Go to the source code of this file.

## Macros
#define | econf_setValue(kf, group, key, value)
| Generic macro calls setter function depending on value type. More...
#define | econf_free(value)
| Generic macro to free memory allocated by econf_ functions. More...

## Typedefs
typedef enum econf_err | econf_err
typedef struct econf_file | econf_file

## 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 More...

## Functions
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. More...
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. More...
econf_err | econf_mergeFiles (econf_file **merged_file, econf_file *usr_file, econf_file *etc_file)
| Merge the contents of two key_files objects. More...
econf_err | econf_readDirs (econf_file **key_file, const char *usr_conf_dir, const char *etc_conf_dir, const char *project_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 two different directories (normally in /usr/etc and /etc). More...
econf_err | econf_readDirsWithCallback (econf_file **key_file, const char *usr_conf_dir, const char *etc_conf_dir, const char *project_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 for every given configuration files in two different directories (normally in /usr/etc and /etc). More...
econf_err | econf_readDirsHistory (econf_file ***key_files, size_t *size, const char *usr_conf_dir, const char *etc_conf_dir, const char *project_name, const char *config_suffix, const char *delim, const char *comment)
| Evaluating key/values for every given configuration files in two different directories (normally in /usr/etc and /etc). More...
econf_err | econf_readDirsHistoryWithCallback (econf_file ***key_files, size_t *size, const char *usr_conf_dir, const char *etc_conf_dir, const char *project_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 for every given configuration files in two different directories (normally in /usr/etc and /etc). More...
econf_err | econf_newKeyFile (econf_file **result, char delimiter, char comment)
| Create a new econf_file object. More...
econf_err | econf_newIniFile (econf_file **result)
| Create a new econf_file object in IniFile format. More...
char | econf_comment_tag (econf_file *key_file)
| Returns the comment character tag of the given econf_file object. More...
char | econf_delimiter_tag (econf_file *key_file)
| Returns the delimiter character of the given econf_file object. More...
void | econf_set_comment_tag (econf_file *key_file, const char comment)
| Set the comment character tag of the given econf_file object. More...
void | econf_set_delimiter_tag (econf_file *key_file, const char delimiter)
| Set the delimiter character of the given econf_file object. More...
econf_err | econf_writeFile (econf_file *key_file, const char *save_to_dir, const char *file_name)
| Write content of a econf_file struct to specified location. More...
char * | econf_getPath (econf_file *kf)
| Evaluating path name. More...
econf_err | econf_getGroups (econf_file *kf, size_t *length, char ***groups)
| Evaluating all group entries. More...
econf_err | econf_getKeys (econf_file *kf, const char *group, size_t *length, char ***keys)
| Evaluating all keys. More...
econf_err | econf_getIntValue (econf_file *kf, const char *group, const char *key, int32_t *result)
| Evaluating int32 value for given group/key. More...
econf_err | econf_getInt64Value (econf_file *kf, const char *group, const char *key, int64_t *result)
| Evaluating int64 value for given group/key. More...
econf_err | econf_getUIntValue (econf_file *kf, const char *group, const char *key, uint32_t *result)
| Evaluating uint32 value for given group/key. More...
econf_err | econf_getUInt64Value (econf_file *kf, const char *group, const char *key, uint64_t *result)
| Evaluating uint64 value for given group/key. More...
econf_err | econf_getFloatValue (econf_file *kf, const char *group, const char *key, float *result)
| Evaluating float value for given group/key. More...
econf_err | econf_getDoubleValue (econf_file *kf, const char *group, const char *key, double *result)
| Evaluating double value for given group/key. More...
econf_err | econf_getStringValue (econf_file *kf, const char *group, const char *key, char **result)
| Evaluating string value for given group/key. More...
econf_err | econf_getBoolValue (econf_file *kf, const char *group, const char *key, bool *result)
| Evaluating bool value for given group/key. More...
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. More...
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. More...
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. More...
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. More...
econf_err | econf_getFloatValueDef (econf_file *kf, const char *group, const char *key, float *result, float def)
| Evaluating float value for given group/key. More...
econf_err | econf_getDoubleValueDef (econf_file *kf, const char *group, const char *key, double *result, double def)
| Evaluating double value for given group/key. More...
econf_err | econf_getStringValueDef (econf_file *kf, const char *group, const char *key, char **result, char *def)
| Evaluating string value for given group/key. More...
econf_err | econf_getBoolValueDef (econf_file *kf, const char *group, const char *key, bool *result, bool def)
| Evaluating bool value for given group/key. More...
econf_err | econf_setIntValue (econf_file *kf, const char *group, const char *key, int32_t value)
| Set int32 value for given group/key. More...
econf_err | econf_setInt64Value (econf_file *kf, const char *group, const char *key, int64_t value)
| Set int64 value for given group/key. More...
econf_err | econf_setUIntValue (econf_file *kf, const char *group, const char *key, uint32_t value)
| Set uint32 value for given group/key. More...
econf_err | econf_setUInt64Value (econf_file *kf, const char *group, const char *key, uint64_t value)
| Set uint64 value for given group/key. More...
econf_err | econf_setFloatValue (econf_file *kf, const char *group, const char *key, float value)
| Set float value for given group/key. More...
econf_err | econf_setDoubleValue (econf_file *kf, const char *group, const char *key, double value)
| Set double value for given group/key. More...
econf_err | econf_setStringValue (econf_file *kf, const char *group, const char *key, const char *value)
| Set string value for given group/key. More...
econf_err | econf_setBoolValue (econf_file *kf, const char *group, const char *key, const char *value)
| Set bool value for given group/key. More...
const char * | econf_errString (const econf_err error)
| Convert an econf_err type to a string. More...
void | econf_errLocation (char **filename, uint64_t *line_nr)
| Info about where the error has happened. More...
void | econf_freeArray (char **array)
| Free an array of type char** created by econf_getGroups() or econf_getKeys(). More...
void | econf_freeFile (econf_file *key_file)
| Free memory allocated by e.g. More...
void | __attribute__ ((deprecated("use one of econf_read*WithCallback instead"))) econf_requireOwner(uid_t owner)
| All parsed files require this user permission. More...
econf_err | econf_set_conf_dirs (const char **dir_postfix_list)
| Sets a list of directory structures (with order) which describes the directories in which the files have to be parsed. More...

## Variables
void mode_t | dir_perms

## Detailed Description

Public API for the econf library.

Definition in file libeconf.h.

## Macro Definition Documentation

## ◆ econf_setValue

#define econf_setValue | ( |  | kf,
|  |  | group,
|  |  | key,
|  |  | value
| ) |  |

Value:
(( \
_Generic((value), \
int: econf_setIntValue, \
long: econf_setInt64Value, \
unsigned int: econf_setUIntValue, \
unsigned long: econf_setUInt64Value, \
float: econf_setFloatValue, \
double: econf_setDoubleValue, \
char*: econf_setStringValue, void*: econf_setStringValue)) \
(kf, group, key, value))
econf_setFloatValue
econf_err econf_setFloatValue(econf_file *kf, const char *group, const char *key, float value)
Set float value for given group/key.
econf_setDoubleValue
econf_err econf_setDoubleValue(econf_file *kf, const char *group, const char *key, double value)
Set double value for given group/key.
econf_setInt64Value
econf_err econf_setInt64Value(econf_file *kf, const char *group, const char *key, int64_t value)
Set int64 value for given group/key.
econf_setUIntValue
econf_err econf_setUIntValue(econf_file *kf, const char *group, const char *key, uint32_t value)
Set uint32 value for given group/key.
econf_setStringValue
econf_err econf_setStringValue(econf_file *kf, const char *group, const char *key, const char *value)
Set string value for given group/key.
econf_setUInt64Value
econf_err econf_setUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t value)
Set uint64 value for given group/key.
econf_setIntValue
econf_err econf_setIntValue(econf_file *kf, const char *group, const char *key, int32_t value)
Set int32 value for given group/key.

Generic macro calls setter function depending on value type.

Use: econf_setValue(econf_file *key_file, char *group, char *key, generic value);

Replace generic with one of the supported value types. Supported Types: int, long, unsigned int, unsigned long, float, double, string (as *char). Note: Does not detect "yes", "no", 1 and 0 as boolean type. If you want to set a bool value use "true" or "false" or use setBoolValue() directly.

Definition at line 100 of file libeconf.h.

## ◆ econf_free

#define econf_free | ( |  | value | ) |

Value:
(( \
_Generic((value), \
econf_file*: econf_freeFile , \
char**: econf_freeArray)) \
(value))
econf_file
struct econf_file econf_file
Definition: libeconf.h:123
econf_freeArray
void econf_freeArray(char **array)
Free an array of type char** created by econf_getGroups() or econf_getKeys().
econf_freeFile
void econf_freeFile(econf_file *key_file)
Free memory allocated by e.g.

Generic macro to free memory allocated by econf_ functions.

Use: econf_free(generic value);

Replace generic with one of the supported value types. Supported Types: char** and econf_file*.

Definition at line 117 of file libeconf.h.

## Typedef Documentation

## ◆ econf_err

typedef enum econf_err econf_err

Definition at line 88 of file libeconf.h.

## ◆ econf_file

typedef struct econf_file econf_file

Definition at line 123 of file libeconf.h.

## Enumeration Type Documentation

## ◆ econf_err

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 is NULL or 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 permission.
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.

Definition at line 41 of file libeconf.h.

## Function Documentation

## ◆ econf_readFile()

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 =". 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

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 ECONF_JOIN_SAME_ENTRIES. In that case entries with the same name will be joined to one single entry.

## ◆ econf_readFileWithCallback()

econf_err econf_readFileWithCallback | ( | econf_file ** | result,
|  | const char * | file_name,
|  | const char * | delim,
|  | const char * | comment,
|  | bool(*)(const char *filename, const void *data) | callback,
|  | 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 =". 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 the given filename. This user defined function has the pathname as paramter 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 ECONF_JOIN_SAME_ENTRIES. In that case entries with the same name will be joined to one single entry.

## ◆ econf_mergeFiles()

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 prefered. 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_readDirs()

econf_err econf_readDirs | ( | econf_file ** | key_file,
|  | const char * | usr_conf_dir,
|  | const char * | etc_conf_dir,
|  | const char * | project_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 two different directories (normally in /usr/etc and /etc).

Parameters

  key_file | content of parsed file(s)
  usr_conf_dir | absolute path of the first directory (normally "/usr/etc")
  etc_conf_dir | absolute path of the second directory (normally "/etc")
  project_name | basename of the configuration file
  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 of example.conf in /usr/etc and /etc directory.

#include "libeconf.h"
econf_file *key_file = NULL;
econf_err error;
error = econf_readDirs (&key_file,
"/usr/etc",
"/etc",
"example",
"conf",
"=", "#");
econf_free (key_file);

## ◆ econf_readDirsWithCallback()

econf_err econf_readDirsWithCallback | ( | econf_file ** | key_file,
|  | const char * | usr_conf_dir,
|  | const char * | etc_conf_dir,
|  | const char * | project_name,
|  | const char * | config_suffix,
|  | const char * | delim,
|  | const char * | comment,
|  | bool(*)(const char *filename, const void *data) | callback,
|  | const void * | callback_data
| ) |  |

Evaluating key/values for every given configuration files in two different directories (normally in /usr/etc and /etc).

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

Parameters

  key_files | list of parsed file(s). Each entry includes all key/value, path, comments,... information of the regarding file.
  size | Size of the evaluated key_files list.
  usr_conf_dir | absolute path of the first directory (normally "/usr/etc")
  etc_conf_dir | absolute path of the second directory (normally "/etc")
  project_name | basename of the configuration file
  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 paramter 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 of example.conf in /usr/etc and /etc directory.

#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_readDirsWithCallback (&key_file,
"/usr/etc",
"/etc",
"example",
"conf",
"=", "#",
checkFile,
NULL);
econf_free (key_file);

## ◆ econf_readDirsHistory()

econf_err econf_readDirsHistory | ( | econf_file *** | key_files,
|  | size_t * | size,
|  | const char * | usr_conf_dir,
|  | const char * | etc_conf_dir,
|  | const char * | project_name,
|  | const char * | config_suffix,
|  | const char * | delim,
|  | const char * | comment
| ) |  |

Evaluating key/values for every given configuration files in two different directories (normally in /usr/etc and /etc).

Returns a list of read configuration files and their values.

Parameters

  key_files | list of parsed file(s). Each entry includes all key/value, path, comments,... information of the regarding file.
  size | Size of the evaluated key_files list.
  usr_conf_dir | absolute path of the first directory (normally "/usr/etc")
  etc_conf_dir | absolute path of the second directory (normally "/etc")
  project_name | basename of the configuration file
  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

## ◆ econf_readDirsHistoryWithCallback()

econf_err econf_readDirsHistoryWithCallback | ( | econf_file *** | key_files,
|  | size_t * | size,
|  | const char * | usr_conf_dir,
|  | const char * | etc_conf_dir,
|  | const char * | project_name,
|  | const char * | config_suffix,
|  | const char * | delim,
|  | const char * | comment,
|  | bool(*)(const char *filename, const void *data) | callback,
|  | const void * | callback_data
| ) |  |

Evaluating key/values for every given configuration files in two different directories (normally in /usr/etc and /etc).

For each parsed file the user defined function will be called in order e.g. to check the correct file permissions. Returns a list of read configuration files and their values.

Parameters

  key_files | list of parsed file(s). Each entry includes all key/value, path, comments,... information of the regarding file.
  size | Size of the evaluated key_files list.
  usr_conf_dir | absolute path of the first directory (normally "/usr/etc")
  etc_conf_dir | absolute path of the second directory (normally "/etc")
  project_name | basename of the configuration file
  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 paramter 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

## ◆ econf_newKeyFile()

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

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 ECONF_JOIN_SAME_ENTRIES. In that case entries with the same name will be joined to one single entry.

## ◆ econf_newIniFile()

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_comment_tag()

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

## ◆ econf_delimiter_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

## ◆ econf_set_comment_tag()

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

## ◆ econf_set_delimiter_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_writeFile()

econf_err econf_writeFile | ( | econf_file * | key_file,
|  | const char * | save_to_dir,
|  | const char * | file_name
| ) |  |

Write content of a 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

## ◆ econf_getPath()

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_getGroups()

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_getKeys()

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_getIntValue()

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_getInt64Value()

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_getUIntValue()

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_getUInt64Value()

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_getFloatValue()

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_getDoubleValue()

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_getStringValue()

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_getBoolValue()

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_getIntValueDef()

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_getInt64ValueDef()

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_getUIntValueDef()

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_getUInt64ValueDef()

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_getFloatValueDef()

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_getDoubleValueDef()

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_getStringValueDef()

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_getBoolValueDef()

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_setIntValue()

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_setInt64Value()

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_setUIntValue()

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_setUInt64Value()

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_setFloatValue()

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_setDoubleValue()

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_setStringValue()

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_setBoolValue()

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

## ◆ econf_errString()

const char* econf_errString | ( | const econf_err | error | ) |

Convert an econf_err type to a string.

Parameters

  error | error enum

Returns
  human readable string

## ◆ econf_errLocation()

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.

## ◆ econf_freeArray()

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

## ◆ econf_freeFile()

void econf_freeFile | ( | econf_file * | key_file | ) |

Free memory allocated by e.g.

econf_readFile(), econf_readDirs(),...

Parameters

  key_file | allocated data

Returns
  void

## ◆ __attribute__()

void __attribute__ | ( | (deprecated("use one of econf_read*WithCallback instead")) |  | ) |

All parsed files require this user permission.

Reset all UID, GID, permissions,...

Allowing the parser to follow sym links (default: true).

All parsed file have to have these file and directory permissions.

All parsed files require this group permission.

DEPRECATED: Use the callback in econf_readFileWithCallback, econf_readDirsWithCallback or econf_readDirsHistoryWithCallback instead.

Parameters

  owner | User ID

Returns
  void

DEPRECATED: Use the callback in econf_readFileWithCallback, econf_readDirsWithCallback or econf_readDirsHistoryWithCallback instead.

Parameters

  group | Group ID

Returns
  void

DEPRECATED: Use the callback in econf_readFileWithCallback, econf_readDirsWithCallback or econf_readDirsHistoryWithCallback instead.

Parameters

  file_perms | file permissions
  dir_perms | dir permissions

Returns
  void

DEPRECATED: Use the callback in econf_readFileWithCallback, econf_readDirsWithCallback or econf_readDirsHistoryWithCallback instead.

Parameters

  allow | allow to follow sym links.

Returns
  void

restrictions for parsed files/dirs. DEPRECATED: Use the callback in econf_readFileWithCallback, econf_readDirsWithCallback or econf_readDirsHistoryWithCallback instead.

Returns
  void

## ◆ econf_set_conf_dirs()

econf_err econf_set_conf_dirs | ( | const char ** | dir_postfix_list | ) |

Sets 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

## Variable Documentation

## ◆ dir_perms

void mode_t dir_perms

Definition at line 852 of file libeconf.h.