libeconf 0.6.2
libeconf.h
Go to the documentation of this file.
1/*
2 Copyright (C) 2019 SUSE LLC
3 Author: Pascal Arlt <parlt@suse.com>
4
5 Permission is hereby granted, free of charge, to any person obtaining a copy
6 of this software and associated documentation files (the "Software"), to deal
7 in the Software without restriction, including without limitation the rights
8 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 copies of the Software, and to permit persons to whom the Software is
10 furnished to do so, subject to the following conditions:
11
12 The above copyright notice and this permission notice shall be included in all
13 copies or substantial portions of the Software.
14
15 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 SOFTWARE.
22*/
23
24#pragma once
25
30#include <stdbool.h>
31#include <stdint.h>
32#include <stdlib.h>
33#include <sys/types.h>
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
89
90typedef enum econf_err econf_err;
91
102#define econf_setValue(kf, group, key, value) (( \
103 _Generic((value), \
104 int: econf_setIntValue, \
105 long: econf_setInt64Value, \
106 unsigned int: econf_setUIntValue, \
107 unsigned long: econf_setUInt64Value, \
108 float: econf_setFloatValue, \
109 double: econf_setDoubleValue, \
110 char*: econf_setStringValue, void*: econf_setStringValue)) \
111(kf, group, key, value))
112
119#define econf_free(value) (( \
120 _Generic((value), \
121 econf_file*: econf_freeFile , \
122 char**: econf_freeArray)) \
123(value))
124
125typedef struct econf_file econf_file;
126
155extern econf_err econf_readFile(econf_file **result, const char *file_name,
156 const char *delim, const char *comment);
157
158
197extern econf_err econf_readFileWithCallback(econf_file **result, const char *file_name,
198 const char *delim, const char *comment,
199 bool (*callback)(const char *filename, const void *data),
200 const void *callback_data);
201
231 econf_file *usr_file, econf_file *etc_file);
232
233
326 const char *project,
327 const char *usr_subdir,
328 const char *config_name,
329 const char *config_suffix,
330 const char *delim,
331 const char *comment);
332
439 const char *project,
440 const char *usr_subdir,
441 const char *config_name,
442 const char *config_suffix,
443 const char *delim,
444 const char *comment,
445 bool (*callback)(const char *filename, const void *data),
446 const void *callback_data);
447
448
482extern econf_err __attribute__ ((deprecated("Use the econf_readConfig/econf_readConfigWithCallback instead")))
484 const char *usr_conf_dir,
485 const char *etc_conf_dir,
486 const char *config_name,
487 const char *config_suffix,
488 const char *delim,
489 const char *comment);
490
536extern econf_err __attribute__ ((deprecated("Use the econf_readConfig/econf_readConfigWithCallback instead")))
538 const char *usr_conf_dir,
539 const char *etc_conf_dir,
540 const char *config_name,
541 const char *config_suffix,
542 const char *delim,
543 const char *comment,
544 bool (*callback)(const char *filename, const void *data),
545 const void *callback_data);
546
566 size_t *size,
567 const char *usr_conf_dir,
568 const char *etc_conf_dir,
569 const char *config_name,
570 const char *config_suffix,
571 const char *delim,
572 const char *comment);
573
598 size_t *size,
599 const char *usr_conf_dir,
600 const char *etc_conf_dir,
601 const char *config_name,
602 const char *config_suffix,
603 const char *delim,
604 const char *comment,
605 bool (*callback)(const char *filename, const void *data),
606 const void *callback_data);
607
608/* The API/ABI of the following three functions (econf_newKeyFile,
609 econf_newIniFile and econf_writeFile) are not stable and will change */
610
624extern econf_err econf_newKeyFile(econf_file **result, char delimiter, char comment);
625
634
642extern char econf_comment_tag(econf_file *key_file);
643
651extern char econf_delimiter_tag(econf_file *key_file);
652
660extern void econf_set_comment_tag(econf_file *key_file, const char comment);
661
669extern void econf_set_delimiter_tag(econf_file *key_file, const char delimiter);
670
679extern econf_err econf_writeFile(econf_file *key_file, const char *save_to_dir,
680 const char *file_name);
681
682/* --------------- */
683/* --- GETTERS --- */
684/* --------------- */
685
693extern char *econf_getPath(econf_file *kf);
694
703extern econf_err econf_getGroups(econf_file *kf, size_t *length, char ***groups);
704
715extern econf_err econf_getKeys(econf_file *kf, const char *group, size_t *length, char ***keys);
716
726extern econf_err econf_getIntValue(econf_file *kf, const char *group, const char *key, int32_t *result);
727
737extern econf_err econf_getInt64Value(econf_file *kf, const char *group, const char *key, int64_t *result);
738
748extern econf_err econf_getUIntValue(econf_file *kf, const char *group, const char *key, uint32_t *result);
749
759extern econf_err econf_getUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t *result);
760
770extern econf_err econf_getFloatValue(econf_file *kf, const char *group, const char *key, float *result);
771
781extern econf_err econf_getDoubleValue(econf_file *kf, const char *group, const char *key, double *result);
782
792extern econf_err econf_getStringValue(econf_file *kf, const char *group, const char *key, char **result);
793
803extern econf_err econf_getBoolValue(econf_file *kf, const char *group, const char *key, bool *result);
804
816extern econf_err econf_getIntValueDef(econf_file *kf, const char *group, const char *key, int32_t *result, int32_t def);
817
829extern econf_err econf_getInt64ValueDef(econf_file *kf, const char *group, const char *key, int64_t *result, int64_t def);
830
842extern econf_err econf_getUIntValueDef(econf_file *kf, const char *group, const char *key, uint32_t *result, uint32_t def);
843
855extern econf_err econf_getUInt64ValueDef(econf_file *kf, const char *group, const char *key, uint64_t *result, uint64_t def);
856
868extern econf_err econf_getFloatValueDef(econf_file *kf, const char *group, const char *key, float *result, float def);
869
881extern econf_err econf_getDoubleValueDef(econf_file *kf, const char *group, const char *key, double *result, double def);
882
894extern econf_err econf_getStringValueDef(econf_file *kf, const char *group, const char *key, char **result, char *def);
895
907extern econf_err econf_getBoolValueDef(econf_file *kf, const char *group, const char *key, bool *result, bool def);
908
909/* --------------- */
910/* --- SETTERS --- */
911/* --------------- */
912
922extern econf_err econf_setIntValue(econf_file *kf, const char *group, const char *key, int32_t value);
923
933extern econf_err econf_setInt64Value(econf_file *kf, const char *group, const char *key, int64_t value);
934
944extern econf_err econf_setUIntValue(econf_file *kf, const char *group, const char *key, uint32_t value);
945
955extern econf_err econf_setUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t value);
956
966extern econf_err econf_setFloatValue(econf_file *kf, const char *group, const char *key, float value);
967
977extern econf_err econf_setDoubleValue(econf_file *kf, const char *group, const char *key, double value);
978
988extern econf_err econf_setStringValue(econf_file *kf, const char *group, const char *key, const char *value);
989
999extern econf_err econf_setBoolValue(econf_file *kf, const char *group, const char *key, const char *value);
1000
1001/* --------------- */
1002/* --- HELPERS --- */
1003/* --------------- */
1004
1011extern const char *econf_errString (const econf_err error);
1012
1019extern void econf_errLocation (char **filename, uint64_t *line_nr);
1020
1027extern void econf_freeArray(char **array);
1028
1035extern void econf_freeFile(econf_file *key_file);
1036
1045extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1047
1057extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1059
1069extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1070econf_requirePermissions(mode_t file_perms, mode_t dir_perms);
1071
1080extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1082
1091extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1093
1107extern econf_err econf_set_conf_dirs(const char **dir_postfix_list);
1108
1109#ifdef __cplusplus
1110}
1111#endif
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 h...
econf_err econf_newIniFile(econf_file **result)
Create a new econf_file object in IniFile format.
struct econf_file econf_file
Definition libeconf.h:125
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_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_err econf_getBoolValueDef(econf_file *kf, const char *group, const char *key, bool *result, bool def)
Evaluating bool value for given group/key.
const char * econf_errString(const econf_err error)
Convert an econf_err type to a string.
econf_err econf_setDoubleValue(econf_file *kf, const char *group, const char *key, double value)
Set double value for given group/key.
void econf_followSymlinks(bool allow)
Allowing the parser to follow sym links (default: true).
void econf_set_comment_tag(econf_file *key_file, const char comment)
Set the comment character tag of the given econf_file object.
econf_err econf_mergeFiles(econf_file **merged_file, econf_file *usr_file, econf_file *etc_file)
Merge the contents of two key_files objects.
char econf_delimiter_tag(econf_file *key_file)
Returns the delimiter character of the given econf_file object.
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_getStringValueDef(econf_file *kf, const char *group, const char *key, char **result, char *def)
Evaluating string value for given group/key.
econf_err
libeconf error codes
Definition libeconf.h:41
@ ECONF_FILE_LIST_IS_NULL
Parsed file list is NULL.
Definition libeconf.h:69
@ ECONF_NOMEM
Out of memory.
Definition libeconf.h:47
@ ECONF_NOGROUP
Group not found.
Definition libeconf.h:51
@ ECONF_WRONG_BOOLEAN_VALUE
Wrong boolean value (1/0 true/false yes/no)
Definition libeconf.h:71
@ ECONF_TEXT_AFTER_SECTION
Text after section.
Definition libeconf.h:67
@ ECONF_PARSING_CALLBACK_FAILED
User defined parsing callback has failed.
Definition libeconf.h:85
@ ECONF_PARSE_ERROR
General syntax error in input file.
Definition libeconf.h:59
@ ECONF_WRONG_FILE_PERMISSION
File has wrong file permissions.
Definition libeconf.h:79
@ ECONF_ARGUMENT_IS_NULL_VALUE
Given argument is NULL.
Definition libeconf.h:87
@ ECONF_EMPTY_SECTION_NAME
Empty section name.
Definition libeconf.h:65
@ ECONF_WRITEERROR
Error creating or writing to a file.
Definition libeconf.h:57
@ ECONF_KEY_HAS_NULL_VALUE
Given key has NULL value.
Definition libeconf.h:73
@ ECONF_MISSING_BRACKET
Missing closing section bracket.
Definition libeconf.h:61
@ ECONF_ERROR_FILE_IS_SYM_LINK
File is a sym link which is not permitted.
Definition libeconf.h:83
@ ECONF_WRONG_GROUP
File has wrong group.
Definition libeconf.h:77
@ ECONF_WRONG_DIR_PERMISSION
File has wrong dir permission.
Definition libeconf.h:81
@ ECONF_NOKEY
Key not found.
Definition libeconf.h:53
@ ECONF_MISSING_DELIMITER
Missing delimiter.
Definition libeconf.h:63
@ ECONF_NOFILE
Config file not found.
Definition libeconf.h:49
@ ECONF_WRONG_OWNER
File has wrong owner.
Definition libeconf.h:75
@ ECONF_ERROR
Generic Error.
Definition libeconf.h:45
@ ECONF_EMPTYKEY
Key is NULL or has empty value.
Definition libeconf.h:55
@ ECONF_SUCCESS
General purpose success code.
Definition libeconf.h:43
void econf_requirePermissions(mode_t file_perms, mode_t dir_perms)
All parsed file have to have these file and directory permissions.
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_err econf_setBoolValue(econf_file *kf, const char *group, const char *key, const char *value)
Set bool 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_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_err econf_setUIntValue(econf_file *kf, const char *group, const char *key, uint32_t value)
Set uint32 value for given group/key.
void econf_requireGroup(gid_t group)
All parsed files require this group permission.
econf_err econf_getFloatValue(econf_file *kf, const char *group, const char *key, float *result)
Evaluating float value for given group/key.
char econf_comment_tag(econf_file *key_file)
Returns the comment character tag of the given econf_file object.
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.
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_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_err econf_getBoolValue(econf_file *kf, const char *group, const char *key, bool *result)
Evaluating bool 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_getInt64Value(econf_file *kf, const char *group, const char *key, int64_t *result)
Evaluating int64 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_setFloatValue(econf_file *kf, const char *group, const char *key, float value)
Set float value for given group/key.
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_err econf_newKeyFile(econf_file **result, char delimiter, char comment)
Create a new econf_file object.
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_setIntValue(econf_file *kf, const char *group, const char *key, int32_t value)
Set int32 value for given group/key.
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.
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_getGroups(econf_file *kf, size_t *length, char ***groups)
Evaluating all group entries.
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_getFloatValueDef(econf_file *kf, const char *group, const char *key, float *result, float def)
Evaluating float value for given group/key.
void econf_requireOwner(uid_t owner)
All parsed files require this user permission.
econf_err econf_getStringValue(econf_file *kf, const char *group, const char *key, char **result)
Evaluating string value for given group/key.
void econf_reset_security_settings(void)
Reset all UID, GID, permissions,... restrictions for parsed files/dirs.
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_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_err econf_getDoubleValue(econf_file *kf, const char *group, const char *key, double *result)
Evaluating double value for given group/key.
void econf_freeArray(char **array)
Free an array of type char** created by econf_getGroups() or econf_getKeys().
void econf_errLocation(char **filename, uint64_t *line_nr)
Info about where the error has happened.
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.
char * econf_getPath(econf_file *kf)
Evaluating path name.
void econf_freeFile(econf_file *key_file)
Free memory allocated by e.g.
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_getUIntValue(econf_file *kf, const char *group, const char *key, uint32_t *result)
Evaluating uint32 value for given group/key.
econf_err econf_getKeys(econf_file *kf, const char *group, size_t *length, char ***keys)
Evaluating all keys.