Provided by: allegro4-doc_4.4.2-4_all bug

NAME

       override_config_file  -  Specifies  a  file  containing  config  overrides.  Allegro  game
       programming library.

SYNOPSIS

       #include <allegro.h>

       void override_config_file(const char *filename);

DESCRIPTION

       Specifies a file containing config overrides. These settings will be used in  addition  to
       the parameters in the main config file, and where a variable is present in both files this
       version will take priority. This can be used by application programmers to  override  some
       of  the config settings from their code, while still leaving the main config file free for
       the end user to customise. For example, you could specify a  particular  sample  frequency
       and IBK instrument file, but the user could still use an `allegro.cfg' file to specify the
       port settings and irq numbers.

       The override config file will not only take precedence when reading, but will also be used
       for  storing  values.  When you are done with using the override config file, you can call
       override_config_file with a NULL parameter, so config data will be directly read from  the
       current config file again.

       Note:  The override file is completely independent from the current configuration. You can
       e.g. call  set_config_file,  and  the  override  file  will  still  be  active.  Also  the
       flush_config_file  function will only affect the current config file (which can be changed
       with set_config_file), never the overriding one specified with this function. The modified
       override config is written back to disk whenever you call override_config_file.

       Example:

          override_config_file("my.cfg");
          /* This will read from my.cfg, and if it doesn't find a
           * setting, will read from the current config file instead.
           */
          language = get_config_string("system", "language", NULL);
          /* This will always write to my.cfg, no matter if the
           * settings is already present or not.
           */
          set_config_string("system", "language", "RU");
          /* This forces the changed setting to be written back to
           * disk. Else it is written back at the next call to
           * override_config_file, or when Allegro shuts down.
           */
          override_config_file(NULL);

       Note  that  this  function and override_config_data() are mutually exclusive, i.e. calling
       one will cancel the effects of the other.

SEE ALSO

       override_config_data(3alleg4), set_config_file(3alleg4)