libini_config 0.1.3
Functions
Functions
INI configuration interface

Functions

const char * parsing_error_str (int parsing_error)
 Function to return a parsing error as a string.
int config_from_file (const char *application, const char *config_filename, struct collection_item **ini_config, int error_level, struct collection_item **error_list)
 Read configuration information from a file.
int config_from_fd (const char *application, int fd, const char *config_source, struct collection_item **ini_config, int error_level, struct collection_item **error_list)
 Read configuration information from a file descriptor.
int config_from_file_with_metadata (const char *application, const char *config_filename, struct collection_item **ini_config, int error_level, struct collection_item **error_list, uint32_t metaflags, struct collection_item **metadata)
 Read configuration information from a file with additional meta data.
int config_from_fd_with_metadata (const char *application, int fd, const char *config_source, struct collection_item **ini_config, int error_level, struct collection_item **error_list, uint32_t metaflags, struct collection_item **metadata)
 Read configuration information from a file descriptor with additional meta data.
int config_for_app (const char *application, const char *config_file, const char *config_dir, struct collection_item **ini_config, int error_level, struct collection_item **error_set)
 Read default configuration file and then overwrite it with a specific one from the directory.
int config_for_app_with_metadata (const char *application, const char *config_file, const char *config_dir, struct collection_item **ini_config, int error_level, struct collection_item **error_set, uint32_t metaflags, struct collection_item **meta_default, struct collection_item **meta_appini)
 Read default configuration file and then overwrite it with a specific one from the directory.
int config_access_check (struct collection_item *metadata, uint32_t flags, uid_t uid, gid_t gid, mode_t mode, mode_t mask)
 Function to check ownership and permissions.
int config_changed (struct collection_item *metadata, struct collection_item *saved_metadata, int *changed)
 Function compares two meta data objects.
void free_ini_config (struct collection_item *ini_config)
 Function to free configuration object.
void free_ini_config_errors (struct collection_item *error_set)
 Function to free configuration errors.
void free_ini_config_metadata (struct collection_item *metadata)
 Function to free metadata.
void print_file_parsing_errors (FILE *file, struct collection_item *error_list)
 Print errors and warnings that were detected while parsing one file.
void print_config_parsing_errors (FILE *file, struct collection_item *error_set)
 Print errors and warnings that were detected parsing configuration as a whole.
char ** get_section_list (struct collection_item *ini_config, int *size, int *error)
 Get list of sections.
void free_section_list (char **section_list)
 Free list of sections.
char ** get_attribute_list (struct collection_item *ini_config, const char *section, int *size, int *error)
 Get list of attributes.
void free_attribute_list (char **attr_list)
 Free list of attributes.
int get_config_item (const char *section, const char *name, struct collection_item *ini_config, struct collection_item **item)
 Get a configuration item form the configuration.
int get_int_config_value (struct collection_item *item, int strict, int def, int *error)
 Convert item value to integer number.
long get_long_config_value (struct collection_item *item, int strict, long def, int *error)
 Convert item value to long number.
unsigned get_unsigned_config_value (struct collection_item *item, int strict, unsigned def, int *error)
 Convert item value to unsigned integer number.
unsigned long get_ulong_config_value (struct collection_item *item, int strict, unsigned long def, int *error)
 Convert item value to unsigned long number.
int32_t get_int32_config_value (struct collection_item *item, int strict, int32_t def, int *error)
 Convert item value to integer number.
uint32_t get_uint32_config_value (struct collection_item *item, int strict, uint32_t def, int *error)
 Convert item value to integer number.
int64_t get_int64_config_value (struct collection_item *item, int strict, int64_t def, int *error)
 Convert item value to integer number.
uint64_t get_uint64_config_value (struct collection_item *item, int strict, uint64_t def, int *error)
 Convert item value to integer number.
double get_double_config_value (struct collection_item *item, int strict, double def, int *error)
 Convert item value to floating point number.
