confparse.h 8.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212
  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-2019, The Tor Project, Inc. */
  5. /* See LICENSE for licensing information */
  6. /**
  7. * \file confparse.h
  8. *
  9. * \brief Header for confparse.c.
  10. */
  11. #ifndef TOR_CONFPARSE_H
  12. #define TOR_CONFPARSE_H
  13. #include "lib/conf/conftypes.h"
  14. #include "lib/conf/confmacros.h"
  15. #include "lib/testsupport/testsupport.h"
  16. /**
  17. * An abbreviation or alias for a configuration option.
  18. **/
  19. typedef struct config_abbrev_t {
  20. /** The option name as abbreviated. Not case-sensitive. */
  21. const char *abbreviated;
  22. /** The full name of the option. Not case-sensitive. */
  23. const char *full;
  24. /** True if this abbreviation should only be allowed on the command line. */
  25. int commandline_only;
  26. /** True if we should warn whenever this abbreviation is used. */
  27. int warn;
  28. } config_abbrev_t;
  29. /**
  30. * A note that a configuration option is deprecated, with an explanation why.
  31. */
  32. typedef struct config_deprecation_t {
  33. /** The option that is deprecated. */
  34. const char *name;
  35. /** A user-facing string explaining why the option is deprecated. */
  36. const char *why_deprecated;
  37. } config_deprecation_t;
  38. /**
  39. * Handy macro for declaring "In the config file or on the command line, you
  40. * can abbreviate <b>tok</b>s as <b>tok</b>". Used inside an array of
  41. * config_abbrev_t.
  42. *
  43. * For example, to declare "NumCpu" as an abbreviation for "NumCPUs",
  44. * you can say PLURAL(NumCpu).
  45. **/
  46. #define PLURAL(tok) { #tok, #tok "s", 0, 0 }
  47. /**
  48. * Type of a callback to validate whether a given configuration is
  49. * well-formed and consistent.
  50. *
  51. * The configuration to validate is passed as <b>newval</b>. The previous
  52. * configuration, if any, is provided in <b>oldval</b>. The
  53. * <b>default_val</b> argument receives a configuration object initialized
  54. * with default values for all its fields. The <b>from_setconf</b> argument
  55. * is true iff the input comes from a SETCONF controller command.
  56. *
  57. * On success, return 0. On failure, set *<b>msg_out</b> to a newly allocated
  58. * error message, and return -1.
  59. *
  60. * REFACTORING NOTE: Currently, this callback type is only used from inside
  61. * config_dump(); later in our refactoring, it will be cleaned up and used
  62. * more generally.
  63. */
  64. typedef int (*validate_fn_t)(void *oldval,
  65. void *newval,
  66. void *default_val,
  67. int from_setconf,
  68. char **msg_out);
  69. struct config_mgr_t;
  70. /**
  71. * Callback to clear all non-managed fields of a configuration object.
  72. *
  73. * <b>obj</b> is the configuration object whose non-managed fields should be
  74. * cleared.
  75. *
  76. * (Regular fields get cleared by config_reset(), but you might have fields
  77. * in the object that do not correspond to configuration variables. If those
  78. * fields need to be cleared or freed, this is where to do it.)
  79. */
  80. typedef void (*clear_cfg_fn_t)(const struct config_mgr_t *mgr, void *obj);
  81. /** Information on the keys, value types, key-to-struct-member mappings,
  82. * variable descriptions, validation functions, and abbreviations for a
  83. * configuration or storage format. */
  84. typedef struct config_format_t {
  85. size_t size; /**< Size of the struct that everything gets parsed into. */
  86. struct_magic_decl_t magic; /**< Magic number info for this struct. */
  87. const config_abbrev_t *abbrevs; /**< List of abbreviations that we expand
  88. * when parsing this format. */
  89. const config_deprecation_t *deprecations; /** List of deprecated options */
  90. const config_var_t *vars; /**< List of variables we recognize, their default
  91. * values, and where we stick them in the
  92. * structure. */
  93. validate_fn_t validate_fn; /**< Function to validate config. */
  94. clear_cfg_fn_t clear_fn; /**< Function to clear the configuration. */
  95. /** If present, extra denotes a LINELIST variable for unrecognized
  96. * lines. Otherwise, unrecognized lines are an error. */
  97. const struct_member_t *extra;
  98. /** The position of a config_suite_t pointer within the toplevel object,
  99. * or -1 if there is no such pointer. */
  100. ptrdiff_t config_suite_offset;
  101. } config_format_t;
  102. /**
  103. * A collection of config_format_t objects to describe several objects
  104. * that are all configured with the same configuration file.
  105. *
  106. * (NOTE: for now, this only handles a single config_format_t.)
  107. **/
  108. typedef struct config_mgr_t config_mgr_t;
  109. config_mgr_t *config_mgr_new(const config_format_t *toplevel_fmt);
  110. void config_mgr_free_(config_mgr_t *mgr);
  111. int config_mgr_add_format(config_mgr_t *mgr,
  112. const config_format_t *fmt);
  113. void config_mgr_freeze(config_mgr_t *mgr);
  114. #define config_mgr_free(mgr) \
  115. FREE_AND_NULL(config_mgr_t, config_mgr_free_, (mgr))
  116. struct smartlist_t *config_mgr_list_vars(const config_mgr_t *mgr);
  117. struct smartlist_t *config_mgr_list_deprecated_vars(const config_mgr_t *mgr);
  118. /** A collection of managed configuration objects. */
  119. typedef struct config_suite_t config_suite_t;
  120. /**
  121. * Flag for config_assign: if set, then "resetting" an option changes it to
  122. * its default value, as specified in the config_var_t. Otherwise,
  123. * "resetting" an option changes it to a type-dependent null value --
  124. * typically 0 or NULL.
  125. *
  126. * (An option is "reset" when it is set to an empty value, or as described in
  127. * CAL_CLEAR_FIRST).
  128. **/
  129. #define CAL_USE_DEFAULTS (1u<<0)
  130. /**
  131. * Flag for config_assign: if set, then we reset every provided config
  132. * option before we set it.
  133. *
  134. * For example, if this flag is not set, then passing a multi-line option to
  135. * config_assign will cause any previous value to be extended. But if this
  136. * flag is set, then a multi-line option will replace any previous value.
  137. **/
  138. #define CAL_CLEAR_FIRST (1u<<1)
  139. /**
  140. * Flag for config_assign: if set, we warn about deprecated options.
  141. **/
  142. #define CAL_WARN_DEPRECATIONS (1u<<2)
  143. void *config_new(const config_mgr_t *fmt);
  144. void config_free_(const config_mgr_t *fmt, void *options);
  145. #define config_free(mgr, options) do { \
  146. config_free_((mgr), (options)); \
  147. (options) = NULL; \
  148. } while (0)
  149. struct config_line_t *config_get_assigned_option(const config_mgr_t *mgr,
  150. const void *options, const char *key,
  151. int escape_val);
  152. int config_is_same(const config_mgr_t *fmt,
  153. const void *o1, const void *o2,
  154. const char *name);
  155. struct config_line_t *config_get_changes(const config_mgr_t *mgr,
  156. const void *options1, const void *options2);
  157. void config_init(const config_mgr_t *mgr, void *options);
  158. void *config_dup(const config_mgr_t *mgr, const void *old);
  159. char *config_dump(const config_mgr_t *mgr, const void *default_options,
  160. const void *options, int minimal,
  161. int comment_defaults);
  162. bool config_check_ok(const config_mgr_t *mgr, const void *options,
  163. int severity);
  164. int config_assign(const config_mgr_t *mgr, void *options,
  165. struct config_line_t *list,
  166. unsigned flags, char **msg);
  167. const char *config_find_deprecation(const config_mgr_t *mgr,
  168. const char *key);
  169. const char *config_find_option_name(const config_mgr_t *mgr,
  170. const char *key);
  171. const char *config_expand_abbrev(const config_mgr_t *mgr,
  172. const char *option,
  173. int command_line, int warn_obsolete);
  174. void warn_deprecated_option(const char *what, const char *why);
  175. bool config_var_is_settable(const config_var_t *var);
  176. bool config_var_is_listable(const config_var_t *var);
  177. /* Helper macros to compare an option across two configuration objects */
  178. #define CFG_EQ_BOOL(a,b,opt) ((a)->opt == (b)->opt)
  179. #define CFG_EQ_INT(a,b,opt) ((a)->opt == (b)->opt)
  180. #define CFG_EQ_STRING(a,b,opt) (!strcmp_opt((a)->opt, (b)->opt))
  181. #define CFG_EQ_SMARTLIST(a,b,opt) smartlist_strings_eq((a)->opt, (b)->opt)
  182. #define CFG_EQ_LINELIST(a,b,opt) config_lines_eq((a)->opt, (b)->opt)
  183. #define CFG_EQ_ROUTERSET(a,b,opt) routerset_equal((a)->opt, (b)->opt)
  184. #ifdef CONFPARSE_PRIVATE
  185. STATIC void config_reset_line(const config_mgr_t *mgr, void *options,
  186. const char *key, int use_defaults);
  187. STATIC void *config_mgr_get_obj_mutable(const config_mgr_t *mgr,
  188. void *toplevel, int idx);
  189. STATIC const void *config_mgr_get_obj(const config_mgr_t *mgr,
  190. const void *toplevel, int idx);
  191. #endif /* defined(CONFPARSE_PRIVATE) */
  192. #endif /* !defined(TOR_CONFPARSE_H) */