libeconf  0.7.1
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
36 extern "C" {
37 #endif
38 
41 enum econf_err {
92 };
93 
94 typedef enum econf_err econf_err;
95 
106 #define econf_setValue(kf, group, key, value) (( \
107  _Generic((value), \
108  int: econf_setIntValue, \
109  long: econf_setInt64Value, \
110  unsigned int: econf_setUIntValue, \
111  unsigned long: econf_setUInt64Value, \
112  float: econf_setFloatValue, \
113  double: econf_setDoubleValue, \
114  char*: econf_setStringValue, void*: econf_setStringValue)) \
115 (kf, group, key, value))
116 
123 #define econf_free(value) (( \
124  _Generic((value), \
125  econf_file*: econf_freeFile , \
126  char**: econf_freeArray)) \
127 (value))
128 
129 typedef struct econf_file econf_file;
130 
155 extern econf_err econf_readFile(econf_file **result, const char *file_name,
156  const char *delim, const char *comment);
157 
158 
198 extern econf_err econf_readFileWithCallback(econf_file **result, const char *file_name,
199  const char *delim, const char *comment,
200  bool (*callback)(const char *filename, const void *data),
201  const void *callback_data);
202 
231 extern econf_err econf_mergeFiles(econf_file **merged_file,
232  econf_file *usr_file, econf_file *etc_file);
233 
234 
332 extern econf_err econf_readConfig (econf_file **key_file,
333  const char *project,
334  const char *usr_subdir,
335  const char *config_name,
336  const char *config_suffix,
337  const char *delim,
338  const char *comment);
339 
452  const char *project,
453  const char *usr_subdir,
454  const char *config_name,
455  const char *config_suffix,
456  const char *delim,
457  const char *comment,
458  bool (*callback)(const char *filename, const void *data),
459  const void *callback_data);
460 
461 
496 extern econf_err __attribute__ ((deprecated("Use the econf_readConfig/econf_readConfigWithCallback instead")))
497 econf_readDirs(econf_file **key_file,
498  const char *usr_conf_dir,
499  const char *etc_conf_dir,
500  const char *config_name,
501  const char *config_suffix,
502  const char *delim,
503  const char *comment);
504 
551 extern econf_err __attribute__ ((deprecated("Use the econf_readConfig/econf_readConfigWithCallback instead")))
553  const char *usr_conf_dir,
554  const char *etc_conf_dir,
555  const char *config_name,
556  const char *config_suffix,
557  const char *delim,
558  const char *comment,
559  bool (*callback)(const char *filename, const void *data),
560  const void *callback_data);
561 
580 extern econf_err econf_readDirsHistory(econf_file ***key_files,
581  size_t *size,
582  const char *usr_conf_dir,
583  const char *etc_conf_dir,
584  const char *config_name,
585  const char *config_suffix,
586  const char *delim,
587  const char *comment);
588 
613  size_t *size,
614  const char *usr_conf_dir,
615  const char *etc_conf_dir,
616  const char *config_name,
617  const char *config_suffix,
618  const char *delim,
619  const char *comment,
620  bool (*callback)(const char *filename, const void *data),
621  const void *callback_data);
622 
631 extern econf_err econf_newKeyFile(econf_file **result, char delimiter, char comment);
632 
686 extern econf_err econf_newKeyFile_with_options(econf_file **result, const char *options);
687 
695 extern econf_err econf_newIniFile(econf_file **result);
696 
704 extern char econf_comment_tag(econf_file *key_file);
705 
713 extern char econf_delimiter_tag(econf_file *key_file);
714 
722 extern void econf_set_comment_tag(econf_file *key_file, const char comment);
723 
731 extern void econf_set_delimiter_tag(econf_file *key_file, const char delimiter);
732 
741 extern econf_err econf_writeFile(econf_file *key_file, const char *save_to_dir,
742  const char *file_name);
743 
744 /* --------------- */
745 /* --- GETTERS --- */
746 /* --------------- */
747 
755 extern char *econf_getPath(econf_file *kf);
756 
765 extern econf_err econf_getGroups(econf_file *kf, size_t *length, char ***groups);
766 
777 extern econf_err econf_getKeys(econf_file *kf, const char *group, size_t *length, char ***keys);
778 
788 extern econf_err econf_getIntValue(econf_file *kf, const char *group, const char *key, int32_t *result);
789 
799 extern econf_err econf_getInt64Value(econf_file *kf, const char *group, const char *key, int64_t *result);
800 
810 extern econf_err econf_getUIntValue(econf_file *kf, const char *group, const char *key, uint32_t *result);
811 
821 extern econf_err econf_getUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t *result);
822 
832 extern econf_err econf_getFloatValue(econf_file *kf, const char *group, const char *key, float *result);
833 
843 extern econf_err econf_getDoubleValue(econf_file *kf, const char *group, const char *key, double *result);
844 
854 extern econf_err econf_getStringValue(econf_file *kf, const char *group, const char *key, char **result);
855 
865 extern econf_err econf_getBoolValue(econf_file *kf, const char *group, const char *key, bool *result);
866 
878 extern econf_err econf_getIntValueDef(econf_file *kf, const char *group, const char *key, int32_t *result, int32_t def);
879 
891 extern econf_err econf_getInt64ValueDef(econf_file *kf, const char *group, const char *key, int64_t *result, int64_t def);
892 
904 extern econf_err econf_getUIntValueDef(econf_file *kf, const char *group, const char *key, uint32_t *result, uint32_t def);
905 
917 extern econf_err econf_getUInt64ValueDef(econf_file *kf, const char *group, const char *key, uint64_t *result, uint64_t def);
918 
930 extern econf_err econf_getFloatValueDef(econf_file *kf, const char *group, const char *key, float *result, float def);
931 
943 extern econf_err econf_getDoubleValueDef(econf_file *kf, const char *group, const char *key, double *result, double def);
944 
956 extern econf_err econf_getStringValueDef(econf_file *kf, const char *group, const char *key, char **result, char *def);
957 
969 extern econf_err econf_getBoolValueDef(econf_file *kf, const char *group, const char *key, bool *result, bool def);
970 
971 /* --------------- */
972 /* --- SETTERS --- */
973 /* --------------- */
974 
984 extern econf_err econf_setIntValue(econf_file *kf, const char *group, const char *key, int32_t value);
985 
995 extern econf_err econf_setInt64Value(econf_file *kf, const char *group, const char *key, int64_t value);
996 
1006 extern econf_err econf_setUIntValue(econf_file *kf, const char *group, const char *key, uint32_t value);
1007 
1017 extern econf_err econf_setUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t value);
1018 
1028 extern econf_err econf_setFloatValue(econf_file *kf, const char *group, const char *key, float value);
1029 
1039 extern econf_err econf_setDoubleValue(econf_file *kf, const char *group, const char *key, double value);
1040 
1050 extern econf_err econf_setStringValue(econf_file *kf, const char *group, const char *key, const char *value);
1051 
1061 extern econf_err econf_setBoolValue(econf_file *kf, const char *group, const char *key, const char *value);
1062 
1063 /* --------------- */
1064 /* --- HELPERS --- */
1065 /* --------------- */
1066 
1073 extern const char *econf_errString (const econf_err error);
1074 
1081 extern void econf_errLocation (char **filename, uint64_t *line_nr);
1082 
1089 extern void econf_freeArray(char **array);
1090 
1097 extern void econf_freeFile(econf_file *key_file);
1098 
1107 extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1108 econf_requireOwner(uid_t owner);
1109 
1119 extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1120 econf_requireGroup(gid_t group);
1121 
1131 extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1132 econf_requirePermissions(mode_t file_perms, mode_t dir_perms);
1133 
1142 extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1143 econf_followSymlinks(bool allow);
1144 
1153 extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1155 
1173 extern econf_err __attribute__ ((deprecated("Is not thread-safe. Use econf_newKeyFile_with_options instead")))
1174 econf_set_conf_dirs(const char **dir_postfix_list);
1175 
1176 #ifdef __cplusplus
1177 }
1178 #endif
Empty section name.
Definition: libeconf.h:65
General syntax error in input file.
Definition: libeconf.h:59
void econf_requireGroup(gid_t group)
All parsed files require this group permission.
Given argument is NULL.
Definition: libeconf.h:87
Missing delimiter.
Definition: libeconf.h:63
File is a sym link which is not permitted.
Definition: libeconf.h:83
struct econf_file econf_file
Definition: libeconf.h:129
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_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_setFloatValue(econf_file *kf, const char *group, const char *key, float value)
Set float value for given group/key.
char econf_delimiter_tag(econf_file *key_file)
Returns the delimiter character of the given econf_file object.
Text after section.
Definition: libeconf.h:67
econf_err econf_setDoubleValue(econf_file *kf, const char *group, const char *key, double value)
Set double value for given group/key.
Config file not found.
Definition: libeconf.h:49
char econf_comment_tag(econf_file *key_file)
Returns the comment character tag of the given econf_file object.
econf_err econf_getFloatValueDef(econf_file *kf, const char *group, const char *key, float *result, float def)
Evaluating float value for given group/key.
econf_err econf_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...
void econf_reset_security_settings(void)
Reset all UID, GID, permissions,...
econf_err econf_getUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t *result)
Evaluating uint64 value for given group/key.
void econf_errLocation(char **filename, uint64_t *line_nr)
Info about where the error has happened.
void econf_requirePermissions(mode_t file_perms, mode_t dir_perms)
All parsed file have to have these file and directory permissions.
char * econf_getPath(econf_file *kf)
Evaluating path name.
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_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_getUIntValue(econf_file *kf, const char *group, const char *key, uint32_t *result)
Evaluating uint32 value for given group/key.
void econf_requireOwner(uid_t owner)
All parsed files require this user permission.
void econf_freeArray(char **array)
Free an array of type char** created by econf_getGroups() or econf_getKeys().
File has wrong owner.
Definition: libeconf.h:75
void econf_freeFile(econf_file *key_file)
Free memory allocated by e.g.
Group not found.
Definition: libeconf.h:51
Value cannot be converted.
Definition: libeconf.h:91
econf_err econf_getBoolValue(econf_file *kf, const char *group, const char *key, bool *result)
Evaluating bool value for given group/key.
File has wrong group.
Definition: libeconf.h:77
econf_err econf_getGroups(econf_file *kf, size_t *length, char ***groups)
Evaluating all group entries.
econf_err econf_getInt64ValueDef(econf_file *kf, const char *group, const char *key, int64_t *result, int64_t def)
Evaluating int64 value for given group/key.
econf_err econf_getDoubleValueDef(econf_file *kf, const char *group, const char *key, double *result, double def)
Evaluating double value for given group/key.
File has wrong dir permission.
Definition: libeconf.h:81
Given key has NULL value.
Definition: libeconf.h:73
econf_err econf_getStringValue(econf_file *kf, const char *group, const char *key, char **result)
Evaluating string value for given group/key.
Key is NULL or has empty value.
Definition: libeconf.h:55
econf_err econf_getKeys(econf_file *kf, const char *group, size_t *length, char ***keys)
Evaluating all keys.
econf_err econf_getFloatValue(econf_file *kf, const char *group, const char *key, float *result)
Evaluating float value for given group/key.
File has wrong file permissions.
Definition: libeconf.h:79
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_getStringValueDef(econf_file *kf, const char *group, const char *key, char **result, char *def)
Evaluating string value for given group/key.
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_err econf_setInt64Value(econf_file *kf, const char *group, const char *key, int64_t value)
Set int64 value for given group/key.
Parsed file list is NULL.
Definition: libeconf.h:69
General purpose success code.
Definition: libeconf.h:43
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_setUIntValue(econf_file *kf, const char *group, const char *key, uint32_t value)
Set uint32 value for given group/key.
Out of memory.
Definition: libeconf.h:47
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_newKeyFile(econf_file **result, char delimiter, char comment)
Create a new econf_file object.
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_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_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 /...
User defined parsing callback has failed.
Definition: libeconf.h:85
Given option not found.
Definition: libeconf.h:89
econf_err econf_newKeyFile_with_options(econf_file **result, const char *options)
Create a new econf_file object with special options.
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_getIntValueDef(econf_file *kf, const char *group, const char *key, int32_t *result, int32_t def)
Evaluating int32 value for given group/key.
void econf_set_delimiter_tag(econf_file *key_file, const char delimiter)
Set the delimiter character of the given econf_file object.
Wrong boolean value (1/0 true/false yes/no)
Definition: libeconf.h:71
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_getBoolValueDef(econf_file *kf, const char *group, const char *key, bool *result, bool def)
Evaluating bool 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.
econf_err econf_newIniFile(econf_file **result)
Create a new econf_file object in IniFile format.
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 h...
Missing closing section bracket.
Definition: libeconf.h:61
const char * econf_errString(const econf_err error)
Convert an econf_err type to a string.
econf_err
libeconf error codes
Definition: libeconf.h:41
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_mergeFiles(econf_file **merged_file, econf_file *usr_file, econf_file *etc_file)
Merge the contents of two key_files objects.
Key not found.
Definition: libeconf.h:53
void econf_followSymlinks(bool allow)
Allowing the parser to follow sym links (default: true).
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_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 /...
Generic Error.
Definition: libeconf.h:45
econf_err econf_setIntValue(econf_file *kf, const char *group, const char *key, int32_t value)
Set int32 value for given group/key.
Error creating or writing to a file.
Definition: libeconf.h:57