libeconf: include/libeconf.h Source File

libeconf 0.5.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 {
43 ECONF_SUCCESS = 0,
45 ECONF_ERROR = 1,
47 ECONF_NOMEM = 2,
49 ECONF_NOFILE = 3,
51 ECONF_NOGROUP = 4,
53 ECONF_NOKEY = 5,
55 ECONF_EMPTYKEY = 6,
57 ECONF_WRITEERROR = 7,
59 ECONF_PARSE_ERROR = 8,
61 ECONF_MISSING_BRACKET = 9,
63 ECONF_MISSING_DELIMITER = 10,
65 ECONF_EMPTY_SECTION_NAME = 11,
67 ECONF_TEXT_AFTER_SECTION = 12,
69 ECONF_FILE_LIST_IS_NULL = 13,
71 ECONF_WRONG_BOOLEAN_VALUE = 14,
73 ECONF_KEY_HAS_NULL_VALUE = 15,
75 ECONF_WRONG_OWNER = 16,
77 ECONF_WRONG_GROUP = 17,
79 ECONF_WRONG_FILE_PERMISSION = 18,
81 ECONF_WRONG_DIR_PERMISSION = 19,
83 ECONF_ERROR_FILE_IS_SYM_LINK = 20,
85 ECONF_PARSING_CALLBACK_FAILED = 21
86 };
87
88 typedef enum econf_err econf_err;
89
100 #define econf_setValue(kf, group, key, value) (( \
101 _Generic((value), \
102 int: econf_setIntValue, \
103 long: econf_setInt64Value, \
104 unsigned int: econf_setUIntValue, \
105 unsigned long: econf_setUInt64Value, \
106 float: econf_setFloatValue, \
107 double: econf_setDoubleValue, \
108 char*: econf_setStringValue, void*: econf_setStringValue)) \
109 (kf, group, key, value))
110
117 #define econf_free(value) (( \
118 _Generic((value), \
119 econf_file*: econf_freeFile , \
120 char**: econf_freeArray)) \
121 (value))
122
123 typedef struct econf_file econf_file;
124
153 extern econf_err econf_readFile(econf_file **result, const char *file_name,
154 const char *delim, const char *comment);
155
156
195 extern econf_err econf_readFileWithCallback(econf_file **result, const char *file_name,
196 const char *delim, const char *comment,
197 bool (*callback)(const char *filename, const void *data),
198 const void *callback_data);
199
228 extern econf_err econf_mergeFiles(econf_file **merged_file,
229 econf_file *usr_file, econf_file *etc_file);
230
263 extern econf_err econf_readDirs(econf_file **key_file,
264 const char *usr_conf_dir,
265 const char *etc_conf_dir,
266 const char *project_name,
267 const char *config_suffix,
268 const char *delim,
269 const char *comment);
270
317 extern econf_err econf_readDirsWithCallback(econf_file **key_file,
318 const char *usr_conf_dir,
319 const char *etc_conf_dir,
320 const char *project_name,
321 const char *config_suffix,
322 const char *delim,
323 const char *comment,
324 bool (*callback)(const char *filename, const void *data),
325 const void *callback_data);
326
345 extern econf_err econf_readDirsHistory(econf_file ***key_files,
346 size_t *size,
347 const char *usr_conf_dir,
348 const char *etc_conf_dir,
349 const char *project_name,
350 const char *config_suffix,
351 const char *delim,
352 const char *comment);
353
377 extern econf_err econf_readDirsHistoryWithCallback(econf_file ***key_files,
378 size_t *size,
379 const char *usr_conf_dir,
380 const char *etc_conf_dir,
381 const char *project_name,
382 const char *config_suffix,
383 const char *delim,
384 const char *comment,
385 bool (*callback)(const char *filename, const void *data),
386 const void *callback_data);
387
388 /* The API/ABI of the following three functions (econf_newKeyFile,
389 econf_newIniFile and econf_writeFile) are not stable and will change */
390
404 extern econf_err econf_newKeyFile(econf_file **result, char delimiter, char comment);
405
413 extern econf_err econf_newIniFile(econf_file **result);
414
422 extern char econf_comment_tag(econf_file *key_file);
423
431 extern char econf_delimiter_tag(econf_file *key_file);
432
440 extern void econf_set_comment_tag(econf_file *key_file, const char comment);
441
449 extern void econf_set_delimiter_tag(econf_file *key_file, const char delimiter);
450
459 extern econf_err econf_writeFile(econf_file *key_file, const char *save_to_dir,
460 const char *file_name);
461
462 /* --------------- */
463 /* --- GETTERS --- */
464 /* --------------- */
465
473 extern char *econf_getPath(econf_file *kf);
474
483 extern econf_err econf_getGroups(econf_file *kf, size_t *length, char ***groups);
484
495 extern econf_err econf_getKeys(econf_file *kf, const char *group, size_t *length, char ***keys);
496
506 extern econf_err econf_getIntValue(econf_file *kf, const char *group, const char *key, int32_t *result);
507
517 extern econf_err econf_getInt64Value(econf_file *kf, const char *group, const char *key, int64_t *result);
518
528 extern econf_err econf_getUIntValue(econf_file *kf, const char *group, const char *key, uint32_t *result);
529
539 extern econf_err econf_getUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t *result);
540
550 extern econf_err econf_getFloatValue(econf_file *kf, const char *group, const char *key, float *result);
551
561 extern econf_err econf_getDoubleValue(econf_file *kf, const char *group, const char *key, double *result);
562
572 extern econf_err econf_getStringValue(econf_file *kf, const char *group, const char *key, char **result);
573
583 extern econf_err econf_getBoolValue(econf_file *kf, const char *group, const char *key, bool *result);
584
596 extern econf_err econf_getIntValueDef(econf_file *kf, const char *group, const char *key, int32_t *result, int32_t def);
597
609 extern econf_err econf_getInt64ValueDef(econf_file *kf, const char *group, const char *key, int64_t *result, int64_t def);
610
622 extern econf_err econf_getUIntValueDef(econf_file *kf, const char *group, const char *key, uint32_t *result, uint32_t def);
623
635 extern econf_err econf_getUInt64ValueDef(econf_file *kf, const char *group, const char *key, uint64_t *result, uint64_t def);
636
648 extern econf_err econf_getFloatValueDef(econf_file *kf, const char *group, const char *key, float *result, float def);
649
661 extern econf_err econf_getDoubleValueDef(econf_file *kf, const char *group, const char *key, double *result, double def);
662
674 extern econf_err econf_getStringValueDef(econf_file *kf, const char *group, const char *key, char **result, char *def);
675
687 extern econf_err econf_getBoolValueDef(econf_file *kf, const char *group, const char *key, bool *result, bool def);
688
689 /* --------------- */
690 /* --- SETTERS --- */
691 /* --------------- */
692
702 extern econf_err econf_setIntValue(econf_file *kf, const char *group, const char *key, int32_t value);
703
713 extern econf_err econf_setInt64Value(econf_file *kf, const char *group, const char *key, int64_t value);
714
724 extern econf_err econf_setUIntValue(econf_file *kf, const char *group, const char *key, uint32_t value);
725
735 extern econf_err econf_setUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t value);
736
746 extern econf_err econf_setFloatValue(econf_file *kf, const char *group, const char *key, float value);
747
757 extern econf_err econf_setDoubleValue(econf_file *kf, const char *group, const char *key, double value);
758
768 extern econf_err econf_setStringValue(econf_file *kf, const char *group, const char *key, const char *value);
769
779 extern econf_err econf_setBoolValue(econf_file *kf, const char *group, const char *key, const char *value);
780
781 /* --------------- */
782 /* --- HELPERS --- */
783 /* --------------- */
784
791 extern const char *econf_errString (const econf_err error);
792
799 extern void econf_errLocation (char **filename, uint64_t *line_nr);
800
807 extern void econf_freeArray(char **array);
808
815 extern void econf_freeFile(econf_file *key_file);
816
826 extern void __attribute__ ((deprecated("use one of econf_read*WithCallback instead")))
827 econf_requireOwner(uid_t owner);
828
838 extern void __attribute__ ((deprecated("use one of econf_read*WithCallback instead")))
839 econf_requireGroup(gid_t group);
840
851 extern void __attribute__ ((deprecated("use one of econf_read*WithCallback instead")))
852 econf_requirePermissions(mode_t file_perms, mode_t dir_perms);
853
863 extern void __attribute__ ((deprecated("use one of econf_read*WithCallback instead")))
864 econf_followSymlinks(bool allow);
865
874 extern void __attribute__ ((deprecated("use one of econf_read*WithCallback instead")))
875 econf_reset_security_settings(void);
876
893 extern econf_err econf_set_conf_dirs(const char **dir_postfix_list);
894
895 #ifdef __cplusplus
896 }
897 #endif
ECONF_EMPTY_SECTION_NAME
Empty section name.
Definition: libeconf.h:65
ECONF_PARSE_ERROR
General syntax error in input file.
Definition: libeconf.h:59
ECONF_MISSING_DELIMITER
Missing delimiter.
Definition: libeconf.h:63
ECONF_ERROR_FILE_IS_SYM_LINK
File is a sym link which is not permitted.
Definition: libeconf.h:83
econf_file
struct econf_file econf_file
Definition: libeconf.h:123
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_setFloatValue
econf_err econf_setFloatValue(econf_file *kf, const char *group, const char *key, float value)
Set float value for given group/key.
econf_delimiter_tag
char econf_delimiter_tag(econf_file *key_file)
Returns the delimiter character of the given econf_file object.
econf_readDirs
econf_err econf_readDirs(econf_file **key_file, const char *usr_conf_dir, const char *etc_conf_dir, const char *project_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_TEXT_AFTER_SECTION
Text after section.
Definition: libeconf.h:67
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_NOFILE
Config file not found.
Definition: libeconf.h:49
econf_comment_tag
char econf_comment_tag(econf_file *key_file)
Returns the comment character tag of the given econf_file object.
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_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_errLocation
void econf_errLocation(char **filename, uint64_t *line_nr)
Info about where the error has happened.
econf_getPath
char * econf_getPath(econf_file *kf)
Evaluating path name.
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_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_freeArray
void econf_freeArray(char **array)
Free an array of type char** created by econf_getGroups() or econf_getKeys().
ECONF_WRONG_OWNER
File has wrong owner.
Definition: libeconf.h:75
econf_freeFile
void econf_freeFile(econf_file *key_file)
Free memory allocated by e.g.
ECONF_NOGROUP
Group not found.
Definition: libeconf.h:51
dir_perms
void mode_t dir_perms
Definition: libeconf.h:852
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_WRONG_GROUP
File has wrong group.
Definition: libeconf.h:77
econf_getGroups
econf_err econf_getGroups(econf_file *kf, size_t *length, char ***groups)
Evaluating all group entries.
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_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_WRONG_DIR_PERMISSION
File has wrong dir permission.
Definition: libeconf.h:81
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 *project_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_KEY_HAS_NULL_VALUE
Given key has NULL value.
Definition: libeconf.h:73
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_EMPTYKEY
Key is NULL or has empty value.
Definition: libeconf.h:55
econf_getKeys
econf_err econf_getKeys(econf_file *kf, const char *group, size_t *length, char ***keys)
Evaluating all keys.
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_WRONG_FILE_PERMISSION
File has wrong file permissions.
Definition: libeconf.h:79
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.
__attribute__
void __attribute__((deprecated("use one of econf_read*WithCallback instead"))) econf_requireOwner(uid_t owner)
All parsed files require this user permission.
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_writeFile
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_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_FILE_LIST_IS_NULL
Parsed file list is NULL.
Definition: libeconf.h:69
ECONF_SUCCESS
General purpose success code.
Definition: libeconf.h:43
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_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_NOMEM
Out of memory.
Definition: libeconf.h:47
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_newKeyFile
econf_err econf_newKeyFile(econf_file **result, char delimiter, char comment)
Create a new econf_file object.
econf_readDirsWithCallback
econf_err econf_readDirsWithCallback(econf_file **key_file, const char *usr_conf_dir, const char *etc_conf_dir, const char *project_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_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_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_PARSING_CALLBACK_FAILED
User defined parsing callback has failed.
Definition: libeconf.h:85
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_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_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_WRONG_BOOLEAN_VALUE
Wrong boolean value (1/0 true/false yes/no)
Definition: libeconf.h:71
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_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_newIniFile
econf_err econf_newIniFile(econf_file **result)
Create a new econf_file object in IniFile format.
econf_set_conf_dirs
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_MISSING_BRACKET
Missing closing section bracket.
Definition: libeconf.h:61
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 *project_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_errString
const char * econf_errString(const econf_err error)
Convert an econf_err type to a string.
econf_err
econf_err
libeconf error codes
Definition: libeconf.h:41
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_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_NOKEY
Key not found.
Definition: libeconf.h:53
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_ERROR
Generic Error.
Definition: libeconf.h:45
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_WRITEERROR
Error creating or writing to a file.
Definition: libeconf.h:57