Functions
[INI configuration interface]

Functions

const char * parsing_error_str (int parsing_error)
 Function to return a parsing error as a string.
const char * grammar_error_str (int parsing_error)
 Function to return a grammar error in template.
const char * validation_error_str (int parsing_error)
 Function to return a validation error.
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_lines (const char *application, const char *config_filename, struct collection_item **ini_config, int error_level, struct collection_item **error_list, struct collection_item **lines)
 Read configuration information from a file with extra collection of line numbers.
int config_from_fd_with_lines (const char *application, int fd, const char *config_source, struct collection_item **ini_config, int error_level, struct collection_item **error_list, struct collection_item **lines)
 Read configuration information from a file descriptor with extra collection of line numbers.
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.
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_lines (struct collection_item *lines)
 Function to free lines object.
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_grammar_errors (FILE *file, struct collection_item *error_list)
 Print errors and warnings that were detected while checking grammar of the template.
void print_validation_errors (FILE *file, struct collection_item *error_list)
 Print errors and warnings that were detected while checking INI file against the grammar object.
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.
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_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] application Name of the application, will be used as name of the collection.
[in] config_file Name of the configuration file, with default settings for all appplications.
[in] config_dir Name of the directory where the configuration files for different applications reside. Function will look for file with the name name constructed by appending ".ini" to the end of the "application" argument.
[out] ini_config A new configuration object.
[in] error_level Break for errors, warnings or best effort (don't break).
[out] error_set Collection of error lists. One list per file.
Returns:
0 - Success.
EINVAL - Invalid parameter.
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] application Name of the application, will be used as name of the collection.
[in] fd Previously opened file descriptor for the config file.
[in] config_source Name of the file being parsed, for use when printing the error list.
[out] ini_config If *ini_config is NULL a new ini object will be allocated, otherwise the one that is pointed to will be updated.
[in] error_level Break for errors, warnings or best effort (don't break).
[out] error_list List of errors for the file detected during parsing.
Returns:
0 - Success.
EINVAL - Invalid parameter.
int config_from_fd_with_lines ( const char *  application,
int  fd,
const char *  config_source,
struct collection_item **  ini_config,
int  error_level,
struct collection_item **  error_list,
struct collection_item **  lines 
)

Read configuration information from a file descriptor with extra collection of line numbers.

EXPERIMENTAL. Reserved for future use.

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] application Name of the application, will be used as name of the collection.
[in] config_filename Name of the config file, if NULL the configuration collection will be empty.
[out] ini_config If *ini_config is NULL a new ini object will be allocated, otherwise the one that is pointed to will be updated.
[in] error_level Break for errors, warnings or best effort (don't break).
[out] error_list List of errors for the file detected during parsing.
Returns:
0 - Success.
EINVAL - Invalid parameter.
Any error returned by fopen().
int config_from_file_with_lines ( const char *  application,
const char *  config_filename,
struct collection_item **  ini_config,
int  error_level,
struct collection_item **  error_list,
struct collection_item **  lines 
)

Read configuration information from a file with extra collection of line numbers.

EXPERIMENTAL. Reserved for future use.

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_list Array 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] bin Binary 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] array Array of floating pointer values.
void free_ini_config ( struct collection_item *  ini_config  ) 

Function to free configuration object.

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

Function to free configuration errors.

Parameters:
[in] error_set Configuration error set object.
void free_ini_config_lines ( struct collection_item *  lines  ) 

Function to free lines object.

EXPERIMENTAL. Reserved for future use.

Parameters:
[in] lines Lines 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] array Array 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_list Array 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_config Array 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_config Configuration object.
[in] section Section name.
[out] size If not NULL parameter will receive number of attributes in the section.
[out] error If 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] item Item to interpret. It must be retrieved using get_config_item().
[out] length Variable that optionally receives the length of the binary sequence.
[out] error Variable 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] item Item to interpret. It must be retrieved using get_config_item().
[in] def Default value to use if conversion failed.
[out] error Variable 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] section Section name. If NULL assumed default.
[in] name Attribute name to find.
[in] ini_config Configuration object to search.
[out] item Element 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] item Item to use. It must be retrieved using get_config_item().
[out] error Variable 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] item Item to interpret. It must be retrieved using get_config_item().
[out] size Variable that receives the size of the array.
[out] error Variable 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] item Item to interpret. It must be retrieved using get_config_item().
[in] strict Fail the function if the symbol after last digit is not valid.
[in] def Default value to use if conversion failed.
[out] error Variable 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_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] item Item to interpret. It must be retrieved using get_config_item().
[in] strict Fail the function if the symbol after last digit is not valid.
[in] def Default value to use if conversion failed.
[out] error Variable 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] item Item to interpret. It must be retrieved using get_config_item().
[out] size Variable that receives the size of the array.
[out] error Variable 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] item Item to interpret. It must be retrieved using get_config_item().
[in] strict Fail the function if the symbol after last digit is not valid.
[in] def Default value to use if conversion failed.
[out] error Variable 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] item Item to interpret. It must be retrieved using get_config_item().
[in] sep String cosisting of separator symbols. For example: ",.;" would mean that comma, dot and semicolon should be treated as separators in the value.
[out] size Variable that optionally receives the size of the array.
[out] error Variable 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_config Configuration object.
[out] size If not NULL parameter will receive number of sections in the configuration.
[out] error If 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] item Item to interpret. It must be retrieved using get_config_item().
[in] sep String cosisting of separator symbols. For example: ",.;" would mean that comma, dot and semicolon should be treated as separators in the value.
[out] size Variable that optionally receives the size of the array.
[out] error Variable 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] item Item to use. It must be retrieved using get_config_item().
[out] error Variable 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.
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] item Item to interpret. It must be retrieved using get_config_item().
[in] strict Fail the function if the symbol after last digit is not valid.
[in] def Default value to use if conversion failed.
[out] error Variable 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] item Item to interpret. It must be retrieved using get_config_item().
[in] strict Fail the function if the symbol after last digit is not valid.
[in] def Default value to use if conversion failed.
[out] error Variable 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* grammar_error_str ( int  parsing_error  ) 

Function to return a grammar error in template.

EXPERIMENTAL. Reserved for future use.

This error is returned when the template is translated into the grammar object.

Parameters:
[in] parsing_error Error code for the grammar error.
Returns:
Error string.
const char* parsing_error_str ( int  parsing_error  ) 

Function to return a parsing error as a string.

Parameters:
[in] parsing_error Error 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] file File descriptor.
[in] error_set List 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] file File descriptor.
[in] error_list List of the parsing errors.
void print_grammar_errors ( FILE *  file,
struct collection_item *  error_list 
)

Print errors and warnings that were detected while checking grammar of the template.

EXPERIMENTAL. Reserved for future use.

Parameters:
[in] file File descriptor.
[in] error_list List of the parsing errors.
void print_validation_errors ( FILE *  file,
struct collection_item *  error_list 
)

Print errors and warnings that were detected while checking INI file against the grammar object.

EXPERIMENTAL. Reserved for future use.

Parameters:
[in] file File descriptor.
[in] error_list List of the parsing errors.
const char* validation_error_str ( int  parsing_error  ) 

Function to return a validation error.

EXPERIMENTAL. Reserved for future use.

This is the error that it is returned when the INI file is validated against the grammar object.

Parameters:
[in] parsing_error Error code for the validation error.
Returns:
Error string.
 All Data Structures

Generated on 11 Jan 2011 for libini_config by  doxygen 1.6.1