libeconf.h

Go to the documentation of this file.

/*
  Copyright (C) 2019 SUSE LLC
  Author: Pascal Arlt <parlt@suse.com>

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in all
  copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
*/

#pragma once

#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <sys/types.h>

#ifdef __cplusplus
extern "C" {
#endif

enum econf_err {
  ECONF_SUCCESS = 0,
  ECONF_ERROR = 1,
  ECONF_NOMEM = 2,
  ECONF_NOFILE = 3,
  ECONF_NOGROUP = 4,
  ECONF_NOKEY = 5,
  ECONF_EMPTYKEY = 6,
  ECONF_WRITEERROR = 7,
  ECONF_PARSE_ERROR = 8,
  ECONF_MISSING_BRACKET = 9,
  ECONF_MISSING_DELIMITER = 10,
  ECONF_EMPTY_SECTION_NAME = 11,
  ECONF_TEXT_AFTER_SECTION = 12,
  ECONF_FILE_LIST_IS_NULL = 13,
  ECONF_WRONG_BOOLEAN_VALUE = 14,
  ECONF_KEY_HAS_NULL_VALUE = 15,
  ECONF_WRONG_OWNER = 16,
  ECONF_WRONG_GROUP = 17,
  ECONF_WRONG_FILE_PERMISSION = 18,
  ECONF_WRONG_DIR_PERMISSION = 19,
  ECONF_ERROR_FILE_IS_SYM_LINK = 20,
  ECONF_PARSING_CALLBACK_FAILED = 21,
  ECONF_ARGUMENT_IS_NULL_VALUE = 22,
  ECONF_OPTION_NOT_FOUND = 23,
  ECONF_VALUE_CONVERSION_ERROR = 24
};

typedef enum econf_err econf_err;

#define econf_setValue(kf, group, key, value) (( \
  _Generic((value), \
    int: econf_setIntValue, \
    long: econf_setInt64Value, \
    unsigned int: econf_setUIntValue, \
    unsigned long: econf_setUInt64Value, \
    float: econf_setFloatValue, \
    double: econf_setDoubleValue, \
    char*: econf_setStringValue, void*: econf_setStringValue)) \
(kf, group, key, value))

#define econf_free(value) (( \
  _Generic((value), \
    econf_file*: econf_freeFile , \
    char**: econf_freeArray)) \
(value))

typedef struct econf_file econf_file;

extern econf_err econf_readFile(econf_file **result, const char *file_name,
                                const char *delim, const char *comment);


extern 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);

extern econf_err econf_mergeFiles(econf_file **merged_file,
                                  econf_file *usr_file, econf_file *etc_file);


extern 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);

extern 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);


extern econf_err __attribute__ ((deprecated("Use the econf_readConfig/econf_readConfigWithCallback instead")))
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);

extern econf_err __attribute__ ((deprecated("Use the econf_readConfig/econf_readConfigWithCallback instead")))
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);

extern 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);

extern 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);

extern econf_err econf_newKeyFile(econf_file **result, char delimiter, char comment);

extern econf_err econf_newKeyFile_with_options(econf_file **result, const char *options);

extern econf_err econf_newIniFile(econf_file **result);

extern char econf_comment_tag(econf_file *key_file);

extern char econf_delimiter_tag(econf_file *key_file);

extern void econf_set_comment_tag(econf_file *key_file, const char comment);

extern void econf_set_delimiter_tag(econf_file *key_file, const char delimiter);

extern econf_err econf_writeFile(econf_file *key_file, const char *save_to_dir,
                                      const char *file_name);

/* --------------- */
/* --- GETTERS --- */
/* --------------- */

extern char *econf_getPath(econf_file *kf);

extern econf_err econf_getGroups(econf_file *kf, size_t *length, char ***groups);

extern econf_err econf_getKeys(econf_file *kf, const char *group, size_t *length, char ***keys);

extern econf_err econf_getIntValue(econf_file *kf, const char *group, const char *key, int32_t *result);