unsigned char get_bool_config_value (struct collection_item *item, unsigned char def, int *error)
 Convert item value into a logical value.
char * get_string_config_value (struct collection_item *item, int *error)
 Get string configuration value.
const char * get_const_string_config_value (struct collection_item *item, int *error)
 Function returns the string stored in the item.
char * get_bin_config_value (struct collection_item *item, int *length, int *error)
 Convert item value into a binary sequence.
void free_bin_config_value (char *bin)
 Free binary buffer.
char ** get_string_config_array (struct collection_item *item, const char *sep, int *size, int *error)
 Convert value to an array of strings.
char ** get_raw_string_config_array (struct collection_item *item, const char *sep, int *size, int *error)
 Convert value to an array of strings.
long * get_long_config_array (struct collection_item *item, int *size, int *error)
 Convert value to an array of long values.
double * get_double_config_array (struct collection_item *item, int *size, int *error)
 Convert value to an array of floating point values.
void free_string_config_array (char **str_config)
 Free array of string values.
void free_long_config_array (long *array)
 Free array of long values.
void free_double_config_array (double *array)
 Free array of floating pointer values.

Function Documentation

int config_access_check ( struct collection_item *  metadata,
uint32_t  flags,
uid_t  uid,
gid_t  gid,
mode_t  mode,
mode_t  mask 
)

Function to check ownership and permissions.

The function allow caller to make decision if the configuration file is from a trusted source or not.

The flags control how to perform check. See Access control check flags section for more information.

Parameters:
[in]metadataMeta data object. Can't be NULL.
[in]flagsHow and what to check. Must be nonzero.
[in]uidUID to check.
[in]gidGID to check.
[in]modeMode to check. Only permission bits are used.
[in]maskWhich mode bits to check. If 0 all permision bits are checked.
Returns:
0 - Success.
EINVAL - Invalid parameter.
EACCESS - File properties do not match provided access parameters.
int config_changed ( struct collection_item *  metadata,
struct collection_item *  saved_metadata,
int *  changed 
)

Function compares two meta data objects.

Function compares two meta data objects to determine whether the configuration has changed since last time the meta data was collected. The function checks three things about the file:

  • time stamp
  • device ID
  • i-node If any of those changes function will indicate that configuration changed.
Parameters:
[in]metadataRecent meta data object.
[in]saved_metadataPreviously saved meta data object.
[out]changedWill be set to a nonzero value if the configuration has changed.
Returns:
0 - No internal error
EINVAL - Invalid argument
ENOENT - Expected value is missing
ENOMEM - No memory
int config_for_app ( const char *  application,
const char *  config_file,
const char *  config_dir,
struct collection_item **  ini_config,
int  error_level,
struct collection_item **  error_set 
)

Read default configuration file and then overwrite it with a specific one from the directory.

