Tor 0.4.9.0-alpha-dev
Data Structures | Macros | Typedefs | Enumerations
conftypes.h File Reference

Types used to specify configurable options. More...

#include "lib/cc/torint.h"
#include <stddef.h>

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)
 

Enumerations

enum  config_type_t {
  CONFIG_TYPE_STRING = 0 , CONFIG_TYPE_FILENAME , CONFIG_TYPE_POSINT , CONFIG_TYPE_INT ,
  CONFIG_TYPE_UINT64 , CONFIG_TYPE_INTERVAL , CONFIG_TYPE_MSEC_INTERVAL , CONFIG_TYPE_MEMUNIT ,
  CONFIG_TYPE_DOUBLE , CONFIG_TYPE_BOOL , CONFIG_TYPE_AUTOBOOL , CONFIG_TYPE_ISOTIME ,
  CONFIG_TYPE_CSV , CONFIG_TYPE_CSV_INTERVAL , CONFIG_TYPE_LINELIST , CONFIG_TYPE_LINELIST_S ,
  CONFIG_TYPE_LINELIST_V , CONFIG_TYPE_OBSOLETE , CONFIG_TYPE_IGNORE , CONFIG_TYPE_EXTENDED
}
 

Detailed Description

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.

Macro Definition Documentation

◆ CFLG_GROUP_DISABLED

#define CFLG_GROUP_DISABLED
Value:
CFLG_WARN_DISABLED)
#define CFLG_NODUMP
Definition: conftypes.h:154
#define CFLG_NOCMP
Definition: conftypes.h:186
#define CFLG_NOCOPY
Definition: conftypes.h:176
#define CFLG_NOSET
Definition: conftypes.h:167
#define CFLG_NOLIST
Definition: conftypes.h:161

A group of fflags that should be set on all disabled options.

Definition at line 221 of file conftypes.h.

◆ CFLG_GROUP_OBSOLETE

#define CFLG_GROUP_OBSOLETE
Value:

A group of flags that should be set on all obsolete options and types.

Definition at line 214 of file conftypes.h.

◆ CFLG_IMMUTABLE

#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.

◆ CFLG_NOCMP

#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.

◆ CFLG_NOCOPY

#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.

◆ CFLG_NODUMP

#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.

◆ CFLG_NOLIST

#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.

◆ CFLG_NOREPLACE

#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.

◆ CFLG_NOSET

#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.

◆ CFLG_WARN_DISABLED

#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.

◆ CFLG_WARN_OBSOLETE

#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.

◆ PLURAL

#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 Documentation

◆ check_transition_fn_t

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.

◆ clear_cfg_fn_t

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.

◆ legacy_validate_fn_t

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.

◆ post_normalize_fn_t

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.

◆ pre_normalize_fn_t

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.

◆ validate_fn_t

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.

Enumeration Type Documentation

◆ 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.