libeconf  0.4.9
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 
194 extern econf_err econf_readFileWithCallback(econf_file **result, const char *file_name,
195  const char *delim, const char *comment,
196  bool (*callback)(const char *filename));
197 
226 extern econf_err econf_mergeFiles(econf_file **merged_file,
227  econf_file *usr_file, econf_file *etc_file);
228 
262  const char *usr_conf_dir,
263  const char *etc_conf_dir,
264  const char *project_name,
265  const char *config_suffix,
266  const char *delim,
267  const char *comment);
268 
314  const char *usr_conf_dir,
315  const char *etc_conf_dir,
316  const char *project_name,
317  const char *config_suffix,
318  const char *delim,
319  const char *comment,
320  bool (*callback)(const char *filename));
321 
341  size_t *size,
342  const char *usr_conf_dir,
343  const char *etc_conf_dir,
344  const char *project_name,
345  const char *config_suffix,
346  const char *delim,
347  const char *comment);
348 
372  size_t *size,
373  const char *usr_conf_dir,
374  const char *etc_conf_dir,
375  const char *project_name,
376  const char *config_suffix,
377  const char *delim,
378  const char *comment,
379  bool (*callback)(const char *filename));
380 
381 /* The API/ABI of the following three functions (econf_newKeyFile,
382  econf_newIniFile and econf_writeFile) are not stable and will change */
383 
397 extern econf_err econf_newKeyFile(econf_file **result, char delimiter, char comment);
398 
407 
415 extern char econf_comment_tag(econf_file *key_file);
416 
424 extern char econf_delimiter_tag(econf_file *key_file);
425 
433 extern void econf_set_comment_tag(econf_file *key_file, const char comment);
434 
442 extern void econf_set_delimiter_tag(econf_file *key_file, const char delimiter);
443 
452 extern econf_err econf_writeFile(econf_file *key_file, const char *save_to_dir,
453  const char *file_name);
454 
455 /* --------------- */
456 /* --- GETTERS --- */
457 /* --------------- */
458 
466 extern char *econf_getPath(econf_file *kf);
467 
476 extern econf_err econf_getGroups(econf_file *kf, size_t *length, char ***groups);
477 
488 extern econf_err econf_getKeys(econf_file *kf, const char *group, size_t *length, char ***keys);
489 
499 extern econf_err econf_getIntValue(econf_file *kf, const char *group, const char *key, int32_t *result);
500 
510 extern econf_err econf_getInt64Value(econf_file *kf, const char *group, const char *key, int64_t *result);
511 
521 extern econf_err econf_getUIntValue(econf_file *kf, const char *group, const char *key, uint32_t *result);
522 
532 extern econf_err econf_getUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t *result);
533 
543 extern econf_err econf_getFloatValue(econf_file *kf, const char *group, const char *key, float *result);
544 
554 extern econf_err econf_getDoubleValue(econf_file *kf, const char *group, const char *key, double *result);
555 
565 extern econf_err econf_getStringValue(econf_file *kf, const char *group, const char *key, char **result);
566 
576 extern econf_err econf_getBoolValue(econf_file *kf, const char *group, const char *key, bool *result);
577 
589 extern econf_err econf_getIntValueDef(econf_file *kf, const char *group, const char *key, int32_t *result, int32_t def);
590 
602 extern econf_err econf_getInt64ValueDef(econf_file *kf, const char *group, const char *key, int64_t *result, int64_t def);
603 
615 extern econf_err econf_getUIntValueDef(econf_file *kf, const char *group, const char *key, uint32_t *result, uint32_t def);
616 
628 extern econf_err econf_getUInt64ValueDef(econf_file *kf, const char *group, const char *key, uint64_t *result, uint64_t def);
629 
641 extern econf_err econf_getFloatValueDef(econf_file *kf, const char *group, const char *key, float *result, float def);
642 
654 extern econf_err econf_getDoubleValueDef(econf_file *kf, const char *group, const char *key, double *result, double def);
655 
667 extern econf_err econf_getStringValueDef(econf_file *kf, const char *group, const char *key, char **result, char *def);
668 
680 extern econf_err econf_getBoolValueDef(econf_file *kf, const char *group, const char *key, bool *result, bool def);
681 
682 /* --------------- */
683 /* --- SETTERS --- */
684 /* --------------- */
685 
695 extern econf_err econf_setIntValue(econf_file *kf, const char *group, const char *key, int32_t value);
696 
706 extern econf_err econf_setInt64Value(econf_file *kf, const char *group, const char *key, int64_t value);
707 
717 extern econf_err econf_setUIntValue(econf_file *kf, const char *group, const char *key, uint32_t value);
718 
728 extern econf_err econf_setUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t value);
729 
739 extern econf_err econf_setFloatValue(econf_file *kf, const char *group, const char *key, float value);
740 
750 extern econf_err econf_setDoubleValue(econf_file *kf, const char *group, const char *key, double value);
751 
761 extern econf_err econf_setStringValue(econf_file *kf, const char *group, const char *key, const char *value);
762 
772 extern econf_err econf_setBoolValue(econf_file *kf, const char *group, const char *key, const char *value);
773 
774 /* --------------- */
775 /* --- HELPERS --- */
776 /* --------------- */
777 
784 extern const char *econf_errString (const econf_err error);
785 
792 extern void econf_errLocation (char **filename, uint64_t *line_nr);
793 
800 extern void econf_freeArray(char **array);
801 
808 extern void econf_freeFile(econf_file *key_file);
809 
816 extern void econf_requireOwner(uid_t owner);
817 
824 extern void econf_requireGroup(gid_t group);
825 
833 extern void econf_requirePermissions(mode_t file_perms, mode_t dir_perms);
834 
841 extern void econf_followSymlinks(bool allow);
842 
849 
850 #ifdef __cplusplus
851 }
852 #endif
econf_err econf_newIniFile(econf_file **result)
Create a new econf_file object in IniFile format.
struct econf_file econf_file
Definition: libeconf.h:123
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))
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_getBoolValueDef(econf_file *kf, const char *group, const char *key, bool *result, bool def)
Evaluating bool value for given group/key.
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_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_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_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_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_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.
char * econf_getPath(econf_file *kf)
Evaluating path name.
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_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_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_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.
const char * econf_errString(const econf_err error)
Convert an econf_err type to a string.
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,...
econf_err econf_readFileWithCallback(econf_file **result, const char *file_name, const char *delim, const char *comment, bool(*callback)(const char *filename))
Process the file of the given file_name and save its contents into key_file object.
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_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_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))
Evaluating key/values for every given configuration files in two different directories (normally in /...
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.
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.