tor  0.4.2.1-alpha-dev
Data Structures | Macros | Typedefs | Functions
confparse.c File Reference
#include "orconfig.h"
#include "lib/confmgt/confparse.h"
#include "lib/confmgt/structvar.h"
#include "lib/confmgt/unitparse.h"
#include "lib/container/bitarray.h"
#include "lib/container/smartlist.h"
#include "lib/encoding/confline.h"
#include "lib/log/escape.h"
#include "lib/log/log.h"
#include "lib/log/util_bug.h"
#include "lib/string/compat_ctype.h"
#include "lib/string/printf.h"
#include "lib/string/util_string.h"
#include "ext/siphash.h"

Go to the source code of this file.

Data Structures

struct  managed_var_t
 
struct  config_suite_t
 
struct  config_mgr_t
 

Macros

#define CONFPARSE_PRIVATE
 
#define managed_var_free(mv)   FREE_AND_NULL(managed_var_t, managed_var_free_, (mv))
 
#define config_suite_free(suite)   FREE_AND_NULL(config_suite_t, config_suite_free_, (suite))
 
#define IDX_TOPLEVEL   (-1)
 
#define CONFIG_CHECK(mgr, cfg)
 

Typedefs

typedef struct managed_var_t managed_var_t
 

Functions

static void config_reset (const config_mgr_t *fmt, void *options, const managed_var_t *var, int use_defaults)
 
static void config_mgr_register_fmt (config_mgr_t *mgr, const config_format_t *fmt, int object_idx)
 
static void managed_var_free_ (managed_var_t *mv)
 
static config_suite_tconfig_suite_new (void)
 
static void config_suite_free_ (config_suite_t *suite)
 
config_mgr_tconfig_mgr_new (const config_format_t *toplevel_fmt)
 
int config_mgr_add_format (config_mgr_t *mgr, const config_format_t *fmt)
 
static config_suite_t ** config_mgr_get_suite_ptr (const config_mgr_t *mgr, void *toplevel)
 
STATIC void * config_mgr_get_obj_mutable (const config_mgr_t *mgr, void *toplevel, int idx)
 
STATIC const void * config_mgr_get_obj (const config_mgr_t *mgr, const void *toplevel, int idx)
 
static int managed_var_cmp (const void **a, const void **b)
 
void config_mgr_freeze (config_mgr_t *mgr)
 
void config_mgr_free_ (config_mgr_t *mgr)
 
smartlist_tconfig_mgr_list_vars (const config_mgr_t *mgr)
 
smartlist_tconfig_mgr_list_deprecated_vars (const config_mgr_t *mgr)
 
static void config_mgr_assert_magic_ok (const config_mgr_t *mgr, const void *options)
 
void * config_new (const config_mgr_t *mgr)
 
const char * config_expand_abbrev (const config_mgr_t *mgr, const char *option, int command_line, int warn_obsolete)
 
const char * config_find_deprecation (const config_mgr_t *mgr, const char *key)
 
static const managed_var_tconfig_mgr_find_var (const config_mgr_t *mgr, const char *key, bool allow_truncated, int *idx_out)
 
const char * config_find_option_name (const config_mgr_t *mgr, const char *key)
 
static int config_count_options (const config_mgr_t *mgr)
 
static bool config_var_has_flag (const config_var_t *var, uint32_t flag)
 
static bool config_var_is_replaced_on_set (const config_var_t *var)
 
bool config_var_is_settable (const config_var_t *var)
 
static bool config_var_is_gettable (const config_var_t *var)
 
static bool config_var_should_list_changes (const config_var_t *var)
 
static bool config_var_needs_copy (const config_var_t *var)
 
bool config_var_is_listable (const config_var_t *var)
 
static bool config_var_is_dumpable (const config_var_t *var)
 
static int config_assign_value (const config_mgr_t *mgr, void *options, config_line_t *c, char **msg)
 
static void config_mark_lists_fragile (const config_mgr_t *mgr, void *options)
 
void warn_deprecated_option (const char *what, const char *why)
 
static int config_assign_line (const config_mgr_t *mgr, void *options, config_line_t *c, unsigned flags, bitarray_t *options_seen, char **msg)
 
STATIC void config_reset_line (const config_mgr_t *mgr, void *options, const char *key, int use_defaults)
 
static int config_value_needs_escape (const char *value)
 
config_line_tconfig_get_assigned_option (const config_mgr_t *mgr, const void *options, const char *key, int escape_val)
 
int config_assign (const config_mgr_t *mgr, void *options, config_line_t *list, unsigned config_assign_flags, char **msg)
 
