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 {
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 
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 
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
Empty section name.
Definition: libeconf.h:65
General syntax error in input file.
Definition: libeconf.h:59
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:123
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_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.
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...
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_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.
char * econf_getPath(econf_file *kf)
Evaluating path name.
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_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
void mode_t dir_perms
Definition: libeconf.h:852
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
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 /...
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.
void __attribute__((deprecated("use one of econf_read*WithCallback instead"))) econf_requireOwner(uid_t owner)
All parsed files require this user permission.
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_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_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.
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_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
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 /...
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
econf_err econf_getDoubleValue(econf_file *kf, const char *group, const char *key, double *result)
Evaluating double value for given group/key.
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