1 /* Copyright (c) 2001 Matej Pfajfar.
2 * Copyright (c) 2001-2004, Roger Dingledine.
3 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
4 * Copyright (c) 2007-2016, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
7 #ifndef TOR_CONFPARSE_H
8 #define TOR_CONFPARSE_H
10 /** Enumeration of types which option values can take */
11 typedef enum config_type_t
{
12 CONFIG_TYPE_STRING
= 0, /**< An arbitrary string. */
13 CONFIG_TYPE_FILENAME
, /**< A filename: some prefixes get expanded. */
14 CONFIG_TYPE_UINT
, /**< A non-negative integer less than MAX_INT */
15 CONFIG_TYPE_INT
, /**< Any integer. */
16 CONFIG_TYPE_PORT
, /**< A port from 1...65535, 0 for "not set", or
18 CONFIG_TYPE_INTERVAL
, /**< A number of seconds, with optional units*/
19 CONFIG_TYPE_MSEC_INTERVAL
,/**< A number of milliseconds, with optional
21 CONFIG_TYPE_MEMUNIT
, /**< A number of bytes, with optional units*/
22 CONFIG_TYPE_DOUBLE
, /**< A floating-point value */
23 CONFIG_TYPE_BOOL
, /**< A boolean value, expressed as 0 or 1. */
24 CONFIG_TYPE_AUTOBOOL
, /**< A boolean+auto value, expressed 0 for false,
25 * 1 for true, and -1 for auto */
26 CONFIG_TYPE_ISOTIME
, /**< An ISO-formatted time relative to UTC. */
27 CONFIG_TYPE_CSV
, /**< A list of strings, separated by commas and
28 * optional whitespace. */
29 CONFIG_TYPE_CSV_INTERVAL
, /**< A list of strings, separated by commas and
30 * optional whitespace, representing intervals in
31 * seconds, with optional units */
32 CONFIG_TYPE_LINELIST
, /**< Uninterpreted config lines */
33 CONFIG_TYPE_LINELIST_S
, /**< Uninterpreted, context-sensitive config lines,
34 * mixed with other keywords. */
35 CONFIG_TYPE_LINELIST_V
, /**< Catch-all "virtual" option to summarize
36 * context-sensitive config lines when fetching.
38 CONFIG_TYPE_ROUTERSET
, /**< A list of router names, addrs, and fps,
39 * parsed into a routerset_t. */
40 CONFIG_TYPE_OBSOLETE
, /**< Obsolete (ignored) option. */
43 /** An abbreviation for a configuration option allowed on the command line. */
44 typedef struct config_abbrev_t
{
45 const char *abbreviated
;
51 /* Handy macro for declaring "In the config file or on the command line,
52 * you can abbreviate <b>tok</b>s as <b>tok</b>". */
53 #define PLURAL(tok) { #tok, #tok "s", 0, 0 }
55 /** A variable allowed in the configuration file or on the command line. */
56 typedef struct config_var_t
{
57 const char *name
; /**< The full keyword (case insensitive). */
58 config_type_t type
; /**< How to interpret the type and turn it into a
60 off_t var_offset
; /**< Offset of the corresponding member of or_options_t. */
61 const char *initvalue
; /**< String (or null) describing initial value. */
64 /** Represents an English description of a configuration variable; used when
65 * generating configuration file comments. */
66 typedef struct config_var_description_t
{
68 const char *description
;
69 } config_var_description_t
;
71 /** Type of a callback to validate whether a given configuration is
72 * well-formed and consistent. See options_trial_assign() for documentation
74 typedef int (*validate_fn_t
)(void*,void*,void*,int,char**);
76 /** Information on the keys, value types, key-to-struct-member mappings,
77 * variable descriptions, validation functions, and abbreviations for a
78 * configuration or storage format. */
79 typedef struct config_format_t
{
80 size_t size
; /**< Size of the struct that everything gets parsed into. */
81 uint32_t magic
; /**< Required 'magic value' to make sure we have a struct
82 * of the right type. */
83 off_t magic_offset
; /**< Offset of the magic value within the struct. */
84 config_abbrev_t
*abbrevs
; /**< List of abbreviations that we expand when
85 * parsing this format. */
86 config_var_t
*vars
; /**< List of variables we recognize, their default
87 * values, and where we stick them in the structure. */
88 validate_fn_t validate_fn
; /**< Function to validate config. */
89 /** If present, extra is a LINELIST variable for unrecognized
90 * lines. Otherwise, unrecognized lines are an error. */
94 /** Macro: assert that <b>cfg</b> has the right magic field for format
96 #define CONFIG_CHECK(fmt, cfg) STMT_BEGIN \
97 tor_assert(fmt && cfg); \
98 tor_assert((fmt)->magic == \
99 *(uint32_t*)STRUCT_VAR_P(cfg,fmt->magic_offset)); \
102 void *config_new(const config_format_t
*fmt
);
103 void config_line_append(config_line_t
**lst
,
104 const char *key
, const char *val
);
105 config_line_t
*config_lines_dup(const config_line_t
*inp
);
106 const config_line_t
*config_line_find(const config_line_t
*lines
,
108 void config_free(const config_format_t
*fmt
, void *options
);
109 int config_lines_eq(config_line_t
*a
, config_line_t
*b
);
110 int config_count_key(const config_line_t
*a
, const char *key
);
111 config_line_t
*config_get_assigned_option(const config_format_t
*fmt
,
112 const void *options
, const char *key
,
114 int config_is_same(const config_format_t
*fmt
,
115 const void *o1
, const void *o2
,
117 void config_init(const config_format_t
*fmt
, void *options
);
118 void *config_dup(const config_format_t
*fmt
, const void *old
);
119 char *config_dump(const config_format_t
*fmt
, const void *default_options
,
120 const void *options
, int minimal
,
121 int comment_defaults
);
122 int config_assign(const config_format_t
*fmt
, void *options
,
124 int use_defaults
, int clear_first
, char **msg
);
125 config_var_t
*config_find_option_mutable(config_format_t
*fmt
,
127 const config_var_t
*config_find_option(const config_format_t
*fmt
,
130 int config_get_lines(const char *string
, config_line_t
**result
, int extended
);
131 void config_free_lines(config_line_t
*front
);
132 const char *config_expand_abbrev(const config_format_t
*fmt
,
134 int command_line
, int warn_obsolete
);