libeconf.h
Go to the documentation of this file.
/*
Copyright (C) 2019 SUSE LLC
Author: Pascal Arlt <parlt@suse.com>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
*/
#pragma once
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <sys/types.h>
#ifdef __cplusplus
extern "C" {
#endif
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
};
typedef enum econf_err econf_err;
#define econf_setValue(kf, group, key, 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))
#define econf_free(value) (( \
_Generic((value), \
econf_file*: econf_freeFile , \
char**: econf_freeArray)) \
(value))
typedef struct econf_file econf_file;
extern econf_err econf_readFile(econf_file **result, const char *file_name,
const char *delim, const char *comment);
extern 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);
extern econf_err econf_mergeFiles(econf_file **merged_file,
econf_file *usr_file, econf_file *etc_file);
extern 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);
extern 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);
extern econf_err __attribute__ ((deprecated("Use the econf_readConfig/econf_readConfigWithCallback instead")))
econf_readDirs(econf_file **key_file,
const char *usr_conf_dir,
const char *etc_conf_dir,
const char *config_name,
const char *config_suffix,
const char *delim,
const char *comment);
extern econf_err __attribute__ ((deprecated("Use the econf_readConfig/econf_readConfigWithCallback instead")))
econf_readDirsWithCallback(econf_file **key_file,
const char *usr_conf_dir,
const char *etc_conf_dir,
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);
extern econf_err econf_readDirsHistory(econf_file ***key_files,
size_t *size,
const char *usr_conf_dir,
const char *etc_conf_dir,
const char *config_name,
const char *config_suffix,
const char *delim,
const char *comment);
extern econf_err econf_readDirsHistoryWithCallback(econf_file ***key_files,
size_t *size,
const char *usr_conf_dir,
const char *etc_conf_dir,
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);
extern econf_err econf_newKeyFile(econf_file **result, char delimiter, char comment);
extern econf_err econf_newKeyFile_with_options(econf_file **result, const char *options);
extern econf_err econf_newIniFile(econf_file **result);
extern char econf_comment_tag(econf_file *key_file);
extern char econf_delimiter_tag(econf_file *key_file);
extern void econf_set_comment_tag(econf_file *key_file, const char comment);
extern void econf_set_delimiter_tag(econf_file *key_file, const char delimiter);
extern econf_err econf_writeFile(econf_file *key_file, const char *save_to_dir,
const char *file_name);
/* --------------- */
/* --- GETTERS --- */
/* --------------- */
extern char *econf_getPath(econf_file *kf);
extern econf_err econf_getGroups(econf_file *kf, size_t *length, char ***groups);
extern econf_err econf_getKeys(econf_file *kf, const char *group, size_t *length, char ***keys);
extern econf_err econf_getIntValue(econf_file *kf, const char *group, const char *key, int32_t *result);
extern econf_err econf_getInt64Value(econf_file *kf, const char *group, const char *key, int64_t *result);
extern econf_err econf_getUIntValue(econf_file *kf, const char *group, const char *key, uint32_t *result);
extern econf_err econf_getUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t *result);
extern econf_err econf_getFloatValue(econf_file *kf, const char *group, const char *key, float *result);
extern econf_err econf_getDoubleValue(econf_file *kf, const char *group, const char *key, double *result);
extern econf_err econf_getStringValue(econf_file *kf, const char *group, const char *key, char **result);
extern econf_err econf_getBoolValue(econf_file *kf, const char *group, const char *key, bool *result);
extern econf_err econf_getIntValueDef(econf_file *kf, const char *group, const char *key, int32_t *result, int32_t def);
extern econf_err econf_getInt64ValueDef(econf_file *kf, const char *group, const char *key, int64_t *result, int64_t def);
extern econf_err econf_getUIntValueDef(econf_file *kf, const char *group, const char *key, uint32_t *result, uint32_t def);
extern econf_err econf_getUInt64ValueDef(econf_file *kf, const char *group, const char *key, uint64_t *result, uint64_t def);
extern econf_err econf_getFloatValueDef(econf_file *kf, const char *group, const char *key, float *result, float def);
extern econf_err econf_getDoubleValueDef(econf_file *kf, const char *group, const char *key, double *result, double def);
extern econf_err econf_getStringValueDef(econf_file *kf, const char *group, const char *key, char **result, char *def);
extern econf_err econf_getBoolValueDef(econf_file *kf, const char *group, const char *key, bool *result, bool def);
/* --------------- */
/* --- SETTERS --- */
/* --------------- */
extern econf_err econf_setIntValue(econf_file *kf, const char *group, const char *key, int32_t value);
extern econf_err econf_setInt64Value(econf_file *kf, const char *group, const char *key, int64_t value);
extern econf_err econf_setUIntValue(econf_file *kf, const char *group, const char *key, uint32_t value);
extern econf_err econf_setUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t value);
extern econf_err econf_setFloatValue(econf_file *kf, const char *group, const char *key, float value);
extern econf_err econf_setDoubleValue(econf_file *kf, const char *group, const char *key, double value);
extern econf_err econf_setStringValue(econf_file *kf, const char *group, const char *key, const char *value);
extern econf_err econf_setBoolValue(econf_file *kf, const char *group, const char *key, const char *value);
/* --------------- */
/* --- HELPERS --- */
/* --------------- */
extern const char *econf_errString (const econf_err error);
extern void econf_errLocation (char **filename, uint64_t *line_nr);
extern char **econf_freeArray(char **array);
/* helper so that __attribute__((cleanup(econf_freeArrayp)) may be used */
static __inline__ void econf_freeArrayp(char ***array) {
if (*array)
*array = econf_freeArray(*array);
}
extern econf_file *econf_freeFile(econf_file *key_file);
/* helper so that __attribute__((cleanup(econf_freeFilep)) may be used */
static __inline__ void econf_freeFilep(econf_file **key_file) {
if (*key_file)
*key_file = econf_freeFile(*key_file);
}
extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
econf_requireOwner(uid_t owner);
extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
econf_requireGroup(gid_t group);
extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
econf_requirePermissions(mode_t file_perms, mode_t dir_perms);
extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
econf_followSymlinks(bool allow);
extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
econf_reset_security_settings(void);
extern econf_err __attribute__ ((deprecated("Is not thread-safe. Use econf_newKeyFile_with_options instead")))
econf_set_conf_dirs(const char **dir_postfix_list);
#ifdef __cplusplus
}
#endif
econf_set_conf_dirs
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 ha...
econf_newIniFile
econf_err econf_newIniFile(econf_file **result)
Create a new econf_file object in IniFile format.
econf_file
struct econf_file econf_file
Definition libeconf.h:129
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_readConfig
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...
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.
econf_errString
const char * econf_errString(const econf_err error)
Convert an econf_err type to a string.
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_followSymlinks
void econf_followSymlinks(bool allow)
Allowing the parser to follow sym links (default: true).
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.
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.
econf_delimiter_tag
char econf_delimiter_tag(econf_file *key_file)
Returns the delimiter character of the given econf_file object.
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_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.
econf_err
econf_err
libeconf error codes
Definition libeconf.h:41
ECONF_FILE_LIST_IS_NULL
@ ECONF_FILE_LIST_IS_NULL
Parsed file list is NULL.
Definition libeconf.h:69
ECONF_VALUE_CONVERSION_ERROR
@ ECONF_VALUE_CONVERSION_ERROR
Value cannot be converted.
Definition libeconf.h:91
ECONF_NOMEM
@ ECONF_NOMEM
Out of memory.
Definition libeconf.h:47
ECONF_NOGROUP
@ ECONF_NOGROUP
Group not found.
Definition libeconf.h:51
ECONF_WRONG_BOOLEAN_VALUE
@ ECONF_WRONG_BOOLEAN_VALUE
Wrong boolean value (1/0 true/false yes/no).
Definition libeconf.h:71
ECONF_TEXT_AFTER_SECTION
@ ECONF_TEXT_AFTER_SECTION
Text after section.
Definition libeconf.h:67
ECONF_PARSING_CALLBACK_FAILED
@ ECONF_PARSING_CALLBACK_FAILED
User defined parsing callback has failed.
Definition libeconf.h:85
ECONF_PARSE_ERROR
@ ECONF_PARSE_ERROR
General syntax error in input file.
Definition libeconf.h:59
ECONF_WRONG_FILE_PERMISSION
@ ECONF_WRONG_FILE_PERMISSION
File has wrong file permissions.
Definition libeconf.h:79
ECONF_ARGUMENT_IS_NULL_VALUE
@ ECONF_ARGUMENT_IS_NULL_VALUE
Given argument is NULL.
Definition libeconf.h:87
ECONF_OPTION_NOT_FOUND
@ ECONF_OPTION_NOT_FOUND
Given option not found.
Definition libeconf.h:89
ECONF_EMPTY_SECTION_NAME
@ ECONF_EMPTY_SECTION_NAME
Empty section name.
Definition libeconf.h:65
ECONF_WRITEERROR
@ ECONF_WRITEERROR
Error creating or writing to a file.
Definition libeconf.h:57
ECONF_KEY_HAS_NULL_VALUE
@ ECONF_KEY_HAS_NULL_VALUE
Given key has NULL value.
Definition libeconf.h:73
ECONF_MISSING_BRACKET
@ ECONF_MISSING_BRACKET
Missing closing section bracket.
Definition libeconf.h:61
ECONF_ERROR_FILE_IS_SYM_LINK
@ ECONF_ERROR_FILE_IS_SYM_LINK
File is a sym link which is not permitted.
Definition libeconf.h:83
ECONF_WRONG_GROUP
@ ECONF_WRONG_GROUP
File has wrong group.
Definition libeconf.h:77
ECONF_WRONG_DIR_PERMISSION
@ ECONF_WRONG_DIR_PERMISSION
File has wrong dir permission.
Definition libeconf.h:81
ECONF_NOKEY
@ ECONF_NOKEY
Key not found.
Definition libeconf.h:53
ECONF_MISSING_DELIMITER
@ ECONF_MISSING_DELIMITER
Missing delimiter.
Definition libeconf.h:63
ECONF_NOFILE
@ ECONF_NOFILE
Config file not found.
Definition libeconf.h:49
ECONF_WRONG_OWNER
@ ECONF_WRONG_OWNER
File has wrong owner.
Definition libeconf.h:75
ECONF_ERROR
@ ECONF_ERROR
Generic Error.
Definition libeconf.h:45
ECONF_EMPTYKEY
@ ECONF_EMPTYKEY
Key is NULL or has empty value.
Definition libeconf.h:55
ECONF_SUCCESS
@ ECONF_SUCCESS
General purpose success code.
Definition libeconf.h:43
econf_requirePermissions
void econf_requirePermissions(mode_t file_perms, mode_t dir_perms)
All parsed file have to have these file and directory permissions.
econf_freeFile
econf_file * econf_freeFile(econf_file *key_file)
Free memory allocated and returned by econf_readFile(), econf_readFileWithCallback,...
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 *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 for every given configuration files in two different directories (normally in /...
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.
econf_freeArrayp
static __inline__ void econf_freeArrayp(char ***array)
Definition libeconf.h:1093
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.
econf_readDirs
econf_err econf_readDirs(econf_file **key_file, const char *usr_conf_dir, const char *etc_conf_dir, 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 t...
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_requireGroup
void econf_requireGroup(gid_t group)
All parsed files require this group permission.
econf_getFloatValue
econf_err econf_getFloatValue(econf_file *kf, const char *group, const char *key, float *result)
Evaluating float value for given group/key.
econf_comment_tag
char econf_comment_tag(econf_file *key_file)
Returns the comment character tag of the given econf_file object.
econf_writeFile
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.
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 *config_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 /...
econf_newKeyFile_with_options
econf_err econf_newKeyFile_with_options(econf_file **result, const char *options)
Create a new econf_file object with special options.
econf_readFileWithCallback
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.
econf_getBoolValue
econf_err econf_getBoolValue(econf_file *kf, const char *group, const char *key, bool *result)
Evaluating bool 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_getInt64Value
econf_err econf_getInt64Value(econf_file *kf, const char *group, const char *key, int64_t *result)
Evaluating int64 value for given group/key.
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.
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_readDirsWithCallback
econf_err econf_readDirsWithCallback(econf_file **key_file, const char *usr_conf_dir, const char *etc_conf_dir, 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 for every given configuration files in two different directories (normally in /...
econf_newKeyFile
econf_err econf_newKeyFile(econf_file **result, char delimiter, char comment)
Create a new econf_file object.
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.
econf_freeFilep
static __inline__ void econf_freeFilep(econf_file **key_file)
Definition libeconf.h:1111
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.
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.
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.
econf_getGroups
econf_err econf_getGroups(econf_file *kf, size_t *length, char ***groups)
Evaluating all group entries.
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.
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.
econf_requireOwner
void econf_requireOwner(uid_t owner)
All parsed files require this user permission.
econf_getStringValue
econf_err econf_getStringValue(econf_file *kf, const char *group, const char *key, char **result)
Evaluating string value for given group/key.
econf_reset_security_settings
void econf_reset_security_settings(void)
Reset all UID, GID, permissions,... restrictions for parsed files/dirs.
econf_freeArray
char ** econf_freeArray(char **array)
Free an array of type char** created by econf_getGroups() or econf_getKeys().
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.
econf_readConfigWithCallback
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...
econf_getDoubleValue
econf_err econf_getDoubleValue(econf_file *kf, const char *group, const char *key, double *result)
Evaluating double value for given group/key.
econf_errLocation
void econf_errLocation(char **filename, uint64_t *line_nr)
Info about where the error has happened.
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.
econf_getPath
char * econf_getPath(econf_file *kf)
Evaluating path name.
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.
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.
econf_getKeys
econf_err econf_getKeys(econf_file *kf, const char *group, size_t *length, char ***keys)
Evaluating all keys.