Tor
0.4.7.0-alpha-dev
|
Back-end for parsing and generating key-value files, used to implement the torrc file format and the state file. More...
#include "orconfig.h"
#include "lib/confmgt/confmgt.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 | CONFMGT_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) |
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_t * | config_suite_new (void) |
static void | config_suite_free_ (config_suite_t *suite) |
config_mgr_t * | config_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) |
void * | config_mgr_get_obj_mutable (const config_mgr_t *mgr, void *toplevel, int idx) |
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_t * | config_mgr_list_vars (const config_mgr_t *mgr) |
smartlist_t * | config_mgr_list_deprecated_vars (const config_mgr_t *mgr) |
void | config_check_toplevel_magic (const config_mgr_t *mgr, const void *object) |
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_t * | config_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_t * | config_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_t * | config_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) |
static int | config_check_immutable_flags (const config_format_t *fmt, const void *old_options, const void *new_options, char **msg_out) |
static validation_status_t | config_validate_single (const config_format_t *fmt, const void *old_options, void *options, char **msg_out) |
validation_status_t | config_validate (const config_mgr_t *mgr, const void *old_options, void *options, char **msg_out) |
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) |
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 confmgt.c.
#define CONFIG_CHECK | ( | mgr, | |
cfg | |||
) |
Macro: assert that cfg has the right magic field for mgr.
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:
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 937 of file confmgt.c.
Referenced by config_service(), options_init(), and options_trial_assign().
|
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().
|
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().
|
static |
bool config_check_ok | ( | const config_mgr_t * | mgr, |
const void * | options, | ||
int | severity | ||
) |
void config_check_toplevel_magic | ( | const config_mgr_t * | mgr, |
const void * | object | ||
) |
|
static |
Reset config option var to 0, 0.0, NULL, or the equivalent. Called from config_reset() and config_free().
Definition at line 988 of file confmgt.c.
Referenced by config_reset().
|
static |
Return the number of option entries in fmt.
Definition at line 525 of file confmgt.c.
Referenced by config_assign().
char* config_dump | ( | const config_mgr_t * | mgr, |
const void * | default_options, | ||
const void * | options, | ||
int | minimal, | ||
int | comment_defaults | ||
) |
void* config_dup | ( | const config_mgr_t * | mgr, |
const void * | old | ||
) |
Copy storage held by old into a new or_options_t and return it.
Definition at line 1132 of file confmgt.c.
Referenced by options_trial_assign().
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 415 of file confmgt.c.
Referenced by config_assign(), and config_find_option_name().
const char* config_find_deprecation | ( | const config_mgr_t * | mgr, |
const char * | key | ||
) |
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 513 of file confmgt.c.
Referenced by option_get_canonical_name(), and option_is_recognized().
void config_free_ | ( | const config_mgr_t * | mgr, |
void * | options | ||
) |
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 843 of file confmgt.c.
Referenced by config_get_changes(), option_get_assignment(), and warn_about_relative_paths().
config_line_t* config_get_changes | ( | const config_mgr_t * | mgr, |
const void * | options1, | ||
const void * | options2 | ||
) |
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 1158 of file confmgt.c.
Referenced by config_dump(), hs_opts_new(), and options_init().
int config_is_same | ( | const config_mgr_t * | mgr, |
const void * | o1, | ||
const void * | o2, | ||
const char * | name | ||
) |
|
static |
int config_mgr_add_format | ( | config_mgr_t * | mgr, |
const config_format_t * | fmt | ||
) |
|
static |
|
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 468 of file confmgt.c.
Referenced by config_assign_line(), config_assign_value(), config_find_option_name(), config_get_assigned_option(), config_is_same(), and config_reset_line().
void config_mgr_free_ | ( | config_mgr_t * | mgr | ) |
void config_mgr_freeze | ( | config_mgr_t * | mgr | ) |
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 265 of file confmgt.c.
Referenced by config_dup(), config_get_changes(), and config_is_same().
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 246 of file confmgt.c.
Referenced by config_assign_value(), config_clear(), config_dup(), config_mark_lists_fragile(), and config_mgr_get_obj().
|
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 229 of file confmgt.c.
Referenced by config_free_(), config_mgr_assert_magic_ok(), and config_validate().
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 333 of file confmgt.c.
Referenced by list_deprecated_options().
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 319 of file confmgt.c.
Referenced by getinfo_helper_config(), list_torrc_options(), and warn_about_relative_paths().
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.
|
static |
Add a config_format_t to a manager, with a specified (unique) index.
void* config_new | ( | const config_mgr_t * | mgr | ) |
Allocate an empty configuration object of a given format type.
Definition at line 387 of file confmgt.c.
Referenced by config_dump(), config_dup(), disk_state_new(), hs_opts_new(), ob_option_new(), and options_new().
|
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 998 of file confmgt.c.
Referenced by config_init(), and 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().
|
static |
Release all storage held by a config_suite_t. (Does not free any configuration objects it holds; the caller must do that first.)
|
static |
Allocate a new empty config_suite_t.
validation_status_t config_validate | ( | const config_mgr_t * | mgr, |
const void * | old_options, | ||
void * | options, | ||
char ** | msg_out | ||
) |
Normalize and validate all the options in configuration object options
and its sub-objects. options
may be modified as appropriate in order to set ancillary data. If old_options
is provided, make sure that the transition from old_options
to options
is permitted.
On success return VSTAT_OK; on failure set *msg_out to a newly allocated string explaining what is wrong, and return a different validation_status_t to describe which step failed.
Definition at line 1272 of file confmgt.c.
Referenced by config_dump(), options_validate_and_set(), and or_state_validate().
|
static |
Normalize and validate a single object options
within a configuration suite, according to its format. options
may be modified as appropriate in order to set ancillary data. If old_options
is provided, make sure that the transition from old_options
to options
is permitted.
On success return VSTAT_OK; on failure set *msg_out to a newly allocated string explaining what is wrong, and return a different validation_status_t to describe which step failed.
|
static |
|
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 535 of file confmgt.c.
Referenced by config_assign_value(), 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().
|
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.
|
static |
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 619 of file confmgt.c.
Referenced by getinfo_helper_config().
|
static |
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 558 of file confmgt.c.
Referenced by list_torrc_options().
|
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 603 of file confmgt.c.
Referenced by config_dup().
|
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 589 of file confmgt.c.
Referenced by config_get_changes().
|
static |
Sorting helper for smartlist of managed_var_t
Definition at line 272 of file confmgt.c.
Referenced by config_mgr_freeze().
|
static |
Release all storage held in a managed_var_t.