confparse.h 9.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207
  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-2017, The Tor Project, Inc. */
  5. /* See LICENSE for licensing information */
  6. #ifndef TOR_CONFPARSE_H
  7. #define TOR_CONFPARSE_H
  8. /** Enumeration of types which option values can take */
  9. typedef enum config_type_t {
  10. CONFIG_TYPE_STRING = 0, /**< An arbitrary string. */
  11. CONFIG_TYPE_FILENAME, /**< A filename: some prefixes get expanded. */
  12. CONFIG_TYPE_UINT, /**< A non-negative integer less than MAX_INT */
  13. CONFIG_TYPE_INT, /**< Any integer. */
  14. CONFIG_TYPE_PORT, /**< A port from 1...65535, 0 for "not set", or
  15. * "auto". */
  16. CONFIG_TYPE_INTERVAL, /**< A number of seconds, with optional units*/
  17. CONFIG_TYPE_MSEC_INTERVAL,/**< A number of milliseconds, with optional
  18. * units */
  19. CONFIG_TYPE_MEMUNIT, /**< A number of bytes, with optional units*/
  20. CONFIG_TYPE_DOUBLE, /**< A floating-point value */
  21. CONFIG_TYPE_BOOL, /**< A boolean value, expressed as 0 or 1. */
  22. CONFIG_TYPE_AUTOBOOL, /**< A boolean+auto value, expressed 0 for false,
  23. * 1 for true, and -1 for auto */
  24. CONFIG_TYPE_ISOTIME, /**< An ISO-formatted time relative to UTC. */
  25. CONFIG_TYPE_CSV, /**< A list of strings, separated by commas and
  26. * optional whitespace. */
  27. CONFIG_TYPE_CSV_INTERVAL, /**< A list of strings, separated by commas and
  28. * optional whitespace, representing intervals in
  29. * seconds, with optional units */
  30. CONFIG_TYPE_LINELIST, /**< Uninterpreted config lines */
  31. CONFIG_TYPE_LINELIST_S, /**< Uninterpreted, context-sensitive config lines,
  32. * mixed with other keywords. */
  33. CONFIG_TYPE_LINELIST_V, /**< Catch-all "virtual" option to summarize
  34. * context-sensitive config lines when fetching.
  35. */
  36. CONFIG_TYPE_ROUTERSET, /**< A list of router names, addrs, and fps,
  37. * parsed into a routerset_t. */
  38. CONFIG_TYPE_OBSOLETE, /**< Obsolete (ignored) option. */
  39. } config_type_t;
  40. #ifdef TOR_UNIT_TESTS
  41. /**
  42. * Union used when building in test mode typechecking the members of a type
  43. * used with confparse.c. See CONF_CHECK_VAR_TYPE for a description of how
  44. * it is used. */
  45. typedef union {
  46. char **STRING;
  47. char **FILENAME;
  48. int *UINT; /* yes, really: Even though the confparse type is called
  49. * "UINT", it still uses the C int type -- it just enforces that
  50. * the values are in range [0,INT_MAX].
  51. */
  52. int *INT;
  53. int *PORT;
  54. int *INTERVAL;
  55. int *MSEC_INTERVAL;
  56. uint64_t *MEMUNIT;
  57. double *DOUBLE;
  58. int *BOOL;
  59. int *AUTOBOOL;
  60. time_t *ISOTIME;
  61. smartlist_t **CSV;
  62. smartlist_t **CSV_INTERVAL;
  63. config_line_t **LINELIST;
  64. config_line_t **LINELIST_S;
  65. config_line_t **LINELIST_V;
  66. routerset_t **ROUTERSET;
  67. } confparse_dummy_values_t;
  68. #endif
  69. /** An abbreviation for a configuration option allowed on the command line. */
  70. typedef struct config_abbrev_t {
  71. const char *abbreviated;
  72. const char *full;
  73. int commandline_only;
  74. int warn;
  75. } config_abbrev_t;
  76. typedef struct config_deprecation_t {
  77. const char *name;
  78. const char *why_deprecated;
  79. } config_deprecation_t;
  80. /* Handy macro for declaring "In the config file or on the command line,
  81. * you can abbreviate <b>tok</b>s as <b>tok</b>". */
  82. #define PLURAL(tok) { #tok, #tok "s", 0, 0 }
  83. /** A variable allowed in the configuration file or on the command line. */
  84. typedef struct config_var_t {
  85. const char *name; /**< The full keyword (case insensitive). */
  86. config_type_t type; /**< How to interpret the type and turn it into a
  87. * value. */
  88. off_t var_offset; /**< Offset of the corresponding member of or_options_t. */
  89. const char *initvalue; /**< String (or null) describing initial value. */
  90. #ifdef TOR_UNIT_TESTS
  91. /** Used for compiler-magic to typecheck the corresponding field in the
  92. * corresponding struct. Only used in unit test mode, at compile-time. */
  93. confparse_dummy_values_t var_ptr_dummy;
  94. #endif
  95. } config_var_t;
  96. /* Macros to define extra members inside config_var_t fields, and at the
  97. * end of a list of them.
  98. */
  99. #ifdef TOR_UNIT_TESTS
  100. /* This is a somewhat magic type-checking macro for users of confparse.c.
  101. * It initializes a union member "confparse_dummy_values_t.conftype" with
  102. * the address of a static member "tp_dummy.member". This
  103. * will give a compiler warning unless the member field is of the correct
  104. * type.
  105. *
  106. * (This warning is mandatory, because a type mismatch here violates the type
  107. * compatibility constraint for simple assignment, and requires a diagnostic,
  108. * according to the C spec.)
  109. *
  110. * For example, suppose you say:
  111. * "CONF_CHECK_VAR_TYPE(or_options_t, STRING, Address)".
  112. * Then this macro will evaluate to:
  113. * { .STRING = &or_options_t_dummy.Address }
  114. * And since confparse_dummy_values_t.STRING has type "char **", that
  115. * expression will create a warning unless or_options_t.Address also
  116. * has type "char *".
  117. */
  118. #define CONF_CHECK_VAR_TYPE(tp, conftype, member) \
  119. { . conftype = &tp ## _dummy . member }
  120. #define CONF_TEST_MEMBERS(tp, conftype, member) \
  121. , CONF_CHECK_VAR_TYPE(tp, conftype, member)
  122. #define END_OF_CONFIG_VARS \
  123. { NULL, CONFIG_TYPE_OBSOLETE, 0, NULL, { .INT=NULL } }
  124. #define DUMMY_TYPECHECK_INSTANCE(tp) \
  125. static tp tp ## _dummy
  126. #else
  127. #define CONF_TEST_MEMBERS(tp, conftype, member)
  128. #define END_OF_CONFIG_VARS { NULL, CONFIG_TYPE_OBSOLETE, 0, NULL }
  129. /* Repeatedly declarable incomplete struct to absorb redundant semicolons */
  130. #define DUMMY_TYPECHECK_INSTANCE(tp) \
  131. struct tor_semicolon_eater
  132. #endif
  133. /** Type of a callback to validate whether a given configuration is
  134. * well-formed and consistent. See options_trial_assign() for documentation
  135. * of arguments. */
  136. typedef int (*validate_fn_t)(void*,void*,void*,int,char**);
  137. /** Information on the keys, value types, key-to-struct-member mappings,
  138. * variable descriptions, validation functions, and abbreviations for a
  139. * configuration or storage format. */
  140. typedef struct config_format_t {
  141. size_t size; /**< Size of the struct that everything gets parsed into. */
  142. uint32_t magic; /**< Required 'magic value' to make sure we have a struct
  143. * of the right type. */
  144. off_t magic_offset; /**< Offset of the magic value within the struct. */
  145. config_abbrev_t *abbrevs; /**< List of abbreviations that we expand when
  146. * parsing this format. */
  147. const config_deprecation_t *deprecations; /** List of deprecated options */
  148. config_var_t *vars; /**< List of variables we recognize, their default
  149. * values, and where we stick them in the structure. */
  150. validate_fn_t validate_fn; /**< Function to validate config. */
  151. /** If present, extra is a LINELIST variable for unrecognized
  152. * lines. Otherwise, unrecognized lines are an error. */
  153. config_var_t *extra;
  154. } config_format_t;
  155. /** Macro: assert that <b>cfg</b> has the right magic field for format
  156. * <b>fmt</b>. */
  157. #define CONFIG_CHECK(fmt, cfg) STMT_BEGIN \
  158. tor_assert(fmt && cfg); \
  159. tor_assert((fmt)->magic == \
  160. *(uint32_t*)STRUCT_VAR_P(cfg,fmt->magic_offset)); \
  161. STMT_END
  162. #define CAL_USE_DEFAULTS (1u<<0)
  163. #define CAL_CLEAR_FIRST (1u<<1)
  164. #define CAL_WARN_DEPRECATIONS (1u<<2)
  165. void *config_new(const config_format_t *fmt);
  166. void config_free(const config_format_t *fmt, void *options);
  167. config_line_t *config_get_assigned_option(const config_format_t *fmt,
  168. const void *options, const char *key,
  169. int escape_val);
  170. int config_is_same(const config_format_t *fmt,
  171. const void *o1, const void *o2,
  172. const char *name);
  173. void config_init(const config_format_t *fmt, void *options);
  174. void *config_dup(const config_format_t *fmt, const void *old);
  175. char *config_dump(const config_format_t *fmt, const void *default_options,
  176. const void *options, int minimal,
  177. int comment_defaults);
  178. int config_assign(const config_format_t *fmt, void *options,
  179. config_line_t *list,
  180. unsigned flags, char **msg);
  181. config_var_t *config_find_option_mutable(config_format_t *fmt,
  182. const char *key);
  183. const char *config_find_deprecation(const config_format_t *fmt,
  184. const char *key);
  185. const config_var_t *config_find_option(const config_format_t *fmt,
  186. const char *key);
  187. const char *config_expand_abbrev(const config_format_t *fmt,
  188. const char *option,
  189. int command_line, int warn_obsolete);
  190. void warn_deprecated_option(const char *what, const char *why);
  191. #endif /* !defined(TOR_CONFPARSE_H) */