+++ /dev/null
-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.
projects / libradsec.git / blobdiff