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 /**@{*/ 170 typedef char *config_decl_STRING; 171 typedef 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 */ 176 typedef int config_decl_POSINT; 177 typedef uint64_t config_decl_UINT64; 178 typedef int config_decl_INT; 179 typedef int config_decl_INTERVAL; 180 typedef int config_decl_MSEC_INTERVAL; 181 typedef uint64_t config_decl_MEMUNIT; 182 typedef double config_decl_DOUBLE; 183 typedef int config_decl_BOOL; 184 typedef int config_decl_AUTOBOOL; 185 typedef time_t config_decl_ISOTIME; 186 typedef struct smartlist_t config_decl_CSV; 187 typedef int config_decl_CSV_INTERVAL; 188 typedef struct config_line_t *config_decl_LINELIST; 189 typedef struct config_line_t *config_decl_LINELIST_V; 190 typedef struct nonexistent_struct *config_decl_LINELIST_S; 191 /**@}*/ 192 193 struct 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 /**@{*/ 200 extern const struct var_type_def_t STRING_type_defn; 201 extern const struct var_type_def_t FILENAME_type_defn; 202 extern const struct var_type_def_t POSINT_type_defn; 203 extern const struct var_type_def_t UINT64_type_defn; 204 extern const struct var_type_def_t INT_type_defn; 205 extern const struct var_type_def_t INTERVAL_type_defn; 206 extern const struct var_type_def_t MSEC_INTERVAL_type_defn; 207 extern const struct var_type_def_t MEMUNIT_type_defn; 208 extern const struct var_type_def_t DOUBLE_type_defn; 209 extern const struct var_type_def_t BOOL_type_defn; 210 extern const struct var_type_def_t AUTOBOOL_type_defn; 211 extern const struct var_type_def_t ISOTIME_type_defn; 212 extern const struct var_type_def_t CSV_type_defn; 213 extern const struct var_type_def_t CSV_INTERVAL_type_defn; 214 extern const struct var_type_def_t LINELIST_type_defn; 215 extern const struct var_type_def_t LINELIST_V_type_defn; 216 extern const struct var_type_def_t LINELIST_S_type_defn; 217 extern const struct var_type_def_t IGNORE_type_defn; 218 extern const struct var_type_def_t OBSOLETE_type_defn; 219 /**@}*/ 220 221 #endif /* !defined(TOR_LIB_CONF_CONFDECL_H) */ 222