1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
/* Copyright (c) 2001 Matej Pfajfar.
* Copyright (c) 2001-2004, Roger Dingledine.
* Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
* Copyright (c) 2007-2019, The Tor Project, Inc. */
/* See LICENSE for licensing information */
/**
* @file conftypes.h
* @brief Types used to specify configurable options.
*
* This header defines the types that different modules will use in order to
* declare their configuration and state variables, and tell the configuration
* management code about those variables. From the individual module's point
* of view, its configuration and state are simply data structures.
*
* For defining new variable types, see var_type_def_st.h.
*
* For the code that manipulates variables defined via this module, see
* lib/confmgt/, especially typedvar.h and (later) structvar.h. The
* configuration manager is responsible for encoding, decoding, and
* maintaining the configuration structures used by the various modules.
*
* STATUS NOTE: This is a work in process refactoring. It is not yet possible
* for modules to define their own variables, and much of the configuration
* management code is still in src/app/config/.
**/
#ifndef TOR_SRC_LIB_CONF_CONFTYPES_H
#define TOR_SRC_LIB_CONF_CONFTYPES_H
#include "lib/cc/torint.h"
#ifdef TOR_UNIT_TESTS
#include "lib/conf/conftesting.h"
#endif
#include <stddef.h>
/** Enumeration of types which option values can take */
typedef enum config_type_t {
CONFIG_TYPE_STRING = 0, /**< An arbitrary string. */
CONFIG_TYPE_FILENAME, /**< A filename: some prefixes get expanded. */
CONFIG_TYPE_POSINT, /**< A non-negative integer less than MAX_INT */
CONFIG_TYPE_INT, /**< Any integer. */
CONFIG_TYPE_UINT64, /**< A value in range 0..UINT64_MAX */
CONFIG_TYPE_INTERVAL, /**< A number of seconds, with optional units*/
CONFIG_TYPE_MSEC_INTERVAL,/**< A number of milliseconds, with optional
* units */
CONFIG_TYPE_MEMUNIT, /**< A number of bytes, with optional units*/
CONFIG_TYPE_DOUBLE, /**< A floating-point value */
CONFIG_TYPE_BOOL, /**< A boolean value, expressed as 0 or 1. */
CONFIG_TYPE_AUTOBOOL, /**< A boolean+auto value, expressed 0 for false,
* 1 for true, and -1 for auto */
CONFIG_TYPE_ISOTIME, /**< An ISO-formatted time relative to UTC. */
CONFIG_TYPE_CSV, /**< A list of strings, separated by commas and
* optional whitespace. */
CONFIG_TYPE_CSV_INTERVAL, /**< A list of strings, separated by commas and
* optional whitespace, representing intervals in
* seconds, with optional units. We allow
* multiple values here for legacy reasons, but
* ignore every value after the first. */
CONFIG_TYPE_LINELIST, /**< Uninterpreted config lines */
CONFIG_TYPE_LINELIST_S, /**< Uninterpreted, context-sensitive config lines,
* mixed with other keywords. */
CONFIG_TYPE_LINELIST_V, /**< Catch-all "virtual" option to summarize
* context-sensitive config lines when fetching.
*/
CONFIG_TYPE_OBSOLETE, /**< Obsolete (ignored) option. */
/**
* Extended type: definition appears in the <b>type_def</b> pointer
* of the corresponding struct_member_t.
*
* For some types, we cannot define them as particular values of this
* enumeration, since those types are abstractions defined at a higher level
* than this module. (For example, parsing a routerset_t is higher-level
* than this module.) To handle this, we use CONFIG_TYPE_EXTENDED for those
* types, and give a definition for them in the struct_member_t.type_def.
**/
CONFIG_TYPE_EXTENDED,
} config_type_t;
/* Forward delcaration for var_type_def_t, for extended types. */
struct var_type_def_t;
/** Structure to specify a named, typed member within a structure. */
typedef struct struct_member_t {
/** Name of the field. */
const char *name;
/**
* Type of the field, according to the config_type_t enumeration.
*
* For any type not otherwise listed in config_type_t, this field's value
* should be CONFIG_TYPE_EXTENDED. When it is, the <b>type_def</b> pointer
* must be set.
**/
/*
* NOTE: In future refactoring, we might remove this field entirely, along
* with its corresponding enumeration. In that case, we will require that
* type_def be set in all cases. If we do, we will also need a new mechanism
* to enforce consistency between configuration variable types and their
* corresponding structures, since our current design in
* lib/conf/conftesting.h won't work any more.
*/
config_type_t type;
/**
* Pointer to a type definition for the type of this field. Overrides
* <b>type</b> if it is not NULL. Must be set when <b>type</b> is
* CONFIG_TYPE_EXTENDED.
**/
const struct var_type_def_t *type_def;
/**
* Offset of this field within the structure. Compute this with
* offsetof(structure, fieldname).
**/
ptrdiff_t offset;
} struct_member_t;
/**
* Structure to describe the location and preferred value of a "magic number"
* field within a structure.
*
* These 'magic numbers' are 32-bit values used to tag objects to make sure
* that they have the correct type.
*/
typedef struct struct_magic_decl_t {
/** The name of the structure */
const char *typename;
/** A value used to recognize instances of this structure. */
uint32_t magic_val;
/** The location within the structure at which we expect to find
* <b>magic_val</b>. */
ptrdiff_t magic_offset;
} struct_magic_decl_t;
/**
* Flag to indicate that an option or type is "undumpable". An
* undumpable option is never saved to disk.
*
* For historical reasons its name is usually is prefixed with __.
**/
#define CFLG_NODUMP (1u<<0)
/**
* Flag to indicate that an option or type is "unlisted".
*
* We don't tell the controller about unlisted options when it asks for a
* list of them.
**/
#define CFLG_NOLIST (1u<<1)
/**
* Flag to indicate that an option or type is "unsettable".
*
* An unsettable option can never be set directly by name.
**/
#define CFLG_NOSET (1u<<2)
/**
* Flag to indicate that an option or type does not need to be copied when
* copying the structure that contains it.
*
* (Usually, if an option does not need to be copied, then either it contains
* no data, or the data that it does contain is completely contained within
* another option.)
**/
#define CFLG_NOCOPY (1u<<3)
/**
* Flag to indicate that an option or type does not need to be compared
* when telling the controller about the differences between two
* configurations.
*
* (Usually, if an option does not need to be compared, then either it
* contains no data, or the data that it does contain is completely contained
* within another option.)
**/
#define CFLG_NOCMP (1u<<4)
/**
* Flag to indicate that an option or type should not be replaced when setting
* it.
*
* For most options, setting them replaces their old value. For some options,
* however, setting them appends to their old value.
*/
#define CFLG_NOREPLACE (1u<<5)
/**
* A group of flags that should be set on all obsolete options and types.
**/
#define CFLG_GROUP_OBSOLETE \
(CFLG_NOCOPY|CFLG_NOCMP|CFLG_NODUMP|CFLG_NOSET|CFLG_NOLIST)
/** A variable allowed in the configuration file or on the command line. */
typedef struct config_var_t {
struct_member_t member; /** A struct member corresponding to this
* variable. */
const char *initvalue; /**< String (or null) describing initial value. */
uint32_t flags; /**< One or more flags describing special handling for this
* variable */
#ifdef TOR_UNIT_TESTS
/** Used for compiler-magic to typecheck the corresponding field in the
* corresponding struct. Only used in unit test mode, at compile-time. */
confparse_dummy_values_t var_ptr_dummy;
#endif
} config_var_t;
#endif /* !defined(TOR_SRC_LIB_CONF_CONFTYPES_H) */
|
