Tor 0.4.9.0-alpha-dev
|
Types used to specify configurable options. More...
Go to the source code of this file.
Data Structures | |
struct | struct_member_t |
struct | struct_magic_decl_t |
struct | config_var_t |
struct | config_abbrev_t |
struct | config_deprecation_t |
struct | config_format_t |
Macros | |
#define | CFLG_NODUMP (1u<<0) |
#define | CFLG_NOLIST (1u<<1) |
#define | CFLG_NOSET (1u<<2) |
#define | CFLG_NOCOPY (1u<<3) |
#define | CFLG_NOCMP (1u<<4) |
#define | CFLG_NOREPLACE (1u<<5) |
#define | CFLG_IMMUTABLE (1u<<6) |
#define | CFLG_WARN_OBSOLETE (1u<<7) |
#define | CFLG_WARN_DISABLED (1u<<8) |
#define | CFLG_GROUP_OBSOLETE |
#define | CFLG_GROUP_DISABLED |
#define | PLURAL(tok) { (#tok), (#tok "s"), 0, 0 } |
Typedefs | |
typedef int(* | validate_fn_t) (const void *value, char **msg_out) |
typedef int(* | check_transition_fn_t) (const void *old_value, const void *value, char **msg_out) |
typedef int(* | pre_normalize_fn_t) (void *value, char **msg_out) |
typedef int(* | post_normalize_fn_t) (void *value, char **msg_out) |
typedef int(* | legacy_validate_fn_t) (const void *oldval, void *newval, char **msg_out) |
typedef void(* | clear_cfg_fn_t) (const struct config_mgr_t *mgr, void *obj) |
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/.
Definition in file conftypes.h.
#define CFLG_GROUP_DISABLED |
A group of fflags that should be set on all disabled options.
Definition at line 221 of file conftypes.h.
#define CFLG_GROUP_OBSOLETE |
A group of flags that should be set on all obsolete options and types.
Definition at line 214 of file conftypes.h.
#define CFLG_IMMUTABLE (1u<<6) |
Flag to indicate that an option or type cannot be changed while Tor is running.
Definition at line 199 of file conftypes.h.
#define CFLG_NOCMP (1u<<4) |
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.)
Definition at line 186 of file conftypes.h.
#define CFLG_NOCOPY (1u<<3) |
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.)
Definition at line 176 of file conftypes.h.
#define CFLG_NODUMP (1u<<0) |
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 __.
Definition at line 154 of file conftypes.h.
#define CFLG_NOLIST (1u<<1) |
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.
Definition at line 161 of file conftypes.h.
#define CFLG_NOREPLACE (1u<<5) |
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.
Definition at line 194 of file conftypes.h.
#define CFLG_NOSET (1u<<2) |
Flag to indicate that an option or type is "unsettable".
An unsettable option can never be set directly by name.
Definition at line 167 of file conftypes.h.
#define CFLG_WARN_DISABLED (1u<<8) |
Flag to indicate that we should warn that an option applies only to a disabled module, whenever the user tries to use it.
Definition at line 209 of file conftypes.h.
#define CFLG_WARN_OBSOLETE (1u<<7) |
Flag to indicate that we should warn that an option or type is obsolete whenever the user tries to use it.
Definition at line 204 of file conftypes.h.
#define PLURAL | ( | tok | ) | { (#tok), (#tok "s"), 0, 0 } |
Handy macro for declaring "In the config file or on the command line, you can abbreviate <b>tok</b>s as <b>tok</b>". Used inside an array of config_abbrev_t.
For example, to declare "NumCpu" as an abbreviation for "NumCPUs", you can say PLURAL(NumCpu).
Definition at line 272 of file conftypes.h.
typedef int(* check_transition_fn_t) (const void *old_value, const void *value, char **msg_out) |
Validation function: verify whether a configuration object (value
) is an allowable value given the previous configuration value (old_value
).
On success, return 0. On failure, set msg_out to a newly allocated string containing an error message, and return -1.
Definition at line 288 of file conftypes.h.
typedef void(* clear_cfg_fn_t) (const struct config_mgr_t *mgr, void *obj) |
Callback to clear all non-managed fields of a configuration object.
obj is the configuration object whose non-managed fields should be cleared.
(Regular fields get cleared by config_reset(), but you might have fields in the object that do not correspond to configuration variables. If those fields need to be cleared or freed, this is where to do it.)
Definition at line 342 of file conftypes.h.
typedef int(* legacy_validate_fn_t) (const void *oldval, void *newval, char **msg_out) |
Legacy function to validate whether a given configuration is well-formed and consistent.
The configuration to validate is passed as newval. The previous configuration, if any, is provided in oldval.
This API is deprecated, since it mixes the responsibilities of pre_normalize_fn_t, post_normalize_fn_t, validate_fn_t, and check_transition_fn_t. No new instances of this function type should be written.
On success, return 0. On failure, set *msg_out to a newly allocated error message, and return -1.
Definition at line 326 of file conftypes.h.
typedef int(* post_normalize_fn_t) (void *value, char **msg_out) |
Validation function: normalize members of value
, and compute derived members.
This function is called after validation of value
, and may assume that validate_fn or check_transition_fn has passed.
On success, return 0. On failure, set msg_out to a newly allocated string containing an error message, and return -1.
Definition at line 309 of file conftypes.h.
typedef int(* pre_normalize_fn_t) (void *value, char **msg_out) |
Validation function: normalize members of value
, and compute derived members.
This function is called before any other validation of value
, and must not assume that validate_fn or check_transition_fn has passed.
On success, return 0. On failure, set msg_out to a newly allocated string containing an error message, and return -1.
Definition at line 299 of file conftypes.h.
typedef int(* validate_fn_t) (const void *value, char **msg_out) |
Validation function: verify whether a configuration object is well-formed and consistent.
On success, return 0. On failure, set msg_out to a newly allocated string containing an error message, and return -1.
Definition at line 281 of file conftypes.h.
enum config_type_t |
Enumeration of types which option values can take
Enumerator | |
---|---|
CONFIG_TYPE_STRING | 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 | Ignored (obsolete) option. Uses no storage. Reported as "obsolete" when its type is queried. |
CONFIG_TYPE_IGNORE | Ignored option. Uses no storage. Reported as "ignored" when its type is queried. For use with options used by disabled modules. |
CONFIG_TYPE_EXTENDED | Extended type: definition appears in the type_def 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. |
Definition at line 39 of file conftypes.h.