confparse.c File Reference

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

#include "or.h"
#include "confparse.h"
#include "routerset.h"

Include dependency graph for confparse.c:

Data Structures
struct	unit_table_t

Functions
void *	config_new (const config_format_t *fmt)
const char *	config_expand_abbrev (const config_format_t *fmt, const char *option, int command_line, int warn_obsolete)
const char *	config_find_deprecation (const config_format_t *fmt, const char *key)
config_var_t *	config_find_option_mutable (config_format_t *fmt, const char *key)
const config_var_t *	config_find_option (const config_format_t *fmt, const char *key)
void	warn_deprecated_option (const char *what, const char *why)
config_line_t *	config_get_assigned_option (const config_format_t *fmt, const void *options, const char *key, int escape_val)
int	config_assign (const config_format_t *fmt, void *options, config_line_t *list, unsigned config_assign_flags, char **msg)
void	config_free_ (const config_format_t *fmt, void *options)
int	config_is_same (const config_format_t *fmt, const void *o1, const void *o2, const char *name)
void *	config_dup (const config_format_t *fmt, const void *old)
void	config_init (const config_format_t *fmt, void *options)
char *	config_dump (const config_format_t *fmt, const void *default_options, const void *options, int minimal, int comment_defaults)

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.

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.

Here is the caller graph for this function:

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.

Here is the call graph for this function:

config_dup()

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

Copy storage held by old into a new or_options_t and return it.

Here is the call graph for this function:

Here is the caller graph for this function:

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.

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.

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.

Here is the call graph for this function:

Here is the caller graph for this function:

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.

Here is the caller graph for this function:

config_free_()

void config_free_	(	const config_format_t *	fmt,
		void *	options
	)

Release storage held by options.

config_get_assigned_option()

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.

Here is the call graph for this function:

Here is the caller graph for this function:

config_init()

void config_init	(	const config_format_t *	fmt,
		void *	options
	)

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

Here is the caller graph for this function:

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.

config_new()

void* config_new

(

const config_format_t *

fmt

)

Allocate an empty configuration object of a given format type.

Here is the caller graph for this function: