Config Files

The configuration file functions are a simple implementation of the INI file format, with the addition of default values.

#include <util/config-file.h>
type config_t

Config File Functions

config_t *config_create(const char *file)

Creates a new configuration object and associates it with the specified file name.

Parameters:
  • file – Path to the new configuration file

Returns:

A new configuration file object


int config_open(config_t **config, const char *file, enum config_open_type open_type)

Opens a configuration file.

Parameters:
  • config – Pointer that receives a pointer to a new configuration file object (if successful)

  • file – Path to the configuration file

  • open_type

    Can be one of the following values:

    • CONFIG_OPEN_EXISTING - Fail if the file doesn’t exist.

    • CONFIG_OPEN_ALWAYS - Try to open the file. If the file doesn’t exist, create it.

Returns:

Can return the following values:

  • CONFIG_SUCCESS - Successful

  • CONFIG_FILENOTFOUND - File not found

  • CONFIG_ERROR - Generic error


int config_open_string(config_t **config, const char *str)

Opens configuration data via a string rather than a file.

Parameters:
  • config – Pointer that receives a pointer to a new configuration file object (if successful)

  • str – Configuration string

Returns:

Can return the following values:

  • CONFIG_SUCCESS - Successful

  • CONFIG_FILENOTFOUND - File not found

  • CONFIG_ERROR - Generic error


int config_save(config_t *config)

Saves configuration data to a file (if associated with a file).

Parameters:
  • config – Configuration object

Returns:

Can return the following values:

  • CONFIG_SUCCESS - Successful

  • CONFIG_FILENOTFOUND - File not found

  • CONFIG_ERROR - Generic error


int config_save_safe(config_t *config, const char *temp_ext, const char *backup_ext)

Saves configuration data and minimizes overwrite corruption risk. Saves the file with the file name

Parameters:
  • config – Configuration object

  • temp_ext – Temporary extension for the new file

  • backup_ext – Backup extension for the old file. Can be NULL if no backup is desired.

Returns:

Can return the following values:

  • CONFIG_SUCCESS - Successful

  • CONFIG_FILENOTFOUND - File not found

  • CONFIG_ERROR - Generic error


void config_close(config_t *config)

Closes the configuration object.

Parameters:
  • config – Configuration object


size_t config_num_sections(config_t *config)

Returns the number of sections.

Parameters:
  • config – Configuration object

Returns:

Number of configuration sections


const char *config_get_section(config_t *config, size_t idx)

Returns a section name based upon its index.

Parameters:
  • config – Configuration object

  • idx – Index of the section

Returns:

The section’s name

Set/Get Functions

void config_set_string(config_t *config, const char *section, const char *name, const char *value)

Sets a string value.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

  • value – The string value


void config_set_int(config_t *config, const char *section, const char *name, int64_t value)

Sets an integer value.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

  • value – The integer value


void config_set_uint(config_t *config, const char *section, const char *name, uint64_t value)

Sets an unsigned integer value.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

  • value – The unsigned integer value


void config_set_bool(config_t *config, const char *section, const char *name, bool value)

Sets a boolean value.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

  • value – The boolean value


void config_set_double(config_t *config, const char *section, const char *name, double value)

Sets a floating point value.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

  • value – The floating point value


const char *config_get_string(config_t *config, const char *section, const char *name)

Gets a string value. If the value is not set, it will use the default value. If there is no default value, it will return NULL.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

Returns:

The string value


int64_t config_get_int(config_t *config, const char *section, const char *name)

Gets an integer value. If the value is not set, it will use the default value. If there is no default value, it will return 0.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

Returns:

The integer value


uint64_t config_get_uint(config_t *config, const char *section, const char *name)

Gets an unsigned integer value. If the value is not set, it will use the default value. If there is no default value, it will return 0.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

Returns:

The unsigned integer value


bool config_get_bool(config_t *config, const char *section, const char *name)

Gets a boolean value. If the value is not set, it will use the default value. If there is no default value, it will return false.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

Returns:

The boolean value


double config_get_double(config_t *config, const char *section, const char *name)

Gets a floating point value. If the value is not set, it will use the default value. If there is no default value, it will return 0.0.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

Returns:

The floating point value


bool config_remove_value(config_t *config, const char *section, const char *name)

Removes a value. Does not remove the default value if any.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

Default Value Functions

int config_open_defaults(config_t *config, const char *file)

Opens a file and uses it for default values.

Parameters:
  • config – Configuration object

  • file – The file to open for default values


void config_set_default_string(config_t *config, const char *section, const char *name, const char *value)

Sets a default string value.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

  • value – The string value


void config_set_default_int(config_t *config, const char *section, const char *name, int64_t value)

Sets a default integer value.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

  • value – The integer value


void config_set_default_uint(config_t *config, const char *section, const char *name, uint64_t value)

Sets a default unsigned integer value.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

  • value – The unsigned integer value


void config_set_default_bool(config_t *config, const char *section, const char *name, bool value)

Sets a default boolean value.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

  • value – The boolean value


void config_set_default_double(config_t *config, const char *section, const char *name, double value)

Sets a default floating point value.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

  • value – The floating point value


const char *config_get_default_string(config_t *config, const char *section, const char *name)

Gets a default string value. If there is no default value, it will return NULL.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

Returns:

The default string value


int64_t config_get_default_int(config_t *config, const char *section, const char *name)

Gets a default integer value. If there is no default value, it will return 0.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

Returns:

The integer value


uint64_t config_get_default_uint(config_t *config, const char *section, const char *name)

Gets a default unsigned integer value. If there is no default value, it will return 0.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

Returns:

The unsigned integer value


bool config_get_default_bool(config_t *config, const char *section, const char *name)

Gets a default boolean value. If there is no default value, it will return false.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

Returns:

The boolean value


double config_get_default_double(config_t *config, const char *section, const char *name)

Gets a default floating point value. If there is no default value, it will return 0.0.

Parameters:
  • config – Configuration object

  • section – The section of the value

  • name – The value name

Returns:

The floating point value


bool config_has_user_value(config_t *config, const char *section, const char *name)

Returns whether a value is user-set (true) or default/none (false).

param config:

Configuration object

param section:

The section of the value

param name:

The value name

return:

Whether a user value exists


bool config_has_default_value(config_t *config, const char *section, const char *name)

Returns whether a value has a default set.

param config:

Configuration object

param section:

The section of the value

param name:

The value name

return:

Whether a user value exists