src/or/confparse.h

   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-2013, The Tor Project, Inc. */
   5 /* See LICENSE for licensing information */
   6
   7 #ifndef TOR_CONFPARSE_H
   8 #define TOR_CONFPARSE_H
   9
  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
  17                              * "auto".  */
  18   CONFIG_TYPE_INTERVAL,     /**< A number of seconds, with optional units*/
  19   CONFIG_TYPE_MSEC_INTERVAL,/**< A number of milliseconds, with optional
  20                               * units */
  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.
  37                              */
  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. */
  41 } config_type_t;
  42
  43 /** An abbreviation for a configuration option allowed on the command line. */
  44 typedef struct config_abbrev_t {
  45   const char *abbreviated;
  46   const char *full;
  47   int commandline_only;
  48   int warn;
  49 } config_abbrev_t;
  50
  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 }
  54
  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
  59                        * value. */
  60   off_t var_offset; /**< Offset of the corresponding member of or_options_t. */
  61   const char *initvalue; /**< String (or null) describing initial value. */
  62 } config_var_t;
  63
  64 /** Represents an English description of a configuration variable; used when
  65  * generating configuration file comments. */
  66 typedef struct config_var_description_t {
  67   const char *name;
  68   const char *description;
  69 } config_var_description_t;
  70
  71 /** Type of a callback to validate whether a given configuration is
  72  * well-formed and consistent. See options_trial_assign() for documentation
  73  * of arguments. */
  74 typedef int (*validate_fn_t)(void*,void*,void*,int,char**);
  75
  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. */
  91   config_var_t *extra;
  92 } config_format_t;
  93
  94 /** Macro: assert that <b>cfg</b> has the right magic field for format
  95  * <b>fmt</b>. */
  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));        \
 100   STMT_END
 101
 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,
 107                                       const char *key);
 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,
 113                                           int escape_val);
 114 int config_is_same(const config_format_t *fmt,
 115                    const void *o1, const void *o2,
 116                    const char *name);
 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,
 123                   config_line_t *list,
 124                   int use_defaults, int clear_first, char **msg);
 125 config_var_t *config_find_option_mutable(config_format_t *fmt,
 126                                          const char *key);
 127 const config_var_t *config_find_option(const config_format_t *fmt,
 128                                        const char *key);
 129
 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,
 133                                  const char *option,
 134                                  int command_line, int warn_obsolete);
 135
 136 #endif
 137