Tor  0.4.5.0-alpha-dev
conftypes.h
Go to the documentation of this file.
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-2020, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
6 
7 /**
8  * @file conftypes.h
9  * @brief Types used to specify configurable options.
10  *
11  * This header defines the types that different modules will use in order to
12  * declare their configuration and state variables, and tell the configuration
13  * management code about those variables. From the individual module's point
14  * of view, its configuration and state are simply data structures.
15  *
16  * For defining new variable types, see var_type_def_st.h.
17  *
18  * For the code that manipulates variables defined via this module, see
19  * lib/confmgt/, especially typedvar.h and (later) structvar.h. The
20  * configuration manager is responsible for encoding, decoding, and
21  * maintaining the configuration structures used by the various modules.
22  *
23  * STATUS NOTE: This is a work in process refactoring. It is not yet possible
24  * for modules to define their own variables, and much of the configuration
25  * management code is still in src/app/config/.
26  **/
27 
28 #ifndef TOR_SRC_LIB_CONF_CONFTYPES_H
29 #define TOR_SRC_LIB_CONF_CONFTYPES_H
30 
31 #include "lib/cc/torint.h"
32 #ifdef TOR_UNIT_TESTS
33 #include "lib/conf/conftesting.h"
34 #endif
35 
36 #include <stddef.h>
37 
38 /** Enumeration of types which option values can take */
39 typedef enum config_type_t {
40  CONFIG_TYPE_STRING = 0, /**< An arbitrary string. */
41  CONFIG_TYPE_FILENAME, /**< A filename: some prefixes get expanded. */
42  CONFIG_TYPE_POSINT, /**< A non-negative integer less than MAX_INT */
43  CONFIG_TYPE_INT, /**< Any integer. */
44  CONFIG_TYPE_UINT64, /**< A value in range 0..UINT64_MAX */
45  CONFIG_TYPE_INTERVAL, /**< A number of seconds, with optional units*/
46  CONFIG_TYPE_MSEC_INTERVAL,/**< A number of milliseconds, with optional
47  * units */
48  CONFIG_TYPE_MEMUNIT, /**< A number of bytes, with optional units*/
49  CONFIG_TYPE_DOUBLE, /**< A floating-point value */
50  CONFIG_TYPE_BOOL, /**< A boolean value, expressed as 0 or 1. */
51  CONFIG_TYPE_AUTOBOOL, /**< A boolean+auto value, expressed 0 for false,
52  * 1 for true, and -1 for auto */
53  CONFIG_TYPE_ISOTIME, /**< An ISO-formatted time relative to UTC. */
54  CONFIG_TYPE_CSV, /**< A list of strings, separated by commas and
55  * optional whitespace. */
56  CONFIG_TYPE_CSV_INTERVAL, /**< A list of strings, separated by commas and
57  * optional whitespace, representing intervals in
58  * seconds, with optional units. We allow
59  * multiple values here for legacy reasons, but
60  * ignore every value after the first. */
61  CONFIG_TYPE_LINELIST, /**< Uninterpreted config lines */
62  CONFIG_TYPE_LINELIST_S, /**< Uninterpreted, context-sensitive config lines,
63  * mixed with other keywords. */
64  CONFIG_TYPE_LINELIST_V, /**< Catch-all "virtual" option to summarize
65  * context-sensitive config lines when fetching.
66  */
67  /** Ignored (obsolete) option. Uses no storage.
68  *
69  * Reported as "obsolete" when its type is queried.
70  */
72  /** Ignored option. Uses no storage.
73  *
74  * Reported as "ignored" when its type is queried. For use with options used
75  * by disabled modules.
76  **/
78 
79  /**
80  * Extended type: definition appears in the <b>type_def</b> pointer
81  * of the corresponding struct_member_t.
82  *
83  * For some types, we cannot define them as particular values of this
84  * enumeration, since those types are abstractions defined at a higher level
85  * than this module. (For example, parsing a routerset_t is higher-level
86  * than this module.) To handle this, we use CONFIG_TYPE_EXTENDED for those
87  * types, and give a definition for them in the struct_member_t.type_def.
88  **/
91 
92 /* Forward delcaration for var_type_def_t, for extended types. */
93 struct var_type_def_t;
94 
95 /** Structure to specify a named, typed member within a structure. */
96 typedef struct struct_member_t {
97  /** Name of the field. */
98  const char *name;
99  /**
100  * Type of the field, according to the config_type_t enumeration.
101  *
102  * For any type not otherwise listed in config_type_t, this field's value
103  * should be CONFIG_TYPE_EXTENDED. When it is, the <b>type_def</b> pointer
104  * must be set.
105  **/
106  /*
107  * NOTE: In future refactoring, we might remove this field entirely, along
108  * with its corresponding enumeration. In that case, we will require that
109  * type_def be set in all cases. If we do, we will also need a new mechanism
110  * to enforce consistency between configuration variable types and their
111  * corresponding structures, since our current design in
112  * lib/conf/conftesting.h won't work any more.
113  */
115  /**
116  * Pointer to a type definition for the type of this field. Overrides
117  * <b>type</b> if it is not NULL. Must be set when <b>type</b> is
118  * CONFIG_TYPE_EXTENDED.
119  **/
120  const struct var_type_def_t *type_def;
121  /**
122  * Offset of this field within the structure. Compute this with
123  * offsetof(structure, fieldname).
124  **/
125  ptrdiff_t offset;
127 
128 /**
129  * Structure to describe the location and preferred value of a "magic number"
130  * field within a structure.
131  *
132  * These 'magic numbers' are 32-bit values used to tag objects to make sure
133  * that they have the correct type.
134  *
135  * If all fields in this structure are zero or 0, the magic-number check is
136  * not performed.
137  */
138 typedef struct struct_magic_decl_t {
139  /** The name of the structure */
140  const char *typename;
141  /** A value used to recognize instances of this structure. */
142  uint32_t magic_val;
143  /** The location within the structure at which we expect to find
144  * <b>magic_val</b>. */
145  ptrdiff_t magic_offset;
147 
148 /**
149  * Flag to indicate that an option or type is "undumpable". An
150  * undumpable option is never saved to disk.
151  *
152  * For historical reasons its name is usually is prefixed with __.
153  **/
154 #define CFLG_NODUMP (1u<<0)
155 /**
156  * Flag to indicate that an option or type is "unlisted".
157  *
158  * We don't tell the controller about unlisted options when it asks for a
159  * list of them.
160  **/
161 #define CFLG_NOLIST (1u<<1)
162 /**
163  * Flag to indicate that an option or type is "unsettable".
164  *
165  * An unsettable option can never be set directly by name.
166  **/
167 #define CFLG_NOSET (1u<<2)
168 /**
169  * Flag to indicate that an option or type does not need to be copied when
170  * copying the structure that contains it.
171  *
172  * (Usually, if an option does not need to be copied, then either it contains
173  * no data, or the data that it does contain is completely contained within
174  * another option.)
175  **/
176 #define CFLG_NOCOPY (1u<<3)
177 /**
178  * Flag to indicate that an option or type does not need to be compared
179  * when telling the controller about the differences between two
180  * configurations.
181  *
182  * (Usually, if an option does not need to be compared, then either it
183  * contains no data, or the data that it does contain is completely contained
184  * within another option.)
185  **/
186 #define CFLG_NOCMP (1u<<4)
187 /**
188  * Flag to indicate that an option or type should not be replaced when setting
189  * it.
190  *
191  * For most options, setting them replaces their old value. For some options,
192  * however, setting them appends to their old value.
193  */
194 #define CFLG_NOREPLACE (1u<<5)
195 /**
196  * Flag to indicate that an option or type cannot be changed while Tor is
197  * running.
198  **/
199 #define CFLG_IMMUTABLE (1u<<6)
200 /**
201  * Flag to indicate that we should warn that an option or type is obsolete
202  * whenever the user tries to use it.
203  **/
204 #define CFLG_WARN_OBSOLETE (1u<<7)
205 /**
206  * Flag to indicate that we should warn that an option applies only to
207  * a disabled module, whenever the user tries to use it.
208  **/
209 #define CFLG_WARN_DISABLED (1u<<8)
210 
211 /**
212  * A group of flags that should be set on all obsolete options and types.
213  **/
214 #define CFLG_GROUP_OBSOLETE \
215  (CFLG_NOCOPY|CFLG_NOCMP|CFLG_NODUMP|CFLG_NOSET|CFLG_NOLIST|\
216  CFLG_WARN_OBSOLETE)
217 
218 /**
219  * A group of fflags that should be set on all disabled options.
220  **/
221 #define CFLG_GROUP_DISABLED \
222  (CFLG_NOCOPY|CFLG_NOCMP|CFLG_NODUMP|CFLG_NOSET|CFLG_NOLIST|\
223  CFLG_WARN_DISABLED)
224 
225 /** A variable allowed in the configuration file or on the command line. */
226 typedef struct config_var_t {
227  struct_member_t member; /** A struct member corresponding to this
228  * variable. */
229  const char *initvalue; /**< String (or null) describing initial value. */
230  uint32_t flags; /**< One or more flags describing special handling for this
231  * variable */
232 #ifdef TOR_UNIT_TESTS
233  /** Used for compiler-magic to typecheck the corresponding field in the
234  * corresponding struct. Only used in unit test mode, at compile-time. */
235  confparse_dummy_values_t var_ptr_dummy;
236 #endif
237 } config_var_t;
238 
239 /**
240  * An abbreviation or alias for a configuration option.
241  **/
242 typedef struct config_abbrev_t {
243  /** The option name as abbreviated. Not case-sensitive. */
244  const char *abbreviated;
245  /** The full name of the option. Not case-sensitive. */
246  const char *full;
247  /** True if this abbreviation should only be allowed on the command line. */
249  /** True if we should warn whenever this abbreviation is used. */
250  int warn;
252 
253 /**
254  * A note that a configuration option is deprecated, with an explanation why.
255  */
256 typedef struct config_deprecation_t {
257  /** The option that is deprecated. */
258  const char *name;
259  /** A user-facing string explaining why the option is deprecated. */
260  const char *why_deprecated;
262 
263 #ifndef COCCI
264 /**
265  * Handy macro for declaring "In the config file or on the command line, you
266  * can abbreviate <b>tok</b>s as <b>tok</b>". Used inside an array of
267  * config_abbrev_t.
268  *
269  * For example, to declare "NumCpu" as an abbreviation for "NumCPUs",
270  * you can say PLURAL(NumCpu).
271  **/
272 #define PLURAL(tok) { (#tok), (#tok "s"), 0, 0 }
273 #endif /* !defined(COCCI) */
274 
275 /**
276  * Validation function: verify whether a configuation object is well-formed
277  * and consistent.
278  *
279  * On success, return 0. On failure, set <b>msg_out</b> to a newly allocated
280  * string containing an error message, and return -1. */
281 typedef int (*validate_fn_t)(const void *value, char **msg_out);
282 /**
283  * Validation function: verify whether a configuration object (`value`) is an
284  * allowable value given the previous configuration value (`old_value`).
285  *
286  * On success, return 0. On failure, set <b>msg_out</b> to a newly allocated
287  * string containing an error message, and return -1. */
288 typedef int (*check_transition_fn_t)(const void *old_value, const void *value,
289  char **msg_out);
290 /**
291  * Validation function: normalize members of `value`, and compute derived
292  * members.
293  *
294  * This function is called before any other validation of `value`, and must
295  * not assume that validate_fn or check_transition_fn has passed.
296  *
297  * On success, return 0. On failure, set <b>msg_out</b> to a newly allocated
298  * string containing an error message, and return -1. */
299 typedef int (*pre_normalize_fn_t)(void *value, char **msg_out);
300 /**
301  * Validation function: normalize members of `value`, and compute derived
302  * members.
303  *
304  * This function is called after validation of `value`, and may
305  * assume that validate_fn or check_transition_fn has passed.
306  *
307  * On success, return 0. On failure, set <b>msg_out</b> to a newly allocated
308  * string containing an error message, and return -1. */
309 typedef int (*post_normalize_fn_t)(void *value, char **msg_out);
310 
311 /**
312  * Legacy function to validate whether a given configuration is
313  * well-formed and consistent.
314  *
315  * The configuration to validate is passed as <b>newval</b>. The previous
316  * configuration, if any, is provided in <b>oldval</b>.
317  *
318  * This API is deprecated, since it mixes the responsibilities of
319  * pre_normalize_fn_t, post_normalize_fn_t, validate_fn_t, and
320  * check_transition_fn_t. No new instances of this function type should
321  * be written.
322  *
323  * On success, return 0. On failure, set *<b>msg_out</b> to a newly allocated
324  * error message, and return -1.
325  */
326 typedef int (*legacy_validate_fn_t)(const void *oldval,
327  void *newval,
328  char **msg_out);
329 
330 struct config_mgr_t;
331 
332 /**
333  * Callback to clear all non-managed fields of a configuration object.
334  *
335  * <b>obj</b> is the configuration object whose non-managed fields should be
336  * cleared.
337  *
338  * (Regular fields get cleared by config_reset(), but you might have fields
339  * in the object that do not correspond to configuration variables. If those
340  * fields need to be cleared or freed, this is where to do it.)
341  */
342 typedef void (*clear_cfg_fn_t)(const struct config_mgr_t *mgr, void *obj);
343 
344 /** Information on the keys, value types, key-to-struct-member mappings,
345  * variable descriptions, validation functions, and abbreviations for a
346  * configuration or storage format. */
347 typedef struct config_format_t {
348  size_t size; /**< Size of the struct that everything gets parsed into. */
349  struct_magic_decl_t magic; /**< Magic number info for this struct. */
350  const config_abbrev_t *abbrevs; /**< List of abbreviations that we expand
351  * when parsing this format. */
352  const config_deprecation_t *deprecations; /** List of deprecated options */
353  const config_var_t *vars; /**< List of variables we recognize, their default
354  * values, and where we stick them in the
355  * structure. */
356 
357  /** Early-stage normalization callback. Invoked by config_validate(). */
359  /** Configuration validation function. Invoked by config_validate(). */
361  /** Legacy validation function. Invoked by config_validate(). */
363  /** Transition checking function. Invoked by config_validate(). */
365  /** Late-stage normalization callback. Invoked by config_validate(). */
367 
368  clear_cfg_fn_t clear_fn; /**< Function to clear the configuration. */
369  /** If present, extra denotes a LINELIST variable for unrecognized
370  * lines. Otherwise, unrecognized lines are an error. */
372  /**
373  * If true, this format describes a top-level configuration, with
374  * a suite containing multiple sub-configuration objects.
375  */
377  /** The position of a config_suite_t pointer within the toplevel object.
378  * Ignored unless have_config_suite is true.
379  */
382 
383 #endif /* !defined(TOR_SRC_LIB_CONF_CONFTYPES_H) */
config_format_t::extra
const struct_member_t * extra
Definition: conftypes.h:371
config_var_t::flags
uint32_t flags
Definition: conftypes.h:230
config_format_t::pre_normalize_fn
pre_normalize_fn_t pre_normalize_fn
Definition: conftypes.h:358
CONFIG_TYPE_EXTENDED
@ CONFIG_TYPE_EXTENDED
Definition: conftypes.h:89
CONFIG_TYPE_OBSOLETE
@ CONFIG_TYPE_OBSOLETE
Definition: conftypes.h:71
config_mgr_t
Definition: confmgt.c:107
config_var_t::initvalue
const char * initvalue
Definition: conftypes.h:229
CONFIG_TYPE_CSV_INTERVAL
@ CONFIG_TYPE_CSV_INTERVAL
Definition: conftypes.h:56
config_abbrev_t::commandline_only
int commandline_only
Definition: conftypes.h:248
torint.h
Integer definitions used throughout Tor.
config_abbrev_t::warn
int warn
Definition: conftypes.h:250
config_format_t::clear_fn
clear_cfg_fn_t clear_fn
Definition: conftypes.h:368
check_transition_fn_t
int(* check_transition_fn_t)(const void *old_value, const void *value, char **msg_out)
Definition: conftypes.h:288
config_abbrev_t
Definition: conftypes.h:242
config_var_t
Definition: conftypes.h:226
CONFIG_TYPE_UINT64
@ CONFIG_TYPE_UINT64
Definition: conftypes.h:44
config_abbrev_t::abbreviated
const char * abbreviated
Definition: conftypes.h:244
struct_member_t::type_def
const struct var_type_def_t * type_def
Definition: conftypes.h:120
var_type_def_t
Definition: var_type_def_st.h:146
CONFIG_TYPE_STRING
@ CONFIG_TYPE_STRING
Definition: conftypes.h:40
config_format_t::config_suite_offset
ptrdiff_t config_suite_offset
Definition: conftypes.h:380
config_format_t
Definition: conftypes.h:347
config_format_t::vars
const config_var_t * vars
Definition: conftypes.h:353
config_format_t::has_config_suite
bool has_config_suite
Definition: conftypes.h:376
CONFIG_TYPE_DOUBLE
@ CONFIG_TYPE_DOUBLE
Definition: conftypes.h:49
struct_magic_decl_t::magic_val
uint32_t magic_val
Definition: conftypes.h:142
struct_member_t::name
const char * name
Definition: conftypes.h:98
config_format_t::check_transition_fn
check_transition_fn_t check_transition_fn
Definition: conftypes.h:364
config_format_t::size
size_t size
Definition: conftypes.h:348
config_type_t
config_type_t
Definition: conftypes.h:39
config_format_t::post_normalize_fn
post_normalize_fn_t post_normalize_fn
Definition: conftypes.h:366
CONFIG_TYPE_FILENAME
@ CONFIG_TYPE_FILENAME
Definition: conftypes.h:41
CONFIG_TYPE_MSEC_INTERVAL
@ CONFIG_TYPE_MSEC_INTERVAL
Definition: conftypes.h:46
struct_member_t::type
config_type_t type
Definition: conftypes.h:114
CONFIG_TYPE_LINELIST
@ CONFIG_TYPE_LINELIST
Definition: conftypes.h:61
config_format_t::magic
struct_magic_decl_t magic
Definition: conftypes.h:349
CONFIG_TYPE_POSINT
@ CONFIG_TYPE_POSINT
Definition: conftypes.h:42
config_format_t::validate_fn
validate_fn_t validate_fn
Definition: conftypes.h:360
config_format_t::abbrevs
const config_abbrev_t * abbrevs
Definition: conftypes.h:350
struct_member_t
Definition: conftypes.h:96
struct_magic_decl_t::magic_offset
ptrdiff_t magic_offset
Definition: conftypes.h:145
CONFIG_TYPE_AUTOBOOL
@ CONFIG_TYPE_AUTOBOOL
Definition: conftypes.h:51
CONFIG_TYPE_INT
@ CONFIG_TYPE_INT
Definition: conftypes.h:43
CONFIG_TYPE_LINELIST_V
@ CONFIG_TYPE_LINELIST_V
Definition: conftypes.h:64
config_deprecation_t::name
const char * name
Definition: conftypes.h:258
validate_fn_t
int(* validate_fn_t)(const void *value, char **msg_out)
Definition: conftypes.h:281
struct_member_t::offset
ptrdiff_t offset
Definition: conftypes.h:125
legacy_validate_fn_t
int(* legacy_validate_fn_t)(const void *oldval, void *newval, char **msg_out)
Definition: conftypes.h:326
CONFIG_TYPE_ISOTIME
@ CONFIG_TYPE_ISOTIME
Definition: conftypes.h:53
config_deprecation_t::why_deprecated
const char * why_deprecated
Definition: conftypes.h:260
CONFIG_TYPE_CSV
@ CONFIG_TYPE_CSV
Definition: conftypes.h:54
CONFIG_TYPE_BOOL
@ CONFIG_TYPE_BOOL
Definition: conftypes.h:50
config_deprecation_t
Definition: conftypes.h:256
config_abbrev_t::full
const char * full
Definition: conftypes.h:246
post_normalize_fn_t
int(* post_normalize_fn_t)(void *value, char **msg_out)
Definition: conftypes.h:309
CONFIG_TYPE_INTERVAL
@ CONFIG_TYPE_INTERVAL
Definition: conftypes.h:45
pre_normalize_fn_t
int(* pre_normalize_fn_t)(void *value, char **msg_out)
Definition: conftypes.h:299
conftesting.h
Macro and type declarations for testing.
struct_magic_decl_t
Definition: conftypes.h:138
CONFIG_TYPE_MEMUNIT
@ CONFIG_TYPE_MEMUNIT
Definition: conftypes.h:48
config_format_t::legacy_validate_fn
legacy_validate_fn_t legacy_validate_fn
Definition: conftypes.h:362
clear_cfg_fn_t
void(* clear_cfg_fn_t)(const struct config_mgr_t *mgr, void *obj)
Definition: conftypes.h:342
CONFIG_TYPE_IGNORE
@ CONFIG_TYPE_IGNORE
Definition: conftypes.h:77
CONFIG_TYPE_LINELIST_S
@ CONFIG_TYPE_LINELIST_S
Definition: conftypes.h:62