commit f0c1f96adcc049c49f7784645a5b197c8b3e44af Author: Nick Mathewson <nickm@torproject.org> Date: Wed Aug 28 12:23:36 2019 -0400 Document configuration type definition functions for routerset_t These functions are all used to implement the ROUTERSET_type_defn object, which maps strings to and from routerset_t configuration variables for the configuration module. --- src/feature/nodelist/routerset.c | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/src/feature/nodelist/routerset.c b/src/feature/nodelist/routerset.c index 12965ad0d..0b8916780 100644 --- a/src/feature/nodelist/routerset.c +++ b/src/feature/nodelist/routerset.c @@ -466,6 +466,13 @@ routerset_free_(routerset_t *routerset) tor_free(routerset); } +/** + * config helper: parse a routerset-typed variable. + * + * Takes as input as a single line in <b>line</b>; writes its results into a + * routerset_t** passed as <b>target</b>. On success return 0; on failure + * return -1 and store an error message into *<b>errmsg</b>. + **/ static int routerset_kv_parse(void *target, const config_line_t *line, char **errmsg, const void *params) @@ -488,6 +495,12 @@ routerset_kv_parse(void *target, const config_line_t *line, char **errmsg, } } +/** + * config helper: encode a routerset-typed variable. + * + * Return a newly allocated string containing the value of the + * routerset_t** passed as <b>value</b>. + */ static char * routerset_encode(const void *value, const void *params) { @@ -496,6 +509,11 @@ routerset_encode(const void *value, const void *params) return routerset_to_string(*p); } +/** + * config helper: free and clear a routerset-typed variable. + * + * Clear the routerset_t** passed as <b>value</b>. + */ static void routerset_clear(void *value, const void *params) { @@ -504,6 +522,13 @@ routerset_clear(void *value, const void *params) routerset_free(*p); // sets *p to NULL. } +/** + * config helper: copy a routerset-typed variable. + * + * Takes it input from a routerset_t** in <b>src</b>; writes its output to a + * routerset_t** in <b>dest</b>. Returns 0 on success, -1 on (impossible) + * failure. + **/ static int routerset_copy(void *dest, const void *src, const void *params) { @@ -518,6 +543,9 @@ routerset_copy(void *dest, const void *src, const void *params) return 0; } +/** + * Function table to implement a routerset_t-based configuration type. + **/ static const var_type_fns_t routerset_type_fns = { .kv_parse = routerset_kv_parse, .encode = routerset_encode, @@ -525,6 +553,15 @@ static const var_type_fns_t routerset_type_fns = { .copy = routerset_copy }; +/** + * Definition of a routerset_t-based configuration type. + * + * Values are mapped to and from strings using the format defined in + * routerset_parse(): nicknames, IP address patterns, and fingerprints--with + * optional space, separated by commas. + * + * Empty sets are represented as NULL. + **/ const var_type_def_t ROUTERSET_type_defn = { .name = "RouterList", .fns = &routerset_type_fns