diff options
Diffstat (limited to 'gconfig.txt')
| -rw-r--r-- | gconfig.txt | 160 |
1 files changed, 0 insertions, 160 deletions
diff --git a/gconfig.txt b/gconfig.txt deleted file mode 100644 index ec77545..0000000 --- a/gconfig.txt +++ /dev/null @@ -1,160 +0,0 @@ -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. |