gconfig.txt

   1 Documentation for gconfig
   2
   3 gconfig is a configuration file parser. It is generic in the sense that it can
   4 be used for different applications that need different configuration keywords
   5 and value. There is however a fixed syntax.
   6
   7 The basic syntax is
   8
   9 option-name value
  10 or
  11 option-name = value
  12
  13 where white space is used as delimiters, where you can have any amount of
  14 whitespace (spaces and tabs) where there is a space above. option-name cannot
  15 contain spaces. A value can contain spaces if the value is quoted. E.g.
  16
  17 option-name = "option value"
  18
  19 There is a special keyword "include" used for including config files.
  20 Anywhere in a config file one can write "include filespec". At that
  21 point the entire content of a file pointed to by filespec will be
  22 inserted. When the end of the file is read, the config parser will
  23 continue with whatever is after include. "filespec" can use UNIX
  24 shell type globbing, so you may do e.g. "include /etc/gconf.d/*" to
  25 include everything in that directory. This will behave exactly like
  26 including each of the files separately (in alphabetic order).
  27
  28 In addition to this, one may also group options together into
  29 blocks, where blocks also have names.
  30
  31 A block has the syntax
  32
  33 type name {
  34      option-name value
  35      option-name value
  36      ...
  37 }
  38
  39 The application specifies which block types are valid, and which
  40 option-names and syntaxes can be used for each of the types.
  41
  42 The available option syntaxes (or types) are String, Integer and
  43 Boolean.
  44
  45 Usually the same option-name cannot be repeated (unless in different
  46 blocks). For Strings one can specify whether it is allowed or not.
  47 Also, for strings one can use hex notation for bytes. This works
  48 similar to URL hex escaping. E.g. a space can be written as "%20".
  49
  50 radsecproxy uses gconfig and shows what is possible. Here is an
  51 example extracted from getmainconfig() from radsecproxy.
  52
  53 struct gconffile *cfs;
  54 cfs = openconfigfile(configfile);
  55     if (!getgenericconfig(&cfs, NULL,
  56                           "ListenUDP", CONF_MSTR, &listenudp,
  57                           "LogDestination", CONF_STR, &logdestination,
  58                           "LogLevel", CONF_LINT, &loglevel,
  59                           "LoopPrevention", CONF_BLN, &loopprevention,
  60                           "Client", CONF_CBK, confclient_cb, NULL,
  61                           NULL
  62                           ))
  63         debugx(1, DBG_ERR, "configuration error"); /* exit */
  64     /* parsing successful, continue normal operations */
  65
  66 The arguments to getgenericconfig are as follows. First there is a
  67 gconffile struct, this is normally a single file, but as we discuss later,
  68 it can also be a list of files (or data). The second parameter should be
  69 NULL when not in a block, or the block name if inside one. This is only
  70 used for logging.
  71
  72 After this one lists all the legal option and block names that are allowed.
  73 For each option one specifies a name followed by a syntax type and a pointer to
  74 the variable that will hold the value. The syntax types are CONF_STR for a
  75 string, CONF_MSTR for string when the option can be used multiple times,
  76 CONF_LINT for Integer (long int), CONF_BLN for Boolean ("on" or "off"). For
  77 blocks one uses CONF_CBK followed by a callback function for handling the
  78 block, and a pointer to userdata that can be passed to the callback. Normally
  79 this would just be set to NULL.
  80
  81 We will now discuss each of the syntax types and blocks in more detail.
  82
  83 CONF_STR:
  84 This is used for strings. The value argument must be of type "char **". If
  85 the option is found in the config, it will allocate memory for a null-terminated
  86 copy of the string and return a pointer to this. The value argument is not
  87 modified if the option is not used. In the example above, one might do
  88 "char *logdestination = NULL". One then uses &logdestination for the
  89 argument, and can check for NULL to see whether the option was present.
  90
  91 CONF_MSTR:
  92 This is used for strings when the option can be used multiple times. It
  93 will return an array of strings in the order they are found in the config.
  94 The value argument must be of type "char ***". One might do
  95 "char **listenudp = NULL", and use &listenudp for the argument. Memory will
  96 be allocated for the array and the strings if the option is used. If no
  97 options are found, the value is unchanged. If there is at least one value,
  98 one will get an array of strings, and the last element of the array will be
  99 set to NULL.
 100
 101 CONF_LINT:
 102 The option value argument must be of type "long int *". If the option is
 103 present, the value will be set, else it will not be modified.
 104
 105 CONF_BLN:
 106 The option value argument must be of type "uint8_t *". It is set to 0 or 1
 107 for "off" or "on" resp. It is only modified if the option is found.
 108
 109 CONF_CBK:
 110 This is a block where one uses a call back. Here is an example callback:
 111
 112 int confclient_cb(struct gconffile **cf, void *arg, char *block, char *opt, char
 113  *val) {
 114     char *type = NULL, *host = NULL;
 115     debug(DBG_DBG, "confclient_cb called for %s", block);
 116     if (!getgenericconfig(cf, block,
 117                           "type", CONF_STR, &type,
 118                           "host", CONF_STR, &host,
 119                           NULL
 120                           ))
 121         debugx(1, DBG_ERR, "configuration error"); /* exit */
 122     /* parsing successful, continue normal operations */
 123
 124 Here cf is the list of config files we're using, arg is a pointer to
 125 userdata (the parameter after the name of the callback function, often
 126 this is just set to NULL). opt is the type of block, in this case it will
 127 be set to "client". val is the value of the block. E.g. if the config said
 128
 129 client example {
 130         type udp
 131         host 1.2.3.4
 132 }
 133
 134 then val will be set to "example". The string block is set to
 135 "client example" (opt val) and is normally just used for logging.
 136 Note that the opt, val and optval parameters to the callback will all be
 137 freed when the callback function exits.
 138
 139 The gconffile struct can hold a list of config files. Typically one would
 140 just use cfs = openconfigfile(configfile) as above. But one can use any of
 141 the ones below. It can be used to create a new struct (a pointer to NULL),
 142 or a pointer to an existing struct where new files are pushed (as a stack).
 143 The latest pushed is used first, when that is used it continues reading
 144 from the next.
 145
 146 int pushgconfdata(struct gconffile **cf, const char *data);
 147 This can be used to read config stored in memory
 148
 149 FILE *pushgconfpath(struct gconffile **cf, const char *path);
 150 Here one specifies a file path (no globbing)
 151
 152 FILE *pushgconfpaths(struct gconffile **cf, const char *path);
 153 Here one specifies a filespec with globbing. In case of multiple files,
 154 they are pushed in reverse alphabetical order so that the alphabetically
 155 first file is read first.
 156
 157 FILE *pushgconffile(struct gconffile **cf, FILE *file, const char *description);
 158 This can be used for reading config from an already open file descriptor.
 159
 160 For a complete example, see radsecproxy.