Data Structures | Macros | Typedefs | Enumerations | Functions
confparse.h File Reference

Go to the source code of this file.

Data Structures

struct  config_abbrev_t
struct  config_deprecation_t
struct  config_var_t
struct  config_format_t


#define PLURAL(tok)   { #tok, #tok "s", 0, 0 }
#define CONF_TEST_MEMBERS(tp, conftype, member)
#define DUMMY_TYPECHECK_INSTANCE(tp)   struct tor_semicolon_eater
#define CONFIG_CHECK(fmt, cfg)
#define CAL_USE_DEFAULTS   (1u<<0)
#define CAL_CLEAR_FIRST   (1u<<1)
#define CAL_WARN_DEPRECATIONS   (1u<<2)
#define config_free(fmt, options)
#define CFG_EQ_BOOL(a, b, opt)   ((a)->opt == (b)->opt)
#define CFG_EQ_INT(a, b, opt)   ((a)->opt == (b)->opt)
#define CFG_EQ_STRING(a, b, opt)   (!strcmp_opt((a)->opt, (b)->opt))
#define CFG_EQ_SMARTLIST(a, b, opt)   smartlist_strings_eq((a)->opt, (b)->opt)
#define CFG_EQ_LINELIST(a, b, opt)   config_lines_eq((a)->opt, (b)->opt)
#define CFG_EQ_ROUTERSET(a, b, opt)   routerset_equal((a)->opt, (b)->opt)


typedef enum config_type_t config_type_t
typedef struct config_abbrev_t config_abbrev_t
typedef struct config_deprecation_t config_deprecation_t
typedef struct config_var_t config_var_t
typedef int(* validate_fn_t) (void *, void *, void *, int, char **)
typedef void(* free_cfg_fn_t) (void *)
typedef struct config_format_t config_format_t


