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
36 extern "C" {
37 #endif
38 
41 enum econf_err {
88 };
89 
90 typedef 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 
125 typedef struct econf_file econf_file;
126 
155 extern econf_err econf_readFile(econf_file **result, const char *file_name,
156  const char *delim, const char *comment);
157 
158 
197 extern 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 
230 extern econf_err econf_mergeFiles(econf_file **merged_file,
231  econf_file *usr_file, econf_file *etc_file);
232 
233 
325 extern econf_err econf_readConfig (econf_file **key_file,
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 
438 extern econf_err econf_readConfigWithCallback(econf_file **key_file,
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 
482 extern econf_err __attribute__ ((deprecated("Use the econf_readConfig/econf_readConfigWithCallback instead")))
483 econf_readDirs(econf_file **key_file,
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 
536 extern 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 
565 extern econf_err econf_readDirsHistory(econf_file ***key_files,
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 
597 extern econf_err econf_readDirsHistoryWithCallback(econf_file ***key_files,
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 
624 extern econf_err econf_newKeyFile(econf_file **result, char delimiter, char comment);
625 
633 extern econf_err econf_newIniFile(econf_file **result);
634 
642 extern char econf_comment_tag(econf_file *key_file);
643 
651 extern char econf_delimiter_tag(econf_file *key_file);
652 
660 extern void econf_set_comment_tag(econf_file *key_file, const char comment);
661 
669 extern void econf_set_delimiter_tag(econf_file *key_file, const char delimiter);
670 
679 extern econf_err econf_writeFile(econf_file *key_file, const char *save_to_dir,
680  const char *file_name);
681 
682 /* --------------- */
683 /* --- GETTERS --- */
684 /* --------------- */
685 
693 extern char *econf_getPath(econf_file *kf);
694 
703 extern econf_err econf_getGroups(econf_file *kf, size_t *length, char ***groups);
704 
715 extern econf_err econf_getKeys(econf_file *kf, const char *group, size_t *length, char ***keys);
716 
726 extern econf_err econf_getIntValue(econf_file *kf, const char *group, const char *key, int32_t *result);
727 
737 extern econf_err econf_getInt64Value(econf_file *kf, const char *group, const char *key, int64_t *result);
738 
748 extern econf_err econf_getUIntValue(econf_file *kf, const char *group, const char *key, uint32_t *result);
749 
759 extern econf_err econf_getUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t *result);
760 
770 extern econf_err econf_getFloatValue(econf_file *kf, const char *group, const char *key, float *result);
771 
781 extern econf_err econf_getDoubleValue(econf_file *kf, const char *group, const char *key, double *result);
782 
792 extern econf_err econf_getStringValue(econf_file *kf, const char *group, const char *key, char **result);
793 
803 extern econf_err econf_getBoolValue(econf_file *kf, const char *group, const char *key, bool *result);
804 
816 extern econf_err econf_getIntValueDef(econf_file *kf, const char *group, const char *key, int32_t *result, int32_t def);
817 
829 extern econf_err econf_getInt64ValueDef(econf_file *kf, const char *group, const char *key, int64_t *result, int64_t def);
830 
842 extern econf_err econf_getUIntValueDef(econf_file *kf, const char *group, const char *key, uint32_t *result, uint32_t def);
843 
855 extern econf_err econf_getUInt64ValueDef(econf_file *kf, const char *group, const char *key, uint64_t *result, uint64_t def);
856 
868 extern econf_err econf_getFloatValueDef(econf_file *kf, const char *group, const char *key, float *result, float def);
869 
881 extern econf_err econf_getDoubleValueDef(econf_file *kf, const char *group, const char *key, double *result, double def);
882 
894 extern econf_err econf_getStringValueDef(econf_file *kf, const char *group, const char *key, char **result, char *def);
895 
907 extern econf_err econf_getBoolValueDef(econf_file *kf, const char *group, const char *key, bool *result, bool def);
908 
909 /* --------------- */
910 /* --- SETTERS --- */
911 /* --------------- */
912 
922 extern econf_err econf_setIntValue(econf_file *kf, const char *group, const char *key, int32_t value);
923 
933 extern econf_err econf_setInt64Value(econf_file *kf, const char *group, const char *key, int64_t value);
934 
944 extern econf_err econf_setUIntValue(econf_file *kf, const char *group, const char *key, uint32_t value);
945 
955 extern econf_err econf_setUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t value);
956 
966 extern econf_err econf_setFloatValue(econf_file *kf, const char *group, const char *key, float value);
967 
977 extern econf_err econf_setDoubleValue(econf_file *kf, const char *group, const char *key, double value);
978 
988 extern econf_err econf_setStringValue(econf_file *kf, const char *group, const char *key, const char *value);
989 
999 extern econf_err econf_setBoolValue(econf_file *kf, const char *group, const char *key, const char *value);
1000 
1001 /* --------------- */
1002 /* --- HELPERS --- */
1003 /* --------------- */
1004 
1011 extern const char *econf_errString (const econf_err error);
1012 
1019 extern void econf_errLocation (char **filename, uint64_t *line_nr);
1020 
1027 extern void econf_freeArray(char **array);
1028 
1035 extern void econf_freeFile(econf_file *key_file);
1036 
1045 extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1046 econf_requireOwner(uid_t owner);
1047 
1057 extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1058 econf_requireGroup(gid_t group);
1059 
1069 extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1070 econf_requirePermissions(mode_t file_perms, mode_t dir_perms);
1071 
1080 extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1081 econf_followSymlinks(bool allow);
1082 
1091 extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
1093 
1107 extern econf_err econf_set_conf_dirs(const char **dir_postfix_list);
1108 
1109 #ifdef __cplusplus
1110 }
1111 #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:125
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
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 a 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
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)
Sets 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