Parameters:
[in]applicationName of the application, will be used as name of the collection.
[in]config_fileName of the configuration file, with default settings for all appplications.
[in]config_dirName of the directory where the configuration files for different applications reside. Function will look for file with the name constructed by appending ".ini" to the end of the "application" argument.
[out]ini_configA new configuration object.
[in]error_levelBreak for errors, warnings or best effort (don't break).
[out]error_setCollection of error lists. One list per file.
Returns:
0 - Success.
EINVAL - Invalid parameter.
EMOMEM - No memory.
Any error returned by fopen().
int config_for_app_with_metadata ( const char *  application,
const char *  config_file,
const char *  config_dir,
struct collection_item **  ini_config,
int  error_level,
struct collection_item **  error_set,
uint32_t  metaflags,
struct collection_item **  meta_default,
struct collection_item **  meta_appini 
)

Read default configuration file and then overwrite it with a specific one from the directory.

If requested collect meta data for both.

If the metadata argument is not NULL the calling function MUST always free meta data since it can be allocated even if the function returned error.

Parameters:
[in]applicationName of the application, will be used as name of the collection.
[in]config_fileName of the configuration file, with default settings for all appplications.
[in]config_dirName of the directory where the configuration files for different applications reside. Function will look for file with the name constructed by appending ".ini" to the end of the "application" argument.
[out]ini_configA new configuration object.
[in]error_levelBreak for errors, warnings or best effort (don't break).
[out]error_setCollection of error lists. One list per file.
[in]metaflagsA bit mask of flags that define what kind of metadata should be collected.
[out]meta_defaultCollection of metadata values for the default common config file for all applications. See meta data section for more details. Can be NULL.
[out]meta_appiniCollection of metadata values for the application specific config file. See meta data section for more details. Can be NULL.
Returns:
0 - Success.
EINVAL - Invalid parameter.
EMOMEM - No memory.
Any error returned by fopen().
int config_from_fd ( const char *  application,
int  fd,
const char *  config_source,
struct collection_item **  ini_config,
int  error_level,
struct collection_item **  error_list 
)

Read configuration information from a file descriptor.

Parameters:
[in]applicationName of the application, will be used as name of the collection.
[in]fdPreviously opened file descriptor for the config file.
[in]config_sourceName of the file being parsed, for use when printing the error list.
[out]ini_configIf *ini_config is NULL a new ini object will be allocated, otherwise the one that is pointed to will be updated.
[in]error_levelBreak for errors, warnings or best effort (don't break).
[out]error_listList of errors for the file detected during parsing.
Returns:
0 - Success.
EMOMEM - No memory.
EINVAL - Invalid parameter.
int config_from_fd_with_metadata ( const char *  application,
int  fd,
const char *  config_source,
struct collection_item **  ini_config,
int  error_level,
struct collection_item **  error_list,
uint32_t  metaflags,
struct collection_item **  metadata 
)

Read configuration information from a file descriptor with additional meta data.

Meta data consists of addition information about the file for example when it was created or who is the owner. For the detailed description of the meta data content and structure see meta data section.

If the metadata argument is not NULL the calling function MUST always free meta data since it can be allocated even if the function returned error.

Parameters:
[in]applicationName of the application, will be used as name of the collection.
[in]fdPreviously opened file descriptor for the config file.
[in]config_sourceName of the file being parsed, for use when printing the error list.
[out]ini_configIf *ini_config is NULL a new ini object will be allocated, otherwise the one that is pointed to will be updated.
[in]error_levelBreak for errors, warnings or best effort (don't break).
[out]error_listList of errors for the file detected during parsing.
[in]metaflagsA bit mask of flags that define what kind of metadata should be collected.
[out]metadataCollection of metadata values. See meta data section for more details. Can be NULL.
Returns:
0 - Success.
EINVAL - Invalid parameter.
EMOMEM - No memory.
int config_from_file ( const char *  application,
const char *  config_filename,
struct collection_item **  ini_config,
int  error_level,
struct collection_item **  error_list 
)

Read configuration information from a file.

Parameters:
[in]applicationName of the application, will be used as name of the collection.
[in]config_filenameName of the config file, if NULL the configuration collection will be empty.
[out]ini_configIf *ini_config is NULL a new ini object will be allocated, otherwise the one that is pointed to will be updated.
[in]error_levelBreak for errors, warnings or best effort (don't break).
[out]error_listList of errors for the file detected during parsing.
Returns:
0 - Success.
EINVAL - Invalid parameter.
EMOMEM - No memory.
Any error returned by fopen().
int config_from_file_with_metadata ( const char *  application,
const char *  config_filename,
struct collection_item **  ini_config,
int  error_level,
struct collection_item **  error_list,
uint32_t  metaflags,
struct collection_item **  metadata 
)

Read configuration information from a file with additional meta data.

Meta data consists of addition information about the file for example when it was created or who is the owner. For the detailed description of the meta data content and structure see meta data section.

If the metadata argument is not NULL the calling function MUST always free meta data since it can be allocated even if the function returned error.

Parameters:
[in]applicationName of the application, will be used as name of the collection.
[in]config_filenameName of the config file, if NULL the configuration collection will be empty.
[out]ini_configIf *ini_config is NULL a new ini object will be allocated, otherwise the one that is pointed to will be updated.
[in]error_levelBreak for errors, warnings or best effort (don't break).
[out]error_listList of errors for the file detected during parsing.
[in]metaflagsA bit mask of flags that define what kind of metadata should be collected.
[out]metadataCollection of metadata values. See meta data section for more details. Can be NULL.
Returns:
0 - Success.
EINVAL - Invalid parameter.
EMOMEM - No memory.
Any error returned by fopen().
void free_attribute_list ( char **  attr_list)

Free list of attributes.

The attribute array created by get_attribute_list() should be freed using this function.

Parameters:
[in]attr_listArray of strings returned by get_attribute_list() function.
void free_bin_config_value ( char *  bin)

Free binary buffer.

Free binary value returned by get_bin_config_value().

Parameters:
[in]binBinary buffer to free.
void free_double_config_array ( double *  array)

Free array of floating pointer values.

Use this function to free the array returned by get_double_config_array().

Parameters:
[in]arrayArray of floating pointer values.
void free_ini_config ( struct collection_item *  ini_config)

Function to free configuration object.

Parameters:
[in]ini_configConfiguration object.
void free_ini_config_errors ( struct collection_item *  error_set)

Function to free configuration errors.

Parameters:
[in]error_setConfiguration error set object.
void free_ini_config_metadata ( struct collection_item *  metadata)

Function to free metadata.

Parameters:
[in]metadataConfiguration meta data object.
void free_long_config_array ( long *  array)

Free array of long values.

Use this function to free the array returned by get_long_config_array().

Parameters:
[in]arrayArray of long values.
void free_section_list ( char **  section_list)

Free list of sections.

The section array created by get_section_list() should be freed using this function.

Parameters:
[in]section_listArray of strings returned by get_section_list() function.
void free_string_config_array ( char **  str_config)

Free array of string values.

Use this function to free the array returned by get_string_config_array() or by get_raw_string_config_array().

Parameters:
[in]str_configArray of string values.
char** get_attribute_list ( struct collection_item *  ini_config,
const char *  section,
int *  size,
int *  error 
)

Get list of attributes.

Get list of attributes in a section as an array of strings. Function allocates memory for the array of attributes. Use free_attribute_list() to free allocated memory.

Parameters:
[in]ini_configConfiguration object.
[in]sectionSection name.
[out]sizeIf not NULL parameter will receive number of attributes in the section.
[out]errorIf not NULL parameter will receive the error code. 0 - Success. EINVAL - Invalid parameter. ENOMEM - No memory.
Returns:
Array of strings.
char* get_bin_config_value ( struct collection_item *  item,
int *  length,
int *  error 
)

Convert item value into a binary sequence.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into a sequence of bytes. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value.

The function allocates memory. It is the responsibility of the caller to free it after use. Use free_bin_config_value() for this purpose. Functions will return NULL if conversion failed.

Function assumes that the value being interpreted has a special format. The string should be taken in single quotes and consist of hex encoded value represented by two hex digits per byte. Case does not matter.

Example: '0a2BFeCc'

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[out]lengthVariable that optionally receives the length of the binary sequence.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ENOMEM - No memory.
Returns:
Converted value. In case of failure the function returns NULL.
unsigned char get_bool_config_value ( struct collection_item *  item,
unsigned char  def,
int *  error 
)

Convert item value into a logical value.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into a Boolean. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value.

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
Returns:
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
int get_config_item ( const char *  section,
const char *  name,
struct collection_item *  ini_config,
struct collection_item **  item 
)

Get a configuration item form the configuration.

Check return error code first. If the function returns an error there is a serious problem. Then check if item is found. Function will set item parameter to NULL if no attribute with provided name is found in the collection.

Parameters:
[in]sectionSection name. If NULL assumed default.
[in]nameAttribute name to find.
[in]ini_configConfiguration object to search.
[out]itemElement of configuration collection. Will be set to NULL if element with the given name is not found.
Returns:
0 - Success.
EINVAL - Invalid parameter.
ENOMEM - No memory.
const char* get_const_string_config_value ( struct collection_item *  item,
int *  error 
)

Function returns the string stored in the item.

Function returns a reference to the string value stored inside the item. This string can't be altered. The string will go out of scope if the item is deleted.

Parameters:
[in]itemItem to use. It must be retrieved using get_config_item().
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
Returns:
String from the item.
double* get_double_config_array ( struct collection_item *  item,
int *  size,
int *  error 
)

Convert value to an array of floating point values.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into an array of floating point values. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value.

Separators inside the string are detected automatically. The spaces are trimmed automatically around separators in the string.

The length of the allocated array is returned in "size". Size parameter can't be NULL.

Use free_double_config_array() to free the array after use.

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[out]sizeVariable that receives the size of the array.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed.
  • ENOMEM - No memory.
Returns:
Array of floating point values. In case of failure the function returns NULL.
double get_double_config_value ( struct collection_item *  item,
int  strict,
double  def,
int *  error 
)

Convert item value to floating point number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into a floating point number. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit.

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
Returns:
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
int32_t get_int32_config_value ( struct collection_item *  item,
int  strict,
int32_t  def,
int *  error 
)

Convert item value to integer number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into an int32_t number. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from INT_MIN to INT_MAX.

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns:
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
int64_t get_int64_config_value ( struct collection_item *  item,
int  strict,
int64_t  def,
int *  error 
)

Convert item value to integer number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into an int64_t number. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from LLONG_MIN to LLONG_MAX.

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns:
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
int get_int_config_value ( struct collection_item *  item,
int  strict,
int  def,
int *  error 
)

Convert item value to integer number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into an integer number. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from INT_MIN to INT_MAX.

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns:
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
long* get_long_config_array ( struct collection_item *  item,
int *  size,
int *  error 
)

Convert value to an array of long values.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into an array of long values. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value.

Separators inside the string are detected automatically. The spaces are trimmed automatically around separators in the string.

The length of the allocated array is returned in "size". Size parameter can't be NULL.

Use free_long_config_array() to free the array after use.

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[out]sizeVariable that receives the size of the array.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed.
  • ERANGE - Value is out of range.
  • ENOMEM - No memory.
Returns:
Array of long values. In case of failure the function returns NULL.
long get_long_config_value ( struct collection_item *  item,
int  strict,
long  def,
int *  error 
)

Convert item value to long number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into a long number. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from LONG_MIN to LONG_MAX.

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns:
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
char** get_raw_string_config_array ( struct collection_item *  item,
const char *  sep,
int *  size,
int *  error 
)

Convert value to an array of strings.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into an array of strings. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value.

Separator string includes up to three different separators. If separator NULL, comma is assumed. The spaces are trimmed automatically around separators in the string. The function does not drop empty tokens from the list. This means that the string like this: "apple, ,banana, ,orange ," will be translated into the list of five items: "apple", "", "banana", "" and "orange".

The length of the allocated array is returned in "size". Size and error parameters can be NULL. Use free_string_config_array() to free the array after use.

The array is always NULL terminated so it is safe not to get size and just loop until array element is NULL.

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[in]sepString cosisting of separator symbols. For example: ",.;" would mean that comma, dot and semicolon should be treated as separators in the value.
[out]sizeVariable that optionally receives the size of the array.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed.
  • ENOMEM - No memory.
Returns:
Array of strings. In case of failure the function returns NULL.
char** get_section_list ( struct collection_item *  ini_config,
int *  size,
int *  error 
)

Get list of sections.

Get list of sections from the configuration object as an array of strings. Function allocates memory for the array of the sections. Use free_section_list() to free allocated memory.

Parameters:
[in]ini_configConfiguration object.
[out]sizeIf not NULL parameter will receive number of sections in the configuration.
[out]errorIf not NULL parameter will receive the error code. 0 - Success. EINVAL - Invalid parameter. ENOMEM - No memory.
Returns:
Array of strings.
char** get_string_config_array ( struct collection_item *  item,
const char *  sep,
int *  size,
int *  error 
)

Convert value to an array of strings.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into an array of strings. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value.

Separator string includes up to three different separators. If separator NULL, comma is assumed. The spaces are trimmed automatically around separators in the string. The function drops empty tokens from the list. This means that the string like this: "apple, ,banana, ,orange ," will be translated into the list of three items: "apple","banana" and "orange".

The length of the allocated array is returned in "size". Size and error parameters can be NULL. Use free_string_config_array() to free the array after use.

The array is always NULL terminated so it is safe not to get size and just loop until array element is NULL.

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[in]sepString cosisting of separator symbols. For example: ",.;" would mean that comma, dot and semicolon should be treated as separators in the value.
[out]sizeVariable that optionally receives the size of the array.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed.
  • ENOMEM - No memory.
Returns:
Array of strings. In case of failure the function returns NULL.
char* get_string_config_value ( struct collection_item *  item,
int *  error 
)

Get string configuration value.

Function creates a copy of the string value stored in the item. Returned value needs to be freed after use. If error occurred the returned value will be NULL.

Parameters:
[in]itemItem to use. It must be retrieved using get_config_item().
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • ENOMEM - No memory.
Returns:
Copy of the string or NULL.
uint32_t get_uint32_config_value ( struct collection_item *  item,
int  strict,
uint32_t  def,
int *  error 
)

Convert item value to integer number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into an uint32_t number. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from 0 to ULONG_MAX.

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns:
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
uint64_t get_uint64_config_value ( struct collection_item *  item,
int  strict,
uint64_t  def,
int *  error 
)

Convert item value to integer number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into an uint64_t number. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from 0 to ULLONG_MAX.

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns:
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
unsigned long get_ulong_config_value ( struct collection_item *  item,
int  strict,
unsigned long  def,
int *  error 
)

Convert item value to unsigned long number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into an unsigned long number. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from 0 to ULONG_MAX.

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns:
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
unsigned get_unsigned_config_value ( struct collection_item *  item,
int  strict,
unsigned  def,
int *  error 
)

Convert item value to unsigned integer number.

This is a conversion function. It converts the value read from the INI file and stored in the configuration item into an unsigned integer number. Any of the conversion functions can be used to try to convert the value stored as a string inside the item. The results can be different depending upon how the caller tries to interpret the value. If "strict" parameter is non zero the function will fail if there are more characters after the last digit. The value range is from 0 to UINT_MAX.

Parameters:
[in]itemItem to interpret. It must be retrieved using get_config_item().
[in]strictFail the function if the symbol after last digit is not valid.
[in]defDefault value to use if conversion failed.
[out]errorVariable will get the value of the error code if error happened. Can be NULL. In this case function does not set the code. Codes:
  • 0 - Success.
  • EINVAL - Argument is invalid.
  • EIO - Conversion failed due invalid characters.
  • ERANGE - Value is out of range.
Returns:
Converted value. In case of failure the function returns default value and sets error code into the provided variable.
const char* parsing_error_str ( int  parsing_error)

Function to return a parsing error as a string.

Parameters:
[in]parsing_errorError code for the parsing error.
Returns:
Error string.
void print_config_parsing_errors ( FILE *  file,
struct collection_item *  error_set 
)

Print errors and warnings that were detected parsing configuration as a whole.

Use this function to print results of the config_for_app() call.

Parameters:
[in]fileFile descriptor.
[in]error_setList of lists of the parsing errors.
void print_file_parsing_errors ( FILE *  file,
struct collection_item *  error_list 
)

Print errors and warnings that were detected while parsing one file.

Parameters:
[in]fileFile descriptor.
[in]error_listList of the parsing errors.
 All Data Structures