Configuration routines



Various parts of Allegro, such as the sound routines and the load_joystick_data() function, require some configuration information. This data is stored in text files as a collection of "variable=value" lines, along with comments that begin with a '#' character and continue to the end of the line. The configuration file may optionally be divided into sections, which begin with a "[sectionname]" line. Each section has a unique namespace, to prevent variable name conflicts, but any variables that aren't in a section are considered to belong to all the sections simultaneously.

By default the configuration data is read from a file called allegro.cfg or sound.cfg, which can be located either in the same directory as the program executable, or the directory pointed to by the ALLEGRO environment variable. If you don't like this approach, you can specify any filename you like, or use a block of binary configuration data provided by your program (which could for example be loaded from a datafile).

You can store whatever custom information you like in the config file, along with the standard variables that are used by Allegro (see below).

void set_config_file(char *filename);
Sets the configuration file to be used by all subsequent config functions. If you don't call this function, Allegro will use the default allegro.cfg file, looking first in the same directory as your program and then in the directory pointed to by the ALLEGRO environment variable.

void set_config_data(char *data, int length);
Specifies a block of data to be used by all subsequent config functions, which you have already loaded from disk (eg. as part of some more complicated format of your own, or in a grabber datafile). This routine makes a copy of the information, so you can safely free the data after calling it.

void override_config_file(char *filename);
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 a sound.cfg or allegro.cfg file to specify the port settings and irq numbers.

void override_config_data(char *data, int length);
Version of override_config_file() which uses a block of data that has already been read into memory.

void push_config_state();
Pushes the current configuration state (filename, variable values, etc). onto an internal stack, allowing you to select some other config source and later restore the current settings by calling pop_config_state(). This function is mostly intended for internal use by other library functions, for example when you specify a config filename to the save_joystick_data() function, it pushes the config state before switching to the file you specified.

void pop_config_state();
Pops a configuration state previously stored by push_config_state(), replacing the current config source with it.

char *get_config_string(char *section, char *name, char *def);
Retrieves a string variable from the current config file. If the named variable cannot be found, the value of def is returned. The section name may be set to NULL to accept variables from any part of the file, or used to control which set of parameters (eg. sound or joystick) you are interested in reading.

int get_config_int(char *section, char *name, int def);
Reads an integer variable from the current config file. See the comments about get_config_string().

int get_config_hex(char *section, char *name, int def);
Reads an integer variable from the current config file, in hexadecimal format. See the comments about get_config_string().

float get_config_float(char *section, char *name, float def);
Reads a floating point variable from the current config file. See the comments about get_config_string().

char **get_config_argv(char *section, char *name, int *argc);
Reads a token list (words separated by spaces) from the current config file, returning a an argv style argument list, and setting argc to the number of tokens (unlike argc/argv, this list is zero based). Returns NULL and sets argc to zero if the variable is not present. The token list is stored in a temporary buffer that will be clobbered by the next call to get_config_argv(), so the data should not be expected to persist.

void set_config_string(char *section, char *name, char *val);
Writes a string variable to the current config file, replacing any existing value it may have, or removes the variable if val is NULL. The section name may be set to NULL to write the variable to the root of the file, or used to control which section the variable is inserted into. The altered file will be cached in memory, and not actually written to disk until you call allegro_exit(). Note that you can only write to files in this way, so the function will have no effect if the current config source was specified with set_config_data() rather than set_config_file().

void set_config_int(char *section, char *name, int val);
Writes an integer variable to the current config file. See the comments about set_config_string().

void set_config_hex(char *section, char *name, int val);
Writes an integer variable to the current config file, in hexadecimal format. See the comments about set_config_string().

void set_config_float(char *section, char *name, float val);
Writes a floating point variable to the current config file. See the comments about set_config_string().


Allegro uses these standard variables from the configuration file:




Back to Contents