libeconf - Public API for the econf library.
NAME DESCRIPTION Example 1 Example 2 UAPI Configuration Files Specification Bindings SYNOPSIS Typedefs Enumerations Functions Detailed Description Typedef Documentation typedef struct econf_file econf_file typedef struct econf_ext_value econf_ext_value Enumeration Type Documentation enum econf_err SEE ALSONAME
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,
ECONF_ARGUMENT_IS_NULL_VALUE = 22,
ECONF_OPTION_NOT_FOUND = 23,
ECONF_VALUE_CONVERSION_ERROR = 24 }
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/share, /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, const
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, const
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, const
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,
const 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, const
float def)
Evaluating float value for given group/key.
econf_err econf_getDoubleValueDef (econf_file
*kf, const char *group, const char *key, double *result,
const double def)
Evaluating double value for given group/key.
econf_err econf_getStringValueDef (econf_file
*kf, const char *group, const char *key, char **result,
const char *def)
Evaluating string value for given group/key.
econf_err econf_getBoolValueDef (econf_file *kf,
const char *group, const char *key, bool *result, const 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_freeArrayp (char ***array)
Free an array of type char*** by using e.g. __attribute__ in
the declaration.
void econf_freeFile (econf_file **key_file)
Free memory allocated by e.g. econf_readConfig.
RI "void econf_freeFilep (econf_file
*key_file)"
Free memory allocated by e.g. econf_readConfig by
using __attribute__ in the declaration.
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.
econf_err econf_setExtValue (econf_file *kf,
const char *group, const char *key, econf_ext_value
*value)
Setting more information (e.g. comments) 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.
ECONF_ARGUMENT_IS_NULL_VALUE
Given argument is NULL.
ECONF_OPTION_NOT_FOUND
Given option not found.
ECONF_VALUE_CONVERSION_ERROR
Value cannot be converted.
SEE ALSO
Read/Write configuration files:
econf_readConfig(3), econf_readConfigWithCallback(3), econf_readFile(3), econf_readFileWithCallback(3), econf_mergeFiles(3), econf_writeFile(3)
get/set key/value:
econf_getKeys(3), econf_getGroups(3)
econf_getBoolValue(3), econf_getBoolValueDef(3), econf_getDoubleValue(3), econf_getDoubleValueDef(3), econf_getExtValue(3), econf_getFloatValue(3), econf_getFloatValueDef(3), econf_getInt64Value(3), econf_getInt64ValueDef(3), econf_getIntValue(3), econf_getIntValueDef(3), econf_getPath(3), econf_getStringValue(3), econf_getStringValueDef(3), econf_getUInt64Value(3), econf_getUInt64ValueDef(3), econf_getUIntValue(3), econf_getUIntValueDef(3)
econf_setBoolValue(3) econf_setDoubleValue(3), econf_setExtValue(3), econf_setFloatValue(3), econf_setInt64Value(3), econf_setIntValue(3), econf_setStringValue(3), econf_setUInt64Value(3)
Initialization:
econf_newIniFile(3), econf_newKeyFile(3)
Freeing:
econf_freeArray(3), econf_freeExtValue(3), econf_freeFile(3)
General setup:
econf_comment_tag(3), econf_set_comment_tag(3), econf_delimiter_tag(3), econf_set_delimiter_tag(3), econf_set_conf_dirs(3)
Error handling:
econf_errLocation(3), econf_errString(3)
Tools:
econftool(3)