confmgt.h File Reference

Header for confmgt.c. More...

#include "lib/conf/conftypes.h"
#include "lib/conf/confmacros.h"
#include "lib/testsupport/testsupport.h"

Go to the source code of this file.

Macros
#define	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)
#define	CFG_EQ_INT(a, b, opt)
#define	CFG_EQ_STRING(a, b, opt)
#define	CFG_EQ_SMARTLIST(a, b, opt)
#define	CFG_EQ_LINELIST(a, b, opt)
#define	CFG_EQ_ROUTERSET(a, b, opt)

Enumerations
enum	validation_status_t {   VSTAT_PRE_NORMALIZE_ERR = -5 , VSTAT_VALIDATE_ERR = -4 , VSTAT_LEGACY_ERR = -3 , VSTAT_TRANSITION_ERR = -2 ,   VSTAT_POST_NORMALIZE_ERR = -1 , VSTAT_OK = 0 }

Functions
config_mgr_t *	config_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_t *	config_mgr_list_vars (const config_mgr_t *mgr)
struct smartlist_t *	config_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_t *	config_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_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)
validation_status_t	config_validate (const config_mgr_t *mgr, const void *old_options, void *options, char **msg_out)
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)
void	config_check_toplevel_magic (const config_mgr_t *mgr, const void *object)
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)
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)

Detailed Description

Header for confmgt.c.

Definition in file confmgt.h.

Macro Definition Documentation

CAL_CLEAR_FIRST

#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 59 of file confmgt.h.

Referenced by config_assign(), config_assign_line(), and control_setconf_helper().

CAL_USE_DEFAULTS

#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 50 of file confmgt.h.

Referenced by config_assign(), config_assign_line(), and control_setconf_helper().

CAL_WARN_DEPRECATIONS

#define CAL_WARN_DEPRECATIONS   (1u<<2)

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

Definition at line 63 of file confmgt.h.

Referenced by config_assign_line(), options_init(), and options_init_from_string().

CFG_EQ_BOOL

#define CFG_EQ_BOOL	(		a,
			b,
			opt )

Value:

((a)->opt == (b)->opt)

Definition at line 119 of file confmgt.h.

CFG_EQ_INT

#define CFG_EQ_INT	(		a,
			b,
			opt )

Value:

((a)->opt == (b)->opt)

Definition at line 120 of file confmgt.h.

CFG_EQ_LINELIST

#define CFG_EQ_LINELIST	(		a,
			b,
			opt )

Value:

config_lines_eq((a)->opt, (b)->opt)

Definition at line 123 of file confmgt.h.

CFG_EQ_ROUTERSET

#define CFG_EQ_ROUTERSET	(		a,
			b,
			opt )

Value:

routerset_equal((a)->opt, (b)->opt)

Definition at line 124 of file confmgt.h.

CFG_EQ_SMARTLIST

#define CFG_EQ_SMARTLIST	(		a,
			b,
			opt )

Value:

smartlist_strings_eq((a)->opt, (b)->opt)

Definition at line 122 of file confmgt.h.

CFG_EQ_STRING

#define CFG_EQ_STRING	(		a,
			b,
			opt )

Value:

(!strcmp_opt((a)->opt, (b)->opt))

Definition at line 121 of file confmgt.h.

config_free

#define config_free	(		mgr,
			options )

Value:

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

Definition at line 67 of file confmgt.h.

config_mgr_free

#define config_mgr_free

(

mgr

)

Value:

  FREE_AND_NULL(config_mgr_t, config_mgr_free_, (mgr))

Definition at line 33 of file confmgt.h.

Enumeration Type Documentation

validation_status_t

enum validation_status_t

An enumeration to report which validation step failed.

Definition at line 83 of file confmgt.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 937 of file confmgt.c.

Referenced by config_service(), disk_state_load_from_disk_impl(), hs_ob_parse_config_file(), options_init(), options_init_from_string(), options_trial_assign(), and or_state_load().

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 1393 of file confmgt.c.

config_check_toplevel_magic()

void config_check_toplevel_magic	(	const config_mgr_t *	mgr,
		const void *	object )

Check the magic number on object to make sure it's a valid toplevel object, created with mgr. Exit with an assertion if it isn't.

Definition at line 347 of file confmgt.c.

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 1314 of file confmgt.c.

Referenced by disk_state_save_to_disk(), options_dump(), and or_state_save().

config_dup()

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_init_from_string(), and options_trial_assign().

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 415 of file confmgt.c.

Referenced by config_assign(), config_find_option_name(), and config_parse_commandline().

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 442 of file confmgt.c.

Referenced by config_assign_line().

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 513 of file confmgt.c.

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 1025 of file confmgt.c.

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 843 of file confmgt.c.

Referenced by config_dump(), config_get_changes(), option_get_assignment(), and warn_about_relative_paths().

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 1096 of file confmgt.c.

Referenced by set_options().

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 1158 of file confmgt.c.

Referenced by config_dump(), disk_state_new(), hs_opts_new(), ob_option_new(), 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 1070 of file confmgt.c.

Referenced by config_dump().

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 216 of file confmgt.c.

Referenced by subsystems_register_options_formats(), and subsystems_register_state_formats().

config_mgr_free_()

void config_mgr_free_

(

config_mgr_t *

mgr

)

Release all storage held in mgr

Definition at line 302 of file confmgt.c.

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 285 of file confmgt.c.

Referenced by get_hs_opts_mgr(), get_options_mgr(), get_srs_mgr(), and get_state_mgr().

config_mgr_get_obj()

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_assigned_option(), config_get_changes(), and config_is_same().

config_mgr_get_obj_mutable()

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(), config_mgr_get_obj(), subsystems_flush_state(), subsystems_set_options(), and subsystems_set_state().

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 333 of file confmgt.c.

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 319 of file confmgt.c.

Referenced by getinfo_helper_config(), list_torrc_options(), and warn_about_relative_paths().

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 confmgt.c.

Referenced by get_hs_opts_mgr(), get_options_mgr(), get_srs_mgr(), and get_state_mgr().

config_new()

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

config_validate()

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(), config_service(), options_validate_and_set(), and or_state_validate().

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 619 of file confmgt.c.

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 558 of file confmgt.c.

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 692 of file confmgt.c.

Referenced by config_assign_line().