tor  0.4.1.0-alpha-dev
Data Structures | Functions | Variables
confparse.c File Reference
#include "core/or/or.h"
#include "app/config/confparse.h"
#include "feature/nodelist/routerset.h"
#include "lib/container/bitarray.h"
#include "lib/encoding/confline.h"

Go to the source code of this file.

Data Structures

struct  unit_table_t
 

Functions

static uint64_t config_parse_memunit (const char *s, int *ok)
 
static int config_parse_msec_interval (const char *s, int *ok)
 
static int config_parse_interval (const char *s, int *ok)
 
static void config_reset (const config_format_t *fmt, void *options, const config_var_t *var, int use_defaults)
 
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_tconfig_find_option_mutable (config_format_t *fmt, const char *key)
 
const config_var_tconfig_find_option (const config_format_t *fmt, const char *key)
 
static int config_count_options (const config_format_t *fmt)
 
static int config_assign_value (const config_format_t *fmt, void *options, config_line_t *c, char **msg)
 
static void config_mark_lists_fragile (const config_format_t *fmt, void *options)
 
void warn_deprecated_option (const char *what, const char *why)
 
static int config_assign_line (const config_format_t *fmt, void *options, config_line_t *c, unsigned flags, bitarray_t *options_seen, char **msg)
 
static void config_reset_line (const config_format_t *fmt, 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_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)
 
static void config_clear (const config_format_t *fmt, void *options, const config_var_t *var)
 
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)
 
static uint64_t config_parse_units (const char *val, struct unit_table_t *u, int *ok)
 

Variables

static struct unit_table_t memory_units []
 
static struct unit_table_t time_units []
 
static struct unit_table_t time_msec_units []
 

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.

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.

Definition at line 719 of file confparse.c.

References config_count_options().

Referenced by config_dup(), and options_trial_assign().

◆ config_assign_line()

