bionic (3) override_config_file.3alleg4.gz

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)