confparse.h 6.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157
  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. /** An abbreviation for a configuration option allowed on the command line. */
  17. typedef struct config_abbrev_t {
  18. const char *abbreviated;
  19. const char *full;
  20. int commandline_only;
  21. int warn;
  22. } config_abbrev_t;
  23. typedef struct config_deprecation_t {
  24. const char *name;
  25. const char *why_deprecated;
  26. } config_deprecation_t;
  27. /* Handy macro for declaring "In the config file or on the command line,
  28. * you can abbreviate <b>tok</b>s as <b>tok</b>". */
  29. #define PLURAL(tok) { #tok, #tok "s", 0, 0 }
  30. /** Type of a callback to validate whether a given configuration is
  31. * well-formed and consistent. See options_trial_assign() for documentation
  32. * of arguments. */
  33. typedef int (*validate_fn_t)(void*,void*,void*,int,char**);
  34. struct config_mgr_t;
  35. /**
  36. * Callback to clear all non-managed fields of a configuration object.
  37. *
  38. * (Regular fields get cleared by config_reset(), but you might have fields
  39. * in the object that do not correspond to configuration variables. If those
  40. * fields need to be cleared or freed, this is where to do it.)
  41. */
  42. typedef void (*clear_cfg_fn_t)(const struct config_mgr_t *mgr, void*);
  43. /** Information on the keys, value types, key-to-struct-member mappings,
  44. * variable descriptions, validation functions, and abbreviations for a
  45. * configuration or storage format. */
  46. typedef struct config_format_t {
  47. size_t size; /**< Size of the struct that everything gets parsed into. */
  48. struct_magic_decl_t magic; /**< Magic number info for this struct. */
  49. const config_abbrev_t *abbrevs; /**< List of abbreviations that we expand
  50. * when parsing this format. */
  51. const config_deprecation_t *deprecations; /** List of deprecated options */
  52. const config_var_t *vars; /**< List of variables we recognize, their default
  53. * values, and where we stick them in the
  54. * structure. */
  55. validate_fn_t validate_fn; /**< Function to validate config. */
  56. clear_cfg_fn_t clear_fn; /**< Function to clear the configuration. */
  57. /** If present, extra denotes a LINELIST variable for unrecognized
  58. * lines. Otherwise, unrecognized lines are an error. */
  59. const struct_member_t *extra;
  60. /** The position of a config_suite_t pointer within the toplevel object,
  61. * or -1 if there is no such pointer. */
  62. int config_suite_offset;
  63. } config_format_t;
  64. /**
  65. * A collection of config_format_t objects to describe several objects
  66. * that are all configured with the same configuration file.
  67. *
  68. * (NOTE: for now, this only handles a single config_format_t.)
  69. **/
  70. typedef struct config_mgr_t config_mgr_t;
  71. config_mgr_t *config_mgr_new(const config_format_t *toplevel_fmt);
  72. void config_mgr_free_(config_mgr_t *mgr);
  73. int config_mgr_add_format(config_mgr_t *mgr,
  74. const config_format_t *fmt);
  75. void config_mgr_freeze(config_mgr_t *mgr);
  76. #define config_mgr_free(mgr) \
  77. FREE_AND_NULL(config_mgr_t, config_mgr_free_, (mgr))
  78. struct smartlist_t *config_mgr_list_vars(const config_mgr_t *mgr);
  79. struct smartlist_t *config_mgr_list_deprecated_vars(const config_mgr_t *mgr);
  80. /** A collection of managed configuration objects. */
  81. typedef struct config_suite_t config_suite_t;
  82. #define CAL_USE_DEFAULTS (1u<<0)
  83. #define CAL_CLEAR_FIRST (1u<<1)
  84. #define CAL_WARN_DEPRECATIONS (1u<<2)
  85. void *config_new(const config_mgr_t *fmt);
  86. void config_free_(const config_mgr_t *fmt, void *options);
  87. #define config_free(mgr, options) do { \
  88. config_free_((mgr), (options)); \
  89. (options) = NULL; \
  90. } while (0)
  91. struct config_line_t *config_get_assigned_option(const config_mgr_t *mgr,
  92. const void *options, const char *key,
  93. int escape_val);
  94. int config_is_same(const config_mgr_t *fmt,
  95. const void *o1, const void *o2,
  96. const char *name);
  97. struct config_line_t *config_get_changes(const config_mgr_t *mgr,
  98. const void *options1, const void *options2);
  99. void config_init(const config_mgr_t *mgr, void *options);
  100. void *config_dup(const config_mgr_t *mgr, const void *old);
  101. char *config_dump(const config_mgr_t *mgr, const void *default_options,
  102. const void *options, int minimal,
  103. int comment_defaults);
  104. bool config_check_ok(const config_mgr_t *mgr, const void *options,
  105. int severity);
  106. int config_assign(const config_mgr_t *mgr, void *options,
  107. struct config_line_t *list,
  108. unsigned flags, char **msg);
  109. const char *config_find_deprecation(const config_mgr_t *mgr,
  110. const char *key);
  111. const char *config_find_option_name(const config_mgr_t *mgr,
  112. const char *key);
  113. const char *config_expand_abbrev(const config_mgr_t *mgr,
  114. const char *option,
  115. int command_line, int warn_obsolete);
  116. void warn_deprecated_option(const char *what, const char *why);
  117. bool config_var_is_cumulative(const config_var_t *var);
  118. bool config_var_is_settable(const config_var_t *var);
  119. bool config_var_is_contained(const config_var_t *var);
  120. bool config_var_is_invisible(const config_var_t *var);
  121. bool config_var_is_dumpable(const config_var_t *var);
  122. /* Helper macros to compare an option across two configuration objects */
  123. #define CFG_EQ_BOOL(a,b,opt) ((a)->opt == (b)->opt)
  124. #define CFG_EQ_INT(a,b,opt) ((a)->opt == (b)->opt)
  125. #define CFG_EQ_STRING(a,b,opt) (!strcmp_opt((a)->opt, (b)->opt))
  126. #define CFG_EQ_SMARTLIST(a,b,opt) smartlist_strings_eq((a)->opt, (b)->opt)
  127. #define CFG_EQ_LINELIST(a,b,opt) config_lines_eq((a)->opt, (b)->opt)
  128. #define CFG_EQ_ROUTERSET(a,b,opt) routerset_equal((a)->opt, (b)->opt)
  129. #ifdef CONFPARSE_PRIVATE
  130. STATIC void config_reset_line(const config_mgr_t *mgr, void *options,
  131. const char *key, int use_defaults);
  132. STATIC void *config_mgr_get_obj_mutable(const config_mgr_t *mgr,
  133. void *toplevel, int idx);
  134. STATIC const void *config_mgr_get_obj(const config_mgr_t *mgr,
  135. const void *toplevel, int idx);
  136. #endif
  137. #endif /* !defined(TOR_CONFPARSE_H) */