enum  config_type_t {


void * config_new (const config_format_t *fmt)
void config_free_ (const config_format_t *fmt, void *options)
struct config_line_tconfig_get_assigned_option (const config_format_t *fmt, const void *options, const char *key, int escape_val)
int config_is_same (const config_format_t *fmt, const void *o1, const void *o2, const char *name)
void config_init (const config_format_t *fmt, void *options)
void * config_dup (const config_format_t *fmt, const void *old)
char * config_dump (const config_format_t *fmt, const void *default_options, const void *options, int minimal, int comment_defaults)
int config_assign (const config_format_t *fmt, void *options, struct config_line_t *list, unsigned flags, char **msg)
config_var_tconfig_find_option_mutable (config_format_t *fmt, const char *key)
const char * config_find_deprecation (const config_format_t *fmt, const char *key)
const config_var_tconfig_find_option (const config_format_t *fmt, const char *key)
const char * config_expand_abbrev (const config_format_t *fmt, const char *option, int command_line, int warn_obsolete)
void warn_deprecated_option (const char *what, const char *why)

Detailed Description

Header for confparse.c.

Definition in file confparse.h.

Macro Definition Documentation


#define CONFIG_CHECK (   fmt,
tor_assert(fmt && cfg); \
tor_assert((fmt)->magic == \
*(uint32_t*)STRUCT_VAR_P(cfg,fmt->magic_offset)); \
#define STRUCT_VAR_P(st, off)

Macro: assert that cfg has the right magic field for format fmt.

Definition at line 181 of file confparse.h.

◆ config_free

#define config_free (   fmt,
do { \
config_free_((fmt), (options)); \
(options) = NULL; \
} while (0)

Definition at line 193 of file confparse.h.

Typedef Documentation

◆ config_abbrev_t

An abbreviation for a configuration option allowed on the command line.

◆ config_format_t

Information on the keys, value types, key-to-struct-member mappings, variable descriptions, validation functions, and abbreviations for a configuration or storage format.

◆ config_type_t

Enumeration of types which option values can take

◆ config_var_t

typedef struct config_var_t config_var_t

A variable allowed in the configuration file or on the command line.

◆ free_cfg_fn_t

typedef void(* free_cfg_fn_t) (void *)

Callback to free a configuration object.

Definition at line 157 of file confparse.h.

◆ validate_fn_t

typedef int(* validate_fn_t) (void *, void *, void *, int, char **)

Type of a callback to validate whether a given configuration is well-formed and consistent. See options_trial_assign() for documentation of arguments.

Definition at line 154 of file confparse.h.

Enumeration Type Documentation

◆ config_type_t

Enumeration of types which option values can take


An arbitrary string.


A filename: some prefixes get expanded.


A non-negative integer less than MAX_INT


Any integer.


A value in range 0..UINT64_MAX


A number of seconds, with optional units


A number of milliseconds, with optional units


A number of bytes, with optional units


A floating-point value


A boolean value, expressed as 0 or 1.


A boolean+auto value, expressed 0 for false, 1 for true, and -1 for auto


An ISO-formatted time relative to UTC.


A list of strings, separated by commas and optional whitespace.


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.


Uninterpreted config lines


Uninterpreted, context-sensitive config lines, mixed with other keywords.


Catch-all "virtual" option to summarize context-sensitive config lines when fetching.


A list of router names, addrs, and fps, parsed into a routerset_t.


Obsolete (ignored) option.

Definition at line 17 of file confparse.h.

Function Documentation

◆ config_assign()

int config_assign ( const config_format_t fmt,
void *  options,
config_line_t list,
unsigned  config_assign_flags,
char **  msg 

Iterate through the linked list of requested options list. For each item, convert as appropriate and assign to options. If an item is unrecognized, set *msg and return -1 immediately, else return 0 for success.

If clear_first, interpret config options as replacing (not extending) their previous values. If clear_first is set, then use_defaults to decide if you set to defaults after clearing, or make the value 0 or NULL.

Here are the use cases:

  1. A non-empty AllowInvalid line in your torrc. Appends to current if linelist, replaces current if csv.
  2. An empty AllowInvalid line in your torrc. Should clear it.
  3. "RESETCONF AllowInvalid" sets it to default.
  4. "SETCONF AllowInvalid" makes it NULL.
  5. "SETCONF AllowInvalid=foo" clears it and sets it to "foo".

Use_defaults Clear_first 0 0 "append" 1 0 undefined, don't use 0 1 "set to null first" 1 1 "set to defaults first" Return 0 on success, -1 on bad key, -2 on bad value.

As an additional special case, if a LINELIST config option has no value and clear_first is 0, then warn and ignore it.

Now we're done assigning a group of options to the configuration. Subsequent group assignments should replace linelists, not extend them.

Definition at line 714 of file confparse.c.

References config_count_options().

Referenced by config_dup(), and options_trial_assign().

◆ config_dump()

char* config_dump ( const config_format_t fmt,
const void *  default_options,
const void *  options,
int  minimal,
int  comment_defaults 

Allocate and return a new string holding the written-out values of the vars in 'options'. If 'minimal', do not write out any default-valued vars. Else, if comment_defaults, write default values as comments.

Definition at line 943 of file confparse.c.

References config_init(), config_new(), and config_format_t::validate_fn.

◆ config_dup()

void* config_dup ( const config_format_t fmt,
const void *  old 

◆ config_expand_abbrev()

const char* config_expand_abbrev ( const config_format_t fmt,
const char *  option,
int  command_line,
int  warn_obsolete 

If option is an official abbreviation for a longer option, return the longer option. Otherwise return option. If command_line is set, apply all abbreviations. Otherwise, only apply abbreviations that work for the config file and the command line. If warn_obsolete is set, warn about deprecated names.

Definition at line 58 of file confparse.c.

References config_format_t::abbrevs.

◆ config_find_deprecation()

const char* config_find_deprecation ( const config_format_t fmt,
const char *  key 

If key is a deprecated configuration option, return the message explaining why it is deprecated (which may be an empty string). Return NULL if it is not deprecated. The key field must be fully expanded.

Definition at line 88 of file confparse.c.

◆ config_find_option()

const config_var_t* config_find_option ( const config_format_t fmt,
const char *  key 

If key is a configuration option, return the corresponding const config_var_t. Otherwise, if key is a non-standard abbreviation, warn, and return the corresponding const config_var_t. Otherwise return NULL.

Definition at line 137 of file confparse.c.

References config_find_option_mutable().

Referenced by config_assign_value(), config_get_assigned_option(), config_reset_line(), option_get_canonical_name(), and option_is_recognized().

◆ config_find_option_mutable()

config_var_t* config_find_option_mutable ( config_format_t fmt,
const char *  key 

As config_find_option, but return a non-const pointer.

Definition at line 106 of file confparse.c.

References config_var_t::name, and config_format_t::vars.

Referenced by config_find_option().

◆ config_free_()

void config_free_ ( const config_format_t fmt,
void *  options 

Release storage held by options.

Definition at line 851 of file confparse.c.

References config_clear(), config_format_t::extra, config_var_t::name, STRUCT_VAR_P, tor_assert(), config_var_t::var_offset, and config_format_t::vars.

◆ config_get_assigned_option()

struct config_line_t* config_get_assigned_option ( const config_format_t fmt,
const void *  options,
const char *  key,
int  escape_val 

Return newly allocated line or lines corresponding to key in the configuration options. If escape_val is true and a value needs to be quoted before it's put in a config file, quote and escape that value. Return NULL if no such key exists.

Definition at line 532 of file confparse.c.

References CONFIG_CHECK, config_find_option(), and tor_assert().

Referenced by config_dup(), and option_get_assignment().

◆ config_init()

void config_init ( const config_format_t fmt,
void *  options 

Set all vars in the configuration object options to their default values.

Definition at line 924 of file confparse.c.

References CONFIG_CHECK, config_reset(), config_var_t::initvalue, config_var_t::name, and config_format_t::vars.

Referenced by config_dump(), and options_init().

◆ config_is_same()

int config_is_same ( const config_format_t fmt,
const void *  o1,
const void *  o2,
const char *  name 

Return true iff the option name has the same value in o1 and o2. Must not be called for LINELIST_S or OBSOLETE options.

Definition at line 874 of file confparse.c.

◆ config_new()

void* config_new ( const config_format_t fmt)

Allocate an empty configuration object of a given format type.

Definition at line 40 of file confparse.c.

Referenced by config_dump(), config_dup(), and options_new().