static void config_clear (const config_mgr_t *mgr, void *options, const managed_var_t *var)
 
void config_free_ (const config_mgr_t *mgr, void *options)
 
int config_is_same (const config_mgr_t *mgr, const void *o1, const void *o2, const char *name)
 
config_line_tconfig_get_changes (const config_mgr_t *mgr, const void *options1, const void *options2)
 
void * config_dup (const config_mgr_t *mgr, const void *old)
 
void config_init (const config_mgr_t *mgr, void *options)
 
char * config_dump (const config_mgr_t *mgr, const void *default_options, const void *options, int minimal, int comment_defaults)
 
bool config_check_ok (const config_mgr_t *mgr, const void *options, int severity)
 

Detailed Description

Back-end for parsing and generating key-value files, used to implement the torrc file format and the state file.

This module is used by config.c to parse and encode torrc configuration files, and by statefile.c to parse and encode the $DATADIR/state file.

To use this module, its callers provide an instance of config_format_t to describe the mappings from a set of configuration options to a number of fields in a C structure. With this mapping, the functions here can convert back and forth between the C structure specified, and a linked list of key-value pairs.

Definition in file confparse.c.

Macro Definition Documentation

◆ CONFIG_CHECK

#define CONFIG_CHECK (   mgr,
  cfg 
)
Value:
STMT_END
static void config_mgr_assert_magic_ok(const config_mgr_t *mgr, const void *options)
Definition: confparse.c:340

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

Definition at line 365 of file confparse.c.

Typedef Documentation

◆ managed_var_t

typedef struct managed_var_t managed_var_t

A managed_var_t is an internal wrapper around a config_var_t in a config_format_t structure. It is used by config_mgr_t to keep track of which option goes with which structure.

Function Documentation

◆ config_assign()

