Tor 0.4.9.1-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-2021, 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
34#endif
35
36#include <stddef.h>
37
38/** Enumeration of types which option values can take */
39typedef 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. */
93struct var_type_def_t;
94
95/** Structure to specify a named, typed member within a structure. */
96typedef 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 **/
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 */
138typedef 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. */
226typedef 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
238
239/**
240 * An abbreviation or alias for a configuration option.
241 **/
242typedef 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 */
256typedef 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 configuration 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. */
281typedef 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. */
288typedef 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. */
299typedef 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. */
309typedef 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 */
326typedef int (*legacy_validate_fn_t)(const void *oldval,
327 void *newval,
328 char **msg_out);
329
330struct 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 */
342typedef 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. */
347typedef 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) */
Macro and type declarations for testing.
config_type_t
Definition: conftypes.h:39
@ CONFIG_TYPE_AUTOBOOL
Definition: conftypes.h:51
@ CONFIG_TYPE_ISOTIME
Definition: conftypes.h:53
@ CONFIG_TYPE_CSV_INTERVAL
Definition: conftypes.h:56
@ CONFIG_TYPE_LINELIST_V
Definition: conftypes.h:64
@ CONFIG_TYPE_CSV
Definition: conftypes.h:54
@ CONFIG_TYPE_LINELIST_S
Definition: conftypes.h:62
@ CONFIG_TYPE_DOUBLE
Definition: conftypes.h:49
@ CONFIG_TYPE_IGNORE
Definition: conftypes.h:77
@ CONFIG_TYPE_INTERVAL
Definition: conftypes.h:45
@ CONFIG_TYPE_MSEC_INTERVAL
Definition: conftypes.h:46
@ CONFIG_TYPE_INT
Definition: conftypes.h:43
@ CONFIG_TYPE_FILENAME
Definition: conftypes.h:41
@ CONFIG_TYPE_MEMUNIT
Definition: conftypes.h:48
@ CONFIG_TYPE_STRING
Definition: conftypes.h:40
@ CONFIG_TYPE_EXTENDED
Definition: conftypes.h:89
@ CONFIG_TYPE_OBSOLETE
Definition: conftypes.h:71
@ CONFIG_TYPE_UINT64
Definition: conftypes.h:44
@ CONFIG_TYPE_BOOL
Definition: conftypes.h:50
@ CONFIG_TYPE_POSINT
Definition: conftypes.h:42
@ CONFIG_TYPE_LINELIST
Definition: conftypes.h:61
int(* pre_normalize_fn_t)(void *value, char **msg_out)
Definition: conftypes.h:299
int(* validate_fn_t)(const void *value, char **msg_out)
Definition: conftypes.h:281
int(* post_normalize_fn_t)(void *value, char **msg_out)
Definition: conftypes.h:309
int(* check_transition_fn_t)(const void *old_value, const void *value, char **msg_out)
Definition: conftypes.h:288
int(* legacy_validate_fn_t)(const void *oldval, void *newval, char **msg_out)
Definition: conftypes.h:326
void(* clear_cfg_fn_t)(const struct config_mgr_t *mgr, void *obj)
Definition: conftypes.h:342
const char * abbreviated
Definition: conftypes.h:244
const char * full
Definition: conftypes.h:246
int commandline_only
Definition: conftypes.h:248
const char * why_deprecated
Definition: conftypes.h:260
const char * name
Definition: conftypes.h:258
post_normalize_fn_t post_normalize_fn
Definition: conftypes.h:366
const struct_member_t * extra
Definition: conftypes.h:371
const config_var_t * vars
Definition: conftypes.h:353
ptrdiff_t config_suite_offset
Definition: conftypes.h:380
const config_abbrev_t * abbrevs
Definition: conftypes.h:350
check_transition_fn_t check_transition_fn
Definition: conftypes.h:364
bool has_config_suite
Definition: conftypes.h:376
struct_magic_decl_t magic
Definition: conftypes.h:349
clear_cfg_fn_t clear_fn
Definition: conftypes.h:368
legacy_validate_fn_t legacy_validate_fn
Definition: conftypes.h:362
validate_fn_t validate_fn
Definition: conftypes.h:360
pre_normalize_fn_t pre_normalize_fn
Definition: conftypes.h:358
const char * initvalue
Definition: conftypes.h:229
uint32_t flags
Definition: conftypes.h:230
ptrdiff_t magic_offset
Definition: conftypes.h:145
uint32_t magic_val
Definition: conftypes.h:142
ptrdiff_t offset
Definition: conftypes.h:125
const struct var_type_def_t * type_def
Definition: conftypes.h:120
const char * name
Definition: conftypes.h:98
config_type_t type
Definition: conftypes.h:114
Integer definitions used throughout Tor.