doc/conf.doc

   1 The CONF library.
   2
   3 The CONF library is a simple set of routines that can be used to configure
   4 programs.  It is a superset of the genenv() function with some extra
   5 structure.
   6
   7 The library consists of 5 functions.
   8
   9 LHASH *CONF_load(LHASH *config,char *file);
  10 This function is called to load in a configuration file.  Multiple
  11 configuration files can be loaded, with each subsequent 'load' overwriting
  12 any already defined 'variables'.  If there is an error, NULL is returned.
  13 If config is NULL, a new LHASH structure is created and returned, otherwise
  14 the new data in the 'file' is loaded into the 'config' structure.
  15
  16 void CONF_free(LHASH *config);
  17 This function free()s the data in config.
  18
  19 char *CONF_get_string(LHASH *config,char *section,char *name);
  20 This function returns the string found in 'config' that corresponds to the
  21 'section' and 'name' specified.  Classes and the naming system used will be
  22 discussed later in this document.  If the variable is not defined, an NULL
  23 is returned.
  24
  25 long CONF_get_long(LHASH *config,char *section, char *name);
  26 This function is the same as CONF_get_string() except that it converts the
  27 string to an long and returns it.  If variable is not a number or the
  28 variable does not exist, 0 is returned.  This is a little problematic but I
  29 don't know of a simple way around it.
  30
  31 STACK *CONF_get_section(LHASH *config, char *section);
  32 This function returns a 'stack' of CONF_VALUE items that are all the
  33 items defined in a particular section.  DO NOT free() any of the
  34 variable returned.  They will disappear when CONF_free() is called.
  35
  36 The 'lookup' model.
  37 The configuration file is divided into 'sections'.  Each section is started by
  38 a line of the form '[ section ]'.  All subsequent variable definitions are
  39 of this section.  A variable definition is a simple alpha-numeric name
  40 followed by an '=' and then the data.  A section or variable name can be
  41 described by a regular expression of the following form '[A-Za-z0-9_]+'.
  42 The value of the variable is the text after the '=' until the end of the
  43 line, stripped of leading and trailing white space.
  44 At this point I should mention that a '#' is a comment character, \ is the
  45 escape character, and all three types of quote can be used to stop any
  46 special interpretation of the data.
  47 Now when the data is being loaded, variable expansion can occur.  This is
  48 done by expanding any $NAME sequences into the value represented by the
  49 variable NAME.  If the variable is not in the current section, the different
  50 section can be specified by using the $SECTION::NAME form.  The ${NAME} form
  51 also works and is very useful for expanding variables inside strings.
  52
  53 When a variable is looked up, there are 2 special section. 'default', which
  54 is the initial section, and 'ENV' which is the processes environment
  55 variables (accessed via getenv()).  When a variable is looked up, it is
  56 first 'matched' with it's section (if one was specified), if this fails, the
  57 'default' section is matched.
  58 If the 'lhash' variable passed was NULL, the environment is searched.
  59
  60 Now why do we bother with sections?  So we can have multiple programs using
  61 the same configuration file, or multiple instances of the same program
  62 using different variables.  It also provides a nice mechanism to override
  63 the processes environment variables (eg ENV::HOME=/tmp).  If there is a
  64 program specific variable missing, we can have default values.
  65 Multiple configuration files can be loaded, with each new value clearing
  66 any predefined values.  A system config file can provide 'default' values,
  67 and application/usr specific files can provide overriding values.
  68
  69 Examples
  70
  71 # This is a simple example
  72 SSLEAY_HOME     = /usr/local/ssl
  73 ENV::PATH       = $SSLEAY_HOME/bin:$PATH        # override my path
  74
  75 [X509]
  76 cert_dir        = $SSLEAY_HOME/certs    # /usr/local/ssl/certs
  77
  78 [SSL]
  79 CIPHER          = DES-EDE-MD5:RC4-MD5
  80 USER_CERT       = $HOME/${USER}di'r 5'  # /home/eay/eaydir 5
  81 USER_CERT       = $HOME/\${USER}di\'r   # /home/eay/${USER}di'r
  82 USER_CERT       = "$HOME/${US"ER}di\'r  # $HOME/${USER}di'r
  83
  84 TEST            = 1234\
  85 5678\
  86 9ab                                     # TEST=123456789ab
  87 TTT             = 1234\n\n              # TTT=1234<nl><nl>
  88
  89