confmgt.h (5567B)
1 /* Copyright (c) 2001 Matej Pfajfar. 2 * Copyright (c) 2001-2004, Roger Dingledine. 3 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson. 4 * Copyright (c) 2007-2021, The Tor Project, Inc. */ 5 /* See LICENSE for licensing information */ 6 7 /** 8 * \file confmgt.h 9 * 10 * \brief Header for confmgt.c. 11 */ 12 13 #ifndef TOR_CONFMGT_H 14 #define TOR_CONFMGT_H 15 16 #include "lib/conf/conftypes.h" 17 #include "lib/conf/confmacros.h" 18 #include "lib/testsupport/testsupport.h" 19 20 /** 21 * A collection of config_format_t objects to describe several objects 22 * that are all configured with the same configuration file. 23 * 24 * (NOTE: for now, this only handles a single config_format_t.) 25 **/ 26 typedef struct config_mgr_t config_mgr_t; 27 28 config_mgr_t *config_mgr_new(const config_format_t *toplevel_fmt); 29 void config_mgr_free_(config_mgr_t *mgr); 30 int config_mgr_add_format(config_mgr_t *mgr, 31 const config_format_t *fmt); 32 void config_mgr_freeze(config_mgr_t *mgr); 33 #define config_mgr_free(mgr) \ 34 FREE_AND_NULL(config_mgr_t, config_mgr_free_, (mgr)) 35 struct smartlist_t *config_mgr_list_vars(const config_mgr_t *mgr); 36 struct smartlist_t *config_mgr_list_deprecated_vars(const config_mgr_t *mgr); 37 38 /** A collection of managed configuration objects. */ 39 typedef struct config_suite_t config_suite_t; 40 41 /** 42 * Flag for config_assign: if set, then "resetting" an option changes it to 43 * its default value, as specified in the config_var_t. Otherwise, 44 * "resetting" an option changes it to a type-dependent null value -- 45 * typically 0 or NULL. 46 * 47 * (An option is "reset" when it is set to an empty value, or as described in 48 * CAL_CLEAR_FIRST). 49 **/ 50 #define CAL_USE_DEFAULTS (1u<<0) 51 /** 52 * Flag for config_assign: if set, then we reset every provided config 53 * option before we set it. 54 * 55 * For example, if this flag is not set, then passing a multi-line option to 56 * config_assign will cause any previous value to be extended. But if this 57 * flag is set, then a multi-line option will replace any previous value. 58 **/ 59 #define CAL_CLEAR_FIRST (1u<<1) 60 /** 61 * Flag for config_assign: if set, we warn about deprecated options. 62 **/ 63 #define CAL_WARN_DEPRECATIONS (1u<<2) 64 65 void *config_new(const config_mgr_t *fmt); 66 void config_free_(const config_mgr_t *fmt, void *options); 67 #define config_free(mgr, options) do { \ 68 config_free_((mgr), (options)); \ 69 (options) = NULL; \ 70 } while (0) 71 72 struct config_line_t *config_get_assigned_option(const config_mgr_t *mgr, 73 const void *options, const char *key, 74 int escape_val); 75 int config_is_same(const config_mgr_t *fmt, 76 const void *o1, const void *o2, 77 const char *name); 78 struct config_line_t *config_get_changes(const config_mgr_t *mgr, 79 const void *options1, const void *options2); 80 void config_init(const config_mgr_t *mgr, void *options); 81 82 /** An enumeration to report which validation step failed. */ 83 typedef enum { 84 VSTAT_PRE_NORMALIZE_ERR = -5, 85 VSTAT_VALIDATE_ERR = -4, 86 VSTAT_LEGACY_ERR = -3, 87 VSTAT_TRANSITION_ERR = -2, 88 VSTAT_POST_NORMALIZE_ERR = -1, 89 VSTAT_OK = 0, 90 } validation_status_t; 91 92 validation_status_t config_validate(const config_mgr_t *mgr, 93 const void *old_options, void *options, 94 char **msg_out); 95 void *config_dup(const config_mgr_t *mgr, const void *old); 96 char *config_dump(const config_mgr_t *mgr, const void *default_options, 97 const void *options, int minimal, 98 int comment_defaults); 99 void config_check_toplevel_magic(const config_mgr_t *mgr, 100 const void *object); 101 bool config_check_ok(const config_mgr_t *mgr, const void *options, 102 int severity); 103 int config_assign(const config_mgr_t *mgr, void *options, 104 struct config_line_t *list, 105 unsigned flags, char **msg); 106 const char *config_find_deprecation(const config_mgr_t *mgr, 107 const char *key); 108 const char *config_find_option_name(const config_mgr_t *mgr, 109 const char *key); 110 const char *config_expand_abbrev(const config_mgr_t *mgr, 111 const char *option, 112 int command_line, int warn_obsolete); 113 void warn_deprecated_option(const char *what, const char *why); 114 115 bool config_var_is_settable(const config_var_t *var); 116 bool config_var_is_listable(const config_var_t *var); 117 118 /* Helper macros to compare an option across two configuration objects */ 119 #define CFG_EQ_BOOL(a,b,opt) ((a)->opt == (b)->opt) 120 #define CFG_EQ_INT(a,b,opt) ((a)->opt == (b)->opt) 121 #define CFG_EQ_STRING(a,b,opt) (!strcmp_opt((a)->opt, (b)->opt)) 122 #define CFG_EQ_SMARTLIST(a,b,opt) smartlist_strings_eq((a)->opt, (b)->opt) 123 #define CFG_EQ_LINELIST(a,b,opt) config_lines_eq((a)->opt, (b)->opt) 124 #define CFG_EQ_ROUTERSET(a,b,opt) routerset_equal((a)->opt, (b)->opt) 125 126 void *config_mgr_get_obj_mutable(const config_mgr_t *mgr, 127 void *toplevel, int idx); 128 const void *config_mgr_get_obj(const config_mgr_t *mgr, 129 const void *toplevel, int idx); 130 131 #ifdef CONFMGT_PRIVATE 132 STATIC void config_reset_line(const config_mgr_t *mgr, void *options, 133 const char *key, int use_defaults); 134 #endif /* defined(CONFMGT_PRIVATE) */ 135 136 #endif /* !defined(TOR_CONFMGT_H) */