src/lib/confmgt/confmgt.h

   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) */