diff options
Diffstat (limited to 'gconfig.txt')
| -rw-r--r-- | gconfig.txt | 160 |
1 files changed, 160 insertions, 0 deletions
diff --git a/gconfig.txt b/gconfig.txt new file mode 100644 index 0000000..ec77545 --- /dev/null +++ b/gconfig.txt @@ -0,0 +1,160 @@ +Documentation for gconfig + +gconfig is a configuration file parser. It is generic in the sense that it can +be used for different applications that need different configuration keywords +and value. There is however a fixed syntax. + +The basic syntax is + +option-name value +or +option-name = value + +where white space is used as delimiters, where you can have any amount of +whitespace (spaces and tabs) where there is a space above. option-name cannot +contain spaces. A value can contain spaces if the value is quoted. E.g. + +option-name = "option value" + +There is a special keyword "include" used for including config files. +Anywhere in a config file one can write "include filespec". At that +point the entire content of a file pointed to by filespec will be +inserted. When the end of the file is read, the config parser will +continue with whatever is after include. "filespec" can use UNIX +shell type globbing, so you may do e.g. "include /etc/gconf.d/*" to +include everything in that directory. This will behave exactly like +including each of the files separately (in alphabetic order). + +In addition to this, one may also group options together into +blocks, where blocks also have names. + +A block has the syntax + +type name { + option-name value + option-name value + ... +} + +The application specifies which block types are valid, and which +option-names and syntaxes can be used for each of the types. + +The available option syntaxes (or types) are String, Integer and +Boolean. + +Usually the same option-name cannot be repeated (unless in different +blocks). For Strings one can specify whether it is allowed or not. +Also, for strings one can use hex notation for bytes. This works +similar to URL hex escaping. E.g. a space can be written as "%20". + +radsecproxy uses gconfig and shows what is possible. Here is an +example extracted from getmainconfig() from radsecproxy. + +struct gconffile *cfs; +cfs = openconfigfile(configfile); + if (!getgenericconfig(&cfs, NULL, + "ListenUDP", CONF_MSTR, &listenudp, + "LogDestination", CONF_STR, &logdestination, + "LogLevel", CONF_LINT, &loglevel, + "LoopPrevention", CONF_BLN, &loopprevention, + "Client", CONF_CBK, confclient_cb, NULL, + NULL + )) + debugx(1, DBG_ERR, "configuration error"); /* exit */ + /* parsing successful, continue normal operations */ + +The arguments to getgenericconfig are as follows. First there is a +gconffile struct, this is normally a single file, but as we discuss later, +it can also be a list of files (or data). The second parameter should be +NULL when not in a block, or the block name if inside one. This is only +used for logging. + +After this one lists all the legal option and block names that are allowed. +For each option one specifies a name followed by a syntax type and a pointer to +the variable that will hold the value. The syntax types are CONF_STR for a +string, CONF_MSTR for string when the option can be used multiple times, +CONF_LINT for Integer (long int), CONF_BLN for Boolean ("on" or "off"). For +blocks one uses CONF_CBK followed by a callback function for handling the +block, and a pointer to userdata that can be passed to the callback. Normally +this would just be set to NULL. + +We will now discuss each of the syntax types and blocks in more detail. + +CONF_STR: +This is used for strings. The value argument must be of type "char **". If +the option is found in the config, it will allocate memory for a null-terminated +copy of the string and return a pointer to this. The value argument is not +modified if the option is not used. In the example above, one might do +"char *logdestination = NULL". One then uses &logdestination for the +argument, and can check for NULL to see whether the option was present. + +CONF_MSTR: +This is used for strings when the option can be used multiple times. It +will return an array of strings in the order they are found in the config. +The value argument must be of type "char ***". One might do +"char **listenudp = NULL", and use &listenudp for the argument. Memory will +be allocated for the array and the strings if the option is used. If no +options are found, the value is unchanged. If there is at least one value, +one will get an array of strings, and the last element of the array will be +set to NULL. + +CONF_LINT: +The option value argument must be of type "long int *". If the option is +present, the value will be set, else it will not be modified. + +CONF_BLN: +The option value argument must be of type "uint8_t *". It is set to 0 or 1 +for "off" or "on" resp. It is only modified if the option is found. + +CONF_CBK: +This is a block where one uses a call back. Here is an example callback: + +int confclient_cb(struct gconffile **cf, void *arg, char *block, char *opt, char + *val) { + char *type = NULL, *host = NULL; + debug(DBG_DBG, "confclient_cb called for %s", block); + if (!getgenericconfig(cf, block, + "type", CONF_STR, &type, + "host", CONF_STR, &host, + NULL + )) + debugx(1, DBG_ERR, "configuration error"); /* exit */ + /* parsing successful, continue normal operations */ + +Here cf is the list of config files we're using, arg is a pointer to +userdata (the parameter after the name of the callback function, often +this is just set to NULL). opt is the type of block, in this case it will +be set to "client". val is the value of the block. E.g. if the config said + +client example { + type udp + host 1.2.3.4 +} + +then val will be set to "example". The string block is set to +"client example" (opt val) and is normally just used for logging. +Note that the opt, val and optval parameters to the callback will all be +freed when the callback function exits. + +The gconffile struct can hold a list of config files. Typically one would +just use cfs = openconfigfile(configfile) as above. But one can use any of +the ones below. It can be used to create a new struct (a pointer to NULL), +or a pointer to an existing struct where new files are pushed (as a stack). +The latest pushed is used first, when that is used it continues reading +from the next. + +int pushgconfdata(struct gconffile **cf, const char *data); +This can be used to read config stored in memory + +FILE *pushgconfpath(struct gconffile **cf, const char *path); +Here one specifies a file path (no globbing) + +FILE *pushgconfpaths(struct gconffile **cf, const char *path); +Here one specifies a filespec with globbing. In case of multiple files, +they are pushed in reverse alphabetical order so that the alphabetically +first file is read first. + +FILE *pushgconffile(struct gconffile **cf, FILE *file, const char *description); +This can be used for reading config from an already open file descriptor. + +For a complete example, see radsecproxy. |