static int config_assign_line ( const config_format_t fmt,
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 410 of file confparse.c.

◆ config_assign_value()

static int config_assign_value ( const config_format_t fmt,
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 161 of file confparse.c.

References CFG_AUTO_PORT, CONFIG_CHECK, config_find_option(), CONFIG_TYPE_CSV_INTERVAL, CONFIG_TYPE_INT, CONFIG_TYPE_PORT, CONFIG_TYPE_UINT, CONFIG_TYPE_UINT64, STRUCT_VAR_P, tor_asprintf(), tor_assert(), tor_parse_long(), tor_parse_uint64(), config_var_t::type, and config_var_t::var_offset.

◆ config_clear()

static void config_clear ( const config_format_t fmt,
void *  options,
const config_var_t var 
)
static

◆ config_count_options()

static int config_count_options ( const config_format_t fmt)
static

Return the number of option entries in fmt.

Definition at line 143 of file confparse.c.

References config_var_t::name, and config_format_t::vars.

Referenced by config_assign().

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

Definition at line 945 of file confparse.c.

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

◆ config_dup()

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

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

Definition at line 57 of file confparse.c.

References config_format_t::abbrevs.

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

Definition at line 87 of file confparse.c.

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

Definition at line 136 of file confparse.c.

References config_find_option_mutable().

Referenced by config_assign_value(), config_get_assigned_option(), config_reset_line(), option_get_canonical_name(), and option_is_recognized().

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

Definition at line 105 of file confparse.c.

References config_var_t::name, and config_format_t::vars.

Referenced by config_find_option().

◆ config_free_()

void config_free_ ( const config_format_t fmt,
void *  options 
)

Release storage held by options.

Definition at line 855 of file confparse.c.

References config_clear(), config_format_t::extra, config_var_t::name, STRUCT_VAR_P, tor_assert(), config_var_t::var_offset, and config_format_t::vars.

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

Definition at line 532 of file confparse.c.

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

Referenced by config_dup(), and option_get_assignment().

◆ config_init()

void config_init ( const config_format_t fmt,
void *  options 
)

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

Definition at line 926 of file confparse.c.

References CONFIG_CHECK, config_reset(), config_var_t::initvalue, config_var_t::name, and config_format_t::vars.

Referenced by config_dump(), and options_init().

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

Definition at line 878 of file confparse.c.

◆ config_mark_lists_fragile()

static void config_mark_lists_fragile ( const config_format_t fmt,
void *  options 
)
static

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

Definition at line 371 of file confparse.c.

References CONFIG_TYPE_LINELIST, CONFIG_TYPE_LINELIST_V, smartlist_t::list, config_var_t::name, STRUCT_VAR_P, tor_assert(), config_var_t::type, config_var_t::var_offset, and config_format_t::vars.

◆ config_new()

void* config_new ( const config_format_t fmt)

Allocate an empty configuration object of a given format type.

Definition at line 39 of file confparse.c.

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

◆ config_parse_interval()

static int config_parse_interval ( const char *  s,
int *  ok 
)
static

Parse a string in the format "number unit", where unit is a unit of time. On success, set *ok to true and return the number of seconds in the provided interval. Otherwise, set *ok to 0 and return -1.

Definition at line 1196 of file confparse.c.

References config_parse_units(), and time_units.

◆ config_parse_memunit()

static uint64_t config_parse_memunit ( const char *  s,
int *  ok 
)
static

Parse a string in the format "number unit", where unit is a unit of information (byte, KB, M, etc). On success, set *ok to true and return the number of bytes specified. Otherwise, set *ok to false and return 0.

Definition at line 1168 of file confparse.c.

References config_parse_units(), and memory_units.

◆ config_parse_msec_interval()

static int config_parse_msec_interval ( const char *  s,
int *  ok 
)
static

Parse a string in the format "number unit", where unit is a unit of time in milliseconds. On success, set *ok to true and return the number of milliseconds in the provided interval. Otherwise, set *ok to 0 and return -1.

Definition at line 1179 of file confparse.c.

References config_parse_units(), and time_msec_units.

◆ config_parse_units()

static uint64_t config_parse_units ( const char *  val,
struct unit_table_t u,
int *  ok 
)
static

Parse a string val containing a number, zero or more spaces, and an optional unit string. If the unit appears in the table u, then multiply the number by the unit multiplier. On success, set *ok to 1 and return this product. Otherwise, set *ok to 0.

Definition at line 1118 of file confparse.c.

References eat_whitespace(), unit_table_t::multiplier, tor_assert(), tor_parse_double(), tor_parse_uint64(), and unit_table_t::unit.

Referenced by config_parse_interval(), config_parse_memunit(), and config_parse_msec_interval().

◆ config_reset()

static void config_reset ( const config_format_t fmt,
void *  options,
const config_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 832 of file confparse.c.

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

Referenced by config_init(), and config_reset_line().

◆ config_reset_line()

static void config_reset_line ( const config_format_t fmt,
void *  options,
const char *  key,
int  use_defaults 
)
static

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

Definition at line 487 of file confparse.c.

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

◆ 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 504 of file confparse.c.

Variable Documentation

◆ memory_units

struct unit_table_t memory_units[]
static

Table to map the names of memory units to the number of bytes they contain.

Definition at line 1027 of file confparse.c.

Referenced by config_parse_memunit().

◆ time_msec_units

struct unit_table_t time_msec_units[]
static
Initial value:
= {
{ "", 1 },
{ "msec", 1 },
{ "millisecond", 1 },
{ "milliseconds", 1 },
{ "second", 1000 },
{ "seconds", 1000 },
{ "minute", 60*1000 },
{ "minutes", 60*1000 },
{ "hour", 60*60*1000 },
{ "hours", 60*60*1000 },
{ "day", 24*60*60*1000 },
{ "days", 24*60*60*1000 },
{ "week", 7*24*60*60*1000 },
{ "weeks", 7*24*60*60*1000 },
{ NULL, 0 },
}

Table to map the names of time units to the number of milliseconds they contain.

Definition at line 1093 of file confparse.c.

Referenced by config_parse_msec_interval().

◆ time_units

struct unit_table_t time_units[]
static
Initial value:
= {
{ "", 1 },
{ "second", 1 },
{ "seconds", 1 },
{ "minute", 60 },
{ "minutes", 60 },
{ "hour", 60*60 },
{ "hours", 60*60 },
{ "day", 24*60*60 },
{ "days", 24*60*60 },
{ "week", 7*24*60*60 },
{ "weeks", 7*24*60*60 },
{ "month", 2629728, },
{ "months", 2629728, },
{ NULL, 0 },
}

Table to map the names of time units to the number of seconds they contain.

Definition at line 1074 of file confparse.c.

Referenced by config_parse_interval().