Tor 0.4.9.0-alpha-dev
confdecl.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 confdecl.h
9 * @brief Macros for generating a configuration struct from a list
10 * of its individual fields.
11 *
12 * This header defines three important macros: BEGIN_CONF_STRUCT(),
13 * END_CONF_STRUCT(), and CONF_VAR(). They're meant to be used together to
14 * define a configuration structure and the means for encoding and decoding
15 * it.
16 *
17 * To use them, make a new header with a name like `MOD_options.inc`. Start
18 * it with a BEGIN_CONF_STRUCT(), then define your variables with CONF_VAR(),
19 * then end the header with END_CONF_STRUCT(), as in:
20 *
21 * BEGIN_CONF_STRUCT(module_options_t)
22 * CONF_VAR(ModuleIsActive, BOOLEAN, 0, "1")
23 * END_CONF_STRUCT(module_options_t)
24 *
25 * Once you've done that, you can use that header to define a configuration
26 * structure by saying:
27 *
28 * typedef struct module_options_t module_options_t;
29 * #define CONF_CONTEXT STRUCT
30 * #include "MOD_options.inc"
31 * #undef CONF_CONTEXT
32 *
33 * And you can define your field definition table by saying:
34 *
35 * #define CONF_CONTEXT TABLE
36 * #include "MOD_options.inc"
37 * #undef CONF_CONTEXT
38 *
39 * The two above snippets will define a structure called `module_options_t`
40 * with appropriate members, and a table of config_var_t objects called
41 * `module_options_t_vars[]`.
42 *
43 * For lower-level modules, you can say <tt>\#define CONF_TABLE LL_TABLE</tt>,
44 * and get a table definition suitable for use in modules that are at a lower
45 * level than lib/confmgt. Note that the types for these tables cannot
46 * include any extended types.
47 **/
48
49#ifndef TOR_LIB_CONF_CONFDECL_H
50#define TOR_LIB_CONF_CONFDECL_H
51
52#undef CONF_CONTEXT
53#include "lib/cc/tokpaste.h"
54#include "lib/cc/torint.h"
55
56/**
57 * Begin the definition of a configuration object called `name`.
58 **/
59#define BEGIN_CONF_STRUCT(name) \
60 PASTE(BEGIN_CONF_STRUCT__, CONF_CONTEXT)(name)
61/**
62 * End the definition of a configuration object called `name`.
63 **/
64#define END_CONF_STRUCT(name) \
65 PASTE(END_CONF_STRUCT__, CONF_CONTEXT)(name)
66/**
67 * Declare a single configuration field with name `varname`, type `vartype`,
68 * flags `varflags`, and initial value `initval`.
69 **/
70#define CONF_VAR(varname, vartype, varflags, initval) \
71 PASTE(CONF_VAR__, CONF_CONTEXT)(varname, vartype, varflags, initval)
72
73#ifndef COCCI
74/**
75 * @defgroup STRUCT_MACROS Internal macros: struct definitions.
76 * Implementation helpers: the regular confdecl macros expand to these
77 * when CONF_CONTEXT is defined to STRUCT. Don't use them directly.
78 * @{*/
79#define BEGIN_CONF_STRUCT__STRUCT(name) \
80 struct name { \
81 uint32_t magic;
82#define END_CONF_STRUCT__STRUCT(name) \
83 };
84#define CONF_VAR__STRUCT(varname, vartype, varflags, initval) \
85 config_decl_ ## vartype varname;
86/** @} */
87
88/**
89 * @defgroup TABLE_MACROS Internal macros: table definitions.
90 * Implementation helpers: the regular confdecl macros expand to these
91 * when CONF_CONTEXT is defined to TABLE. Don't use them directly.
92 * @{*/
93#define BEGIN_CONF_STRUCT__TABLE(structname) \
94 /* We use this typedef so we can refer to the config type */ \
95 /* without having its name as a macro argument to CONF_VAR. */ \
96 typedef struct structname config_var_reference__obj; \
97 static const config_var_t structname##_vars[] = {
98#define END_CONF_STRUCT__TABLE(structname) \
99 { .member = { .name = NULL } } \
100 };
101#define CONF_VAR__TABLE(varname, vartype, varflags, initval) \
102 { \
103 .member = \
104 { .name = #varname, \
105 .type = CONFIG_TYPE_EXTENDED, \
106 .type_def = &vartype ## _type_defn, \
107 .offset=offsetof(config_var_reference__obj, varname), \
108 }, \
109 .flags = varflags, \
110 .initvalue = initval \
111 },
112/**@}*/
113
114/**
115 * @defgroup LL_TABLE_MACROS Internal macros: low-level table definitions.
116 * Implementation helpers: the regular confdecl macros expand to these
117 * when CONF_CONTEXT is defined to LL_TABLE. Don't use them directly.
118 * @{*/
119#define BEGIN_CONF_STRUCT__LL_TABLE(structname) \
120 /* We use this typedef so we can refer to the config type */ \
121 /* without having its name as a macro argument to CONF_VAR. */ \
122 typedef struct structname config_var_reference__obj; \
123 static const config_var_t structname##_vars[] = {
124#define END_CONF_STRUCT__LL_TABLE(structname) \
125 { .member = { .name = NULL } } \
126 };
127#define CONF_VAR__LL_TABLE(varname, vartype, varflags, initval) \
128 { \
129 .member = \
130 { .name = #varname, \
131 .type = CONFIG_TYPE_ ## vartype, \
132 .offset=offsetof(config_var_reference__obj, varname), \
133 }, \
134 .flags = varflags, \
135 .initvalue = initval \
136 },
137/**@}*/
138
139/** @defgroup STUB_TABLE_MACROS Internal macros: stub table declarations,
140 * for use when a module is disabled.
141 * Implementation helpers: the regular confdecl macros expand to these
142 * when CONF_CONTEXT is defined to LL_TABLE. Don't use them directly.
143 * @{ */
144#define BEGIN_CONF_STRUCT__STUB_TABLE(structname) \
145 static const config_var_t structname##_vars[] = {
146#define END_CONF_STRUCT__STUB_TABLE(structname) \
147 { .member = { .name = NULL } } \
148 };
149#define CONF_VAR__STUB_TABLE(varname, vartype, varflags, initval) \
150 { \
151 .member = \
152 { .name = #varname, \
153 .type = CONFIG_TYPE_IGNORE, \
154 .offset = -1, \
155 }, \
156 .flags = CFLG_GROUP_DISABLED, \
157 },
158/**@}*/
159
160#endif /* !defined(COCCI) */
161
162/** Type aliases for the "commonly used" configuration types.
163 *
164 * Defining them in this way allows our CONF_VAR__STRUCT() macro to declare
165 * structure members corresponding to the configuration types. For example,
166 * when the macro sees us declare a configuration option "foo" of type STRING,
167 * it can emit `config_decl_STRING foo;`, which is an alias for `char *foo`.
168 */
169/**@{*/
170typedef char *config_decl_STRING;
171typedef char *config_decl_FILENAME;
172/* Yes, "POSINT" is really an int, and not an unsigned int. For
173 * historical reasons, many configuration values are restricted
174 * to the range [0,INT_MAX], and stored in signed ints.
175 */
176typedef int config_decl_POSINT;
177typedef uint64_t config_decl_UINT64;
178typedef int config_decl_INT;
179typedef int config_decl_INTERVAL;
180typedef int config_decl_MSEC_INTERVAL;
181typedef uint64_t config_decl_MEMUNIT;
182typedef double config_decl_DOUBLE;
183typedef int config_decl_BOOL;
184typedef int config_decl_AUTOBOOL;
185typedef time_t config_decl_ISOTIME;
186typedef struct smartlist_t config_decl_CSV;
187typedef int config_decl_CSV_INTERVAL;
188typedef struct config_line_t *config_decl_LINELIST;
189typedef struct config_line_t *config_decl_LINELIST_V;
190typedef struct nonexistent_struct *config_decl_LINELIST_S;
191/**@}*/
192
193struct var_type_def_t;
194
195/* Forward declarations for configuration type definitions. These are used by
196 * the CONF_VAR__TABLE macro to set the definition of each variable type
197 * correctly.
198 */
199/**@{*/
200extern const struct var_type_def_t STRING_type_defn;
201extern const struct var_type_def_t FILENAME_type_defn;
202extern const struct var_type_def_t POSINT_type_defn;
203extern const struct var_type_def_t UINT64_type_defn;
204extern const struct var_type_def_t INT_type_defn;
205extern const struct var_type_def_t INTERVAL_type_defn;
206extern const struct var_type_def_t MSEC_INTERVAL_type_defn;
207extern const struct var_type_def_t MEMUNIT_type_defn;
208extern const struct var_type_def_t DOUBLE_type_defn;
209extern const struct var_type_def_t BOOL_type_defn;
210extern const struct var_type_def_t AUTOBOOL_type_defn;
211extern const struct var_type_def_t ISOTIME_type_defn;
212extern const struct var_type_def_t CSV_type_defn;
213extern const struct var_type_def_t CSV_INTERVAL_type_defn;
214extern const struct var_type_def_t LINELIST_type_defn;
215extern const struct var_type_def_t LINELIST_V_type_defn;
216extern const struct var_type_def_t LINELIST_S_type_defn;
217extern const struct var_type_def_t IGNORE_type_defn;
218extern const struct var_type_def_t OBSOLETE_type_defn;
219/**@}*/
220
221#endif /* !defined(TOR_LIB_CONF_CONFDECL_H) */
char * config_decl_STRING
Definition: confdecl.h:170
Token-pasting macros.
Integer definitions used throughout Tor.