extern econf_err econf_getInt64Value(econf_file *kf, const char *group, const char *key, int64_t *result);

extern econf_err econf_getUIntValue(econf_file *kf, const char *group, const char *key, uint32_t *result);

extern econf_err econf_getUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t *result);

extern econf_err econf_getFloatValue(econf_file *kf, const char *group, const char *key, float *result);

extern econf_err econf_getDoubleValue(econf_file *kf, const char *group, const char *key, double *result);

extern econf_err econf_getStringValue(econf_file *kf, const char *group, const char *key, char **result);

extern econf_err econf_getBoolValue(econf_file *kf, const char *group, const char *key, bool *result);

extern econf_err econf_getIntValueDef(econf_file *kf, const char *group, const char *key, int32_t *result, const int32_t def);

extern econf_err econf_getInt64ValueDef(econf_file *kf, const char *group, const char *key, int64_t *result, const int64_t def);

extern econf_err econf_getUIntValueDef(econf_file *kf, const char *group, const char *key, uint32_t *result, const uint32_t def);

extern econf_err econf_getUInt64ValueDef(econf_file *kf, const char *group, const char *key, uint64_t *result, const uint64_t def);

extern econf_err econf_getFloatValueDef(econf_file *kf, const char *group, const char *key, float *result, const float def);

extern econf_err econf_getDoubleValueDef(econf_file *kf, const char *group, const char *key, double *result, const double def);

extern econf_err econf_getStringValueDef(econf_file *kf, const char *group, const char *key, char **result, const char *def);

extern econf_err econf_getBoolValueDef(econf_file *kf, const char *group, const char *key, bool *result, const bool def);

/* --------------- */
/* --- SETTERS --- */
/* --------------- */

extern econf_err econf_setIntValue(econf_file *kf, const char *group, const char *key, int32_t value);

extern econf_err econf_setInt64Value(econf_file *kf, const char *group, const char *key, int64_t value);

extern econf_err econf_setUIntValue(econf_file *kf, const char *group, const char *key, uint32_t value);

extern econf_err econf_setUInt64Value(econf_file *kf, const char *group, const char *key, uint64_t value);

extern econf_err econf_setFloatValue(econf_file *kf, const char *group, const char *key, float value);

extern econf_err econf_setDoubleValue(econf_file *kf, const char *group, const char *key, double value);

extern econf_err econf_setStringValue(econf_file *kf, const char *group, const char *key, const char *value);

extern econf_err econf_setBoolValue(econf_file *kf, const char *group, const char *key, const char *value);

/* --------------- */
/* --- HELPERS --- */
/* --------------- */

extern const char *econf_errString (const econf_err error);

extern void econf_errLocation (char **filename, uint64_t *line_nr);

extern char **econf_freeArray(char **array);

/* helper so that __attribute__((cleanup(econf_freeArrayp)) may be used */
static __inline__ void econf_freeArrayp(char ***array) {
  if (*array)
    *array = econf_freeArray(*array);
}

extern econf_file *econf_freeFile(econf_file *key_file);

/* helper so that __attribute__((cleanup(econf_freeFilep)) may be used */
static __inline__ void econf_freeFilep(econf_file **key_file) {
  if (*key_file)
    *key_file = econf_freeFile(*key_file);
}

extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
econf_requireOwner(uid_t owner);

extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
econf_requireGroup(gid_t group);

extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
econf_requirePermissions(mode_t file_perms, mode_t dir_perms);

extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
econf_followSymlinks(bool allow);

extern void __attribute__ ((deprecated("use callback in econf_readFileWithCallback or econf_readConfigWithCallback instead")))
econf_reset_security_settings(void);

extern econf_err __attribute__ ((deprecated("Is not thread-safe. Use econf_newKeyFile_with_options instead")))
econf_set_conf_dirs(const char **dir_postfix_list);

#ifdef __cplusplus
}
#endif