Data Structures | Macros | Typedefs | Functions
confparse.h File Reference
#include "lib/conf/conftypes.h"
#include "lib/conf/confmacros.h"
#include "lib/testsupport/testsupport.h"

Go to the source code of this file.

Data Structures

struct  config_abbrev_t
struct  config_deprecation_t
struct  config_format_t


#define PLURAL(tok)   { #tok, #tok "s", 0, 0 }
#define config_mgr_free(mgr)   FREE_AND_NULL(config_mgr_t, config_mgr_free_, (mgr))
#define CAL_USE_DEFAULTS   (1u<<0)
#define CAL_CLEAR_FIRST   (1u<<1)
#define CAL_WARN_DEPRECATIONS   (1u<<2)
#define config_free(mgr, 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 struct config_abbrev_t config_abbrev_t
typedef struct config_deprecation_t config_deprecation_t
typedef int(* validate_fn_t) (void *oldval, void *newval, void *default_val, int from_setconf, char **msg_out)
typedef void(* clear_cfg_fn_t) (const struct config_mgr_t *mgr, void *obj)
typedef struct config_format_t config_format_t
typedef struct config_mgr_t config_mgr_t
typedef struct config_suite_t config_suite_t


config_mgr_tconfig_mgr_new (const config_format_t *toplevel_fmt)
void config_mgr_free_ (config_mgr_t *mgr)
int config_mgr_add_format (config_mgr_t *mgr, const config_format_t *fmt)
void config_mgr_freeze (config_mgr_t *mgr)
struct smartlist_tconfig_mgr_list_vars (const config_mgr_t *mgr)
struct smartlist_tconfig_mgr_list_deprecated_vars (const config_mgr_t *mgr)
void * config_new (const config_mgr_t *fmt)
void config_free_ (const config_mgr_t *fmt, void *options)
struct config_line_tconfig_get_assigned_option (const config_mgr_t *mgr, const void *options, const char *key, int escape_val)
int config_is_same (const config_mgr_t *fmt, const void *o1, const void *o2, const char *name)
struct config_line_tconfig_get_changes (const config_mgr_t *mgr, const void *options1, const void *options2)
void config_init (const config_mgr_t *mgr, void *options)
void * config_dup (const config_mgr_t *mgr, const void *old)
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)
int config_assign (const config_mgr_t *mgr, void *options, struct config_line_t *list, unsigned flags, char **msg)
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)
const char * config_expand_abbrev (const config_mgr_t *mgr, const char *option, int command_line, int warn_obsolete)
void warn_deprecated_option (const char *what, const char *why)
bool config_var_is_settable (const config_var_t *var)
bool config_var_is_listable (const config_var_t *var)

Detailed Description

Header for confparse.c.

Definition in file confparse.h.

Macro Definition Documentation


#define CAL_CLEAR_FIRST   (1u<<1)

Flag for config_assign: if set, then we reset every provided config option before we set it.

For example, if this flag is not set, then passing a multi-line option to config_assign will cause any previous value to be extended. But if this flag is set, then a multi-line option will replace any previous value.

Definition at line 152 of file confparse.h.


#define CAL_USE_DEFAULTS   (1u<<0)

Flag for config_assign: if set, then "resetting" an option changes it to its default value, as specified in the config_var_t. Otherwise, "resetting" an option changes it to a type-dependent null value – typically 0 or NULL.

(An option is "reset" when it is set to an empty value, or as described in CAL_CLEAR_FIRST).

Definition at line 143 of file confparse.h.


#define CAL_WARN_DEPRECATIONS   (1u<<2)

Flag for config_assign: if set, we warn about deprecated options.

Definition at line 156 of file confparse.h.

◆ config_free

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

Definition at line 160 of file confparse.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 52 of file confparse.h.

Typedef Documentation

◆ 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 89 of file confparse.h.

◆ config_abbrev_t

An abbreviation or alias for a configuration option.

◆ config_deprecation_t

A note that a configuration option is deprecated, with an explanation why.

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

typedef struct config_mgr_t config_mgr_t

A collection of config_format_t objects to describe several objects that are all configured with the same configuration file.

(NOTE: for now, this only handles a single config_format_t.)

Definition at line 119 of file confparse.h.

◆ config_suite_t

A collection of managed configuration objects.

Definition at line 132 of file confparse.h.

◆ validate_fn_t

typedef int(* validate_fn_t) (void *oldval, void *newval, void *default_val, int from_setconf, char **msg_out)

Type of a callback 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. The default_val argument receives a configuration object initialized with default values for all its fields. The from_setconf argument is true iff the input comes from a SETCONF controller command.

On success, return 0. On failure, set *msg_out to a newly allocated error message, and return -1.

REFACTORING NOTE: Currently, this callback type is only used from inside config_dump(); later in our refactoring, it will be cleaned up and used more generally.

Definition at line 71 of file confparse.h.

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_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_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()

struct 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()

struct 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_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_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_list_deprecated_vars()

struct 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()

struct 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_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_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_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().

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