int config_assign ( const config_mgr_t mgr,
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 913 of file confparse.c.

References CAL_CLEAR_FIRST, CAL_USE_DEFAULTS, CONFIG_CHECK, config_count_options(), config_expand_abbrev(), and tor_free.

Referenced by options_init(), and options_trial_assign().

◆ config_assign_line()

static int config_assign_line ( const config_mgr_t mgr,
void *  options,
config_line_t c,
unsigned  flags,
bitarray_t options_seen,
char **  msg 
)
static

If c is a syntactically valid configuration line, update options with its value and return 0. Otherwise return -1 for bad key, -2 for bad value.

If clear_first is set, clear the value first. Then if use_defaults is set, set the value to the default.

Called from config_assign().

Definition at line 687 of file confparse.c.

References CAL_CLEAR_FIRST, CAL_USE_DEFAULTS, CAL_WARN_DEPRECATIONS, CONFIG_CHECK, config_mgr_find_var(), config_format_t::extra, struct_member_t::offset, STRUCT_VAR_P, and config_mgr_t::toplevel.

◆ config_assign_value()

static int config_assign_value ( const config_mgr_t mgr,
void *  options,
config_line_t c,
char **  msg 
)
static

c->key is known to be a real key. Update options with c->value and return 0, or return -1 if bad value.

Called from config_assign_line() and option_reset().

Definition at line 632 of file confparse.c.

References CONFIG_CHECK, config_mgr_find_var(), config_mgr_get_obj_mutable(), managed_var_t::cvar, struct_member_t::name, managed_var_t::object_idx, struct_var_kvassign(), and tor_assert().

◆ config_check_ok()

bool config_check_ok ( const config_mgr_t mgr,
const void *  options,
int  severity 
)

Return true if every member of options is in-range and well-formed. Return false otherwise. Log errors at level severity.

Definition at line 1226 of file confparse.c.

References config_mgr_t::all_vars, LD_BUG, log_fn, SMARTLIST_FOREACH_BEGIN, and struct_var_ok().

◆ config_clear()

static void config_clear ( const config_mgr_t mgr,
void *  options,
const managed_var_t var 
)
static

Reset config option var to 0, 0.0, NULL, or the equivalent. Called from config_reset() and config_free().

Definition at line 964 of file confparse.c.

References config_mgr_get_obj_mutable(), managed_var_t::cvar, managed_var_t::object_idx, and struct_var_free().

Referenced by config_reset().

◆ config_count_options()

static int config_count_options ( const config_mgr_t mgr)
static

Return the number of option entries in fmt.

Definition at line 509 of file confparse.c.

Referenced by config_assign().

◆ config_dump()

char* config_dump ( const config_mgr_t mgr,
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 1150 of file confparse.c.

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

◆ config_dup()

void* config_dup ( const config_mgr_t mgr,
const void *  old 
)

◆ config_expand_abbrev()

const char* config_expand_abbrev ( const config_mgr_t mgr,
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 399 of file confparse.c.

References config_mgr_t::all_abbrevs, and SMARTLIST_FOREACH_BEGIN.

Referenced by config_assign(), and config_find_option_name().

◆ config_find_deprecation()

const char* config_find_deprecation ( const config_mgr_t mgr,
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 426 of file confparse.c.

◆ config_find_option_name()

const char* config_find_option_name ( const config_mgr_t mgr,
const char *  key 
)

If key is a name or an abbreviation configuration option, return the corresponding canonical name for it. Warn if the abbreviation is non-standard. Return NULL if the option does not exist.

Definition at line 497 of file confparse.c.

References config_expand_abbrev(), config_mgr_find_var(), managed_var_t::cvar, and struct_member_t::name.

Referenced by option_get_canonical_name(), and option_is_recognized().

◆ config_free_()

void config_free_ ( const config_mgr_t mgr,
void *  options 
)

Release storage held by options.

Definition at line 1001 of file confparse.c.

References config_format_t::clear_fn, config_mgr_get_suite_ptr(), config_mgr_t::toplevel, and tor_assert().

◆ config_get_assigned_option()

config_line_t* config_get_assigned_option ( const config_mgr_t mgr,
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 819 of file confparse.c.

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

Referenced by config_get_changes(), and option_get_assignment().

◆ config_get_changes()

config_line_t* config_get_changes ( const config_mgr_t mgr,
const void *  options1,
const void *  options2 
)

Return a list of the options which have changed between options1 and options2. If an option has reverted to its default value, it has a value entry of NULL.

options1 and options2 must be top-level configuration objects of the type managed by mgr.

Definition at line 1072 of file confparse.c.

References config_mgr_t::all_vars, config_get_assigned_option(), config_mgr_get_obj(), config_var_should_list_changes(), SMARTLIST_FOREACH_BEGIN, and struct_var_eq().

◆ config_init()

void config_init ( const config_mgr_t mgr,
void *  options 
)

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

Definition at line 1134 of file confparse.c.

References config_mgr_t::all_vars, CONFIG_CHECK, config_reset(), and SMARTLIST_FOREACH_BEGIN.

Referenced by config_dump(), and options_init().

◆ config_is_same()

int config_is_same ( const config_mgr_t mgr,
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 1046 of file confparse.c.

◆ config_mark_lists_fragile()

static void config_mark_lists_fragile ( const config_mgr_t mgr,
void *  options 
)
static

Mark every linelist in options "fragile", so that fresh assignments to it will replace old ones.

Definition at line 650 of file confparse.c.

References config_mgr_t::all_vars, config_mgr_get_obj_mutable(), SMARTLIST_FOREACH_BEGIN, struct_var_mark_fragile(), and tor_assert().

◆ config_mgr_add_format()

int config_mgr_add_format ( config_mgr_t mgr,
const config_format_t fmt 
)

Add a new format to this configuration object. Asserts on failure.

Returns an internal "index" value used to identify this format within all of those formats contained in mgr. This index value should not generally be used outside of this module.

Definition at line 211 of file confparse.c.

References tor_assert().

◆ config_mgr_assert_magic_ok()

static void config_mgr_assert_magic_ok ( const config_mgr_t mgr,
const void *  options 
)
static

Assert that the magic fields in options and its subsidiary objects are all okay.

Definition at line 340 of file confparse.c.

References config_mgr_get_suite_ptr(), config_mgr_t::frozen, struct_check_magic(), config_mgr_t::toplevel_magic, and tor_assert().

◆ config_mgr_find_var()

static const managed_var_t* config_mgr_find_var ( const config_mgr_t mgr,
const char *  key,
bool  allow_truncated,
int *  idx_out 
)
static

Find the managed_var_t object for a variable whose name is name according to mgr. Return that object, or NULL if none exists.

If allow_truncated is true, then accept any variable whose name begins with name.

If idx_out is not NULL, set *idx_out to the position of that variable within mgr->all_vars, or to -1 if the variable is not found.

Definition at line 452 of file confparse.c.

References config_mgr_t::all_vars, and SMARTLIST_FOREACH_BEGIN.

Referenced by config_assign_line(), config_assign_value(), config_find_option_name(), config_get_assigned_option(), and config_reset_line().

◆ config_mgr_free_()

void config_mgr_free_ ( config_mgr_t mgr)

Release all storage held in mgr

Definition at line 297 of file confparse.c.

References config_mgr_t::all_vars, and SMARTLIST_FOREACH.

◆ config_mgr_freeze()

void config_mgr_freeze ( config_mgr_t mgr)

Mark a configuration manager as "frozen", so that no more formats can be added, and so that it can be used for manipulating configuration objects.

Definition at line 280 of file confparse.c.

References config_mgr_t::all_vars, config_mgr_t::frozen, config_format_t::magic, struct_magic_decl_t::magic_val, managed_var_cmp(), smartlist_sort(), config_mgr_t::toplevel, and config_mgr_t::toplevel_magic.

◆ config_mgr_get_obj()

STATIC const void* config_mgr_get_obj ( const config_mgr_t mgr,
const void *  toplevel,
int  idx 
)

As config_mgr_get_obj_mutable(), but return a const pointer.

Definition at line 260 of file confparse.c.

References config_mgr_get_obj_mutable().

Referenced by config_dup(), and config_get_changes().

◆ config_mgr_get_obj_mutable()

STATIC void* config_mgr_get_obj_mutable ( const config_mgr_t mgr,
void *  toplevel,
int  idx 
)

Return a pointer to the configuration object within toplevel whose index is idx.

NOTE: XXXX Eventually, there will be multiple objects supported within the toplevel object. For example, the or_options_t will contain pointers to configuration objects for other modules. This function gets the sub-object for a particular module.

Definition at line 241 of file confparse.c.

References tor_assert().

Referenced by config_assign_value(), config_clear(), config_dup(), config_mark_lists_fragile(), and config_mgr_get_obj().

◆ config_mgr_get_suite_ptr()

static config_suite_t** config_mgr_get_suite_ptr ( const config_mgr_t mgr,
void *  toplevel 
)
inlinestatic

Return a pointer to the config_suite_t * pointer inside a configuration object; returns NULL if there is no such member.

Definition at line 224 of file confparse.c.

References config_format_t::config_suite_offset, STRUCT_VAR_P, and config_mgr_t::toplevel.

Referenced by config_free_(), and config_mgr_assert_magic_ok().

◆ config_mgr_list_deprecated_vars()

smartlist_t* config_mgr_list_deprecated_vars ( const config_mgr_t mgr)

Return a new smartlist_t containing the names of all deprecated variables. The elements of this smartlist do not need to be freed; they have the same lifespan as mgr.

Definition at line 328 of file confparse.c.

References config_mgr_t::all_deprecations, smartlist_add(), SMARTLIST_FOREACH, and tor_assert().

Referenced by list_deprecated_options().

◆ config_mgr_list_vars()

smartlist_t* config_mgr_list_vars ( const config_mgr_t mgr)

Return a new smartlist_t containing a config_var_t for every variable that mgr knows about. The elements of this smartlist do not need to be freed; they have the same lifespan as mgr.

Definition at line 314 of file confparse.c.

References config_mgr_t::all_vars, smartlist_add(), SMARTLIST_FOREACH, and tor_assert().

Referenced by getinfo_helper_config(), and list_torrc_options().

◆ config_mgr_new()

config_mgr_t* config_mgr_new ( const config_format_t toplevel_fmt)

Create a new config_mgr_t to manage a set of configuration objects to be wrapped under toplevel_fmt.

Definition at line 145 of file confparse.c.

◆ config_mgr_register_fmt()

static void config_mgr_register_fmt ( config_mgr_t mgr,
const config_format_t fmt,
int  object_idx 
)
static

Add a config_format_t to a manager, with a specified (unique) index.

Definition at line 161 of file confparse.c.

◆ config_new()

void* config_new ( const config_mgr_t mgr)

Allocate an empty configuration object of a given format type.

Definition at line 371 of file confparse.c.

References config_mgr_t::frozen, and tor_assert().

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

◆ config_reset()

static void config_reset ( const config_mgr_t mgr,
void *  options,
const managed_var_t var,
int  use_defaults 
)
static

Clear the option indexed by var in options. Then if use_defaults, set it to its default value. Called by config_init() and option_reset_line() and option_assign_line().

Definition at line 974 of file confparse.c.

References CONFIG_CHECK, config_clear(), managed_var_t::cvar, and config_var_t::initvalue.

Referenced by config_init(), and config_reset_line().

◆ config_reset_line()

STATIC void config_reset_line ( const config_mgr_t mgr,
void *  options,
const char *  key,
int  use_defaults 
)

Restore the option named key in options to its default value. Called from config_assign().

Definition at line 774 of file confparse.c.

References CONFIG_CHECK, config_mgr_find_var(), and config_reset().

◆ config_suite_free_()

static void config_suite_free_ ( config_suite_t suite)
static

Release all storage held by a config_suite_t. (Does not free any configuration objects it holds; the caller must do that first.)

Definition at line 96 of file confparse.c.

◆ config_suite_new()

static config_suite_t* config_suite_new ( void  )
static

Allocate a new empty config_suite_t.

Definition at line 86 of file confparse.c.

◆ config_value_needs_escape()

static int config_value_needs_escape ( const char *  value)
static

Return true iff value needs to be quoted and escaped to be used in a configuration file.

Definition at line 791 of file confparse.c.

◆ config_var_has_flag()

static bool config_var_has_flag ( const config_var_t var,
uint32_t  flag 
)
static

Return true iff at least one bit from flag is set on var, either in var's flags, or on the flags of its type.

Definition at line 519 of file confparse.c.

References config_var_t::flags, and struct_var_get_flags().

Referenced by config_var_is_dumpable(), config_var_is_listable(), config_var_is_replaced_on_set(), config_var_is_settable(), config_var_needs_copy(), and config_var_should_list_changes().

◆ config_var_is_dumpable()

static bool config_var_is_dumpable ( const config_var_t var)
static

Return true iff variable var should be written out when we are writing our configuration to disk, to a controller, or via the –dump-config command.

This option may be set because a variable is hidden, or because it is derived from another variable which will already be written out.

Definition at line 617 of file confparse.c.

References CFLG_NODUMP, and config_var_has_flag().

◆ config_var_is_gettable()

static bool config_var_is_gettable ( const config_var_t var)
static

Return true iff the controller is allowed to fetch the value of var.

Definition at line 552 of file confparse.c.

◆ config_var_is_listable()

bool config_var_is_listable ( const config_var_t var)

Return true iff variable var should appear on list of variable names given to the controller or the CLI.

(Note that this option is imperfectly obeyed. The –list-torrc-options command looks at the "settable" flag, whereas "GETINFO config/defaults" and "list_deprecated_*()" do not filter their results. It would be good for consistency to try to converge these behaviors in the future.)

Definition at line 603 of file confparse.c.

References CFLG_NOLIST, and config_var_has_flag().

Referenced by getinfo_helper_config().

◆ config_var_is_replaced_on_set()

static bool config_var_is_replaced_on_set ( const config_var_t var)
static

Return true if assigning a value to var replaces the previous value. Return false if assigning a value to var appends to the previous value.

Definition at line 532 of file confparse.c.

References CFLG_NOREPLACE, and config_var_has_flag().

◆ config_var_is_settable()

bool config_var_is_settable ( const config_var_t var)

Return true iff var may be assigned by name (e.g., via the CLI, the configuration files, or the controller API).

Definition at line 542 of file confparse.c.

References CFLG_NOSET, and config_var_has_flag().

Referenced by list_torrc_options().

◆ config_var_needs_copy()

static bool config_var_needs_copy ( const config_var_t var)
static

Return true iff we need to copy the data for var when we are copying a config option.

A false option might mean that the variable is a derived variable, and that copying the variable it derives from copies it– or it might mean that there is no data to copy.

Definition at line 587 of file confparse.c.

References CFLG_NOCOPY, and config_var_has_flag().

Referenced by config_dup().

◆ config_var_should_list_changes()

static bool config_var_should_list_changes ( const config_var_t var)
static

Return true iff we need to check var for changes when we are comparing config options for changes.

A false result might mean that the variable is a derived variable, and that comparing the variable it derives from compares this one too– or it might mean that there is no data to compare.

Definition at line 573 of file confparse.c.

References CFLG_NOCMP, and config_var_has_flag().

Referenced by config_get_changes().

◆ managed_var_cmp()

static int managed_var_cmp ( const void **  a,
const void **  b 
)
static

Sorting helper for smartlist of managed_var_t

Definition at line 267 of file confparse.c.

References managed_var_t::cvar, and struct_member_t::name.

Referenced by config_mgr_freeze().

◆ managed_var_free_()

static void managed_var_free_ ( managed_var_t mv)
static

Release all storage held in a managed_var_t.

Definition at line 66 of file confparse.c.

References tor_free.

◆ warn_deprecated_option()

void warn_deprecated_option ( const char *  what,
const char *  why 
)

Log a warning that declaring that the option called what is deprecated because of the reason in why.

(Both arguments must be non-NULL.)

Definition at line 668 of file confparse.c.