diff options
Diffstat (limited to 'doc/conf.doc')
| -rw-r--r-- | doc/conf.doc | 89 |
1 files changed, 89 insertions, 0 deletions
diff --git a/doc/conf.doc b/doc/conf.doc new file mode 100644 index 0000000000..f12fe884f5 --- /dev/null +++ b/doc/conf.doc @@ -0,0 +1,89 @@ +The CONF library. + +The CONF library is a simple set of routines that can be used to configure +programs. It is a superset of the genenv() function with some extra +structure. + +The library consists of 5 functions. + +LHASH *CONF_load(LHASH *config,char *file); +This function is called to load in a configuration file. Multiple +configuration files can be loaded, with each subsequent 'load' overwriting +any already defined 'variables'. If there is an error, NULL is returned. +If config is NULL, a new LHASH structure is created and returned, otherwise +the new data in the 'file' is loaded into the 'config' structure. + +void CONF_free(LHASH *config); +This function free()s the data in config. + +char *CONF_get_string(LHASH *config,char *section,char *name); +This function returns the string found in 'config' that corresponds to the +'section' and 'name' specified. Classes and the naming system used will be +discussed later in this document. If the variable is not defined, an NULL +is returned. + +long CONF_get_long(LHASH *config,char *section, char *name); +This function is the same as CONF_get_string() except that it converts the +string to an long and returns it. If variable is not a number or the +variable does not exist, 0 is returned. This is a little problematic but I +don't know of a simple way around it. + +STACK *CONF_get_section(LHASH *config, char *section); +This function returns a 'stack' of CONF_VALUE items that are all the +items defined in a particular section. DO NOT free() any of the +variable returned. They will disappear when CONF_free() is called. + +The 'lookup' model. +The configuration file is divided into 'sections'. Each section is started by +a line of the form '[ section ]'. All subsequent variable definitions are +of this section. A variable definition is a simple alpha-numeric name +followed by an '=' and then the data. A section or variable name can be +described by a regular expression of the following form '[A-Za-z0-9_]+'. +The value of the variable is the text after the '=' until the end of the +line, stripped of leading and trailing white space. +At this point I should mention that a '#' is a comment character, \ is the +escape character, and all three types of quote can be used to stop any +special interpretation of the data. +Now when the data is being loaded, variable expansion can occur. This is +done by expanding any $NAME sequences into the value represented by the +variable NAME. If the variable is not in the current section, the different +section can be specified by using the $SECTION::NAME form. The ${NAME} form +also works and is very useful for expanding variables inside strings. + +When a variable is looked up, there are 2 special section. 'default', which +is the initial section, and 'ENV' which is the processes environment +variables (accessed via getenv()). When a variable is looked up, it is +first 'matched' with it's section (if one was specified), if this fails, the +'default' section is matched. +If the 'lhash' variable passed was NULL, the environment is searched. + +Now why do we bother with sections? So we can have multiple programs using +the same configuration file, or multiple instances of the same program +using different variables. It also provides a nice mechanism to override +the processes environment variables (eg ENV::HOME=/tmp). If there is a +program specific variable missing, we can have default values. +Multiple configuration files can be loaded, with each new value clearing +any predefined values. A system config file can provide 'default' values, +and application/usr specific files can provide overriding values. + +Examples + +# This is a simple example +SSLEAY_HOME = /usr/local/ssl +ENV::PATH = $SSLEAY_HOME/bin:$PATH # override my path + +[X509] +cert_dir = $SSLEAY_HOME/certs # /usr/local/ssl/certs + +[SSL] +CIPHER = DES-EDE-MD5:RC4-MD5 +USER_CERT = $HOME/${USER}di'r 5' # /home/eay/eaydir 5 +USER_CERT = $HOME/\${USER}di\'r # /home/eay/${USER}di'r +USER_CERT = "$HOME/${US"ER}di\'r # $HOME/${USER}di'r + +TEST = 1234\ +5678\ +9ab # TEST=123456789ab +TTT = 1234\n\n # TTT=1234<nl><nl> + + |