libini_config  0.6.1
 All Data Structures Functions Variables Enumerations Enumerator Groups Pages
Functions
API to create and modify configuration objects

Functions

int ini_config_add_section (struct ini_cfgobj *ini_config, const char *section, const char *comments[], size_t count_comment, int position, const char *other_section, int idx)
 Function to add a section. More...
 
int ini_config_comment_section (struct ini_cfgobj *ini_config, const char *section, const char *comments[], size_t count_comment)
 Function to update a comment for a section. More...
 
int ini_config_rename_section (struct ini_cfgobj *ini_config, const char *section, const char *newname)
 Function to rename a section. More...
 
int ini_config_delete_section_by_name (struct ini_cfgobj *ini_config, const char *section)
 Function to delete a section by name. More...
 
int ini_config_delete_section_by_position (struct ini_cfgobj *ini_config, int position, const char *section, int idx)
 Function to delete a section by position or name. More...
 
int ini_config_add_str_value (struct ini_cfgobj *ini_config, const char *section, const char *key, const char *value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to a add string value to a particular section. More...
 
int ini_config_add_int_value (struct ini_cfgobj *ini_config, const char *section, const char *key, int value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add an integer value to a particular section. More...
 
int ini_config_add_long_value (struct ini_cfgobj *ini_config, const char *section, const char *key, long value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add a long value to a particular section. More...
 
int ini_config_add_ulong_value (struct ini_cfgobj *ini_config, const char *section, const char *key, unsigned long value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add an unsigned long value to a particular section. More...
 
int ini_config_add_unsigned_value (struct ini_cfgobj *ini_config, const char *section, const char *key, unsigned value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add an unsigned value to a particular section. More...
 
int ini_config_add_int32_value (struct ini_cfgobj *ini_config, const char *section, const char *key, int32_t value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add an int32 value to a particular section. More...
 
int ini_config_add_uint32_value (struct ini_cfgobj *ini_config, const char *section, const char *key, uint32_t value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add an uint32 value to a particular section. More...
 
int ini_config_add_int64_value (struct ini_cfgobj *ini_config, const char *section, const char *key, int64_t value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add an int64 value to a particular section. More...
 
int ini_config_add_uint64_value (struct ini_cfgobj *ini_config, const char *section, const char *key, uint64_t value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add an uint64 value to a particular section. More...
 
int ini_config_add_double_value (struct ini_cfgobj *ini_config, const char *section, const char *key, double value, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add a double value to a particular section. More...
 
int ini_config_add_bin_value (struct ini_cfgobj *ini_config, const char *section, const char *key, void *value, size_t value_len, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add a binary value to a particular section. More...
 
int ini_config_add_const_str_arr_value (struct ini_cfgobj *ini_config, const char *section, const char *key, const char *value_str_arr[], size_t count_str, char sep, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add a value that consists of an array of constant strings to a particular section. More...
 
int ini_config_add_str_arr_value (struct ini_cfgobj *ini_config, const char *section, const char *key, char *value_str_arr[], size_t count_str, char sep, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add a value that consists of an array of strings to a particular section. More...
 
int ini_config_add_int_arr_value (struct ini_cfgobj *ini_config, const char *section, const char *key, int *value_int_arr, size_t count_int, char sep, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add a value that consists of an array of integers to a particular section. More...
 
int ini_config_add_long_arr_value (struct ini_cfgobj *ini_config, const char *section, const char *key, long *value_long_arr, size_t count_long, char sep, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add a value that consists of an array of long integers to a particular section. More...
 
int ini_config_add_double_arr_value (struct ini_cfgobj *ini_config, const char *section, const char *key, double *value_double_arr, size_t count_double, char sep, const char *comments[], size_t count_comment, int border, int position, const char *other_key, int idx, enum INI_VA flags)
 Function to add a value that consists of an array of doubles to a particular section. More...
 
int ini_config_delete_value (struct ini_cfgobj *ini_config, const char *section, int position, const char *key, int idx)
 Function to delete a value. More...
 
int ini_config_update_comment (struct ini_cfgobj *ini_config, const char *section, const char *key, const char *comments[], size_t count_comment, int idx)
 Function to update a comment. More...
 

Detailed Description

Functions in this section allow creation, modification and deletion of sections and keys.

Explanation of some of the common arguments:

Parameters
[in]positionSpecifies the position a key or a section should be added to.

Options include:
  • Last in the list
  • First in the list
  • N-th element of the list
  • Before a specific element of the list
  • After a specific element of the list
  • As a first duplicate of a specific element
  • As a last duplicate of a specific element
  • As an N-th duplicate of a specific element

    Duplicates can be sequential or not, so there are different constants that specify whether to count all duplicates or just the ones that go together.
[in]other_xxxUsed in conjunction with 'position' constant. In some cases it is convenient to add a section or key immediately before or after another section or key. While 'position' defines where it should be added, this parameter defines the section or key to relate to.
[in]idxIndex allows treating set of sections or keys as an array and add Nth section or key.

Function Documentation

int ini_config_add_section ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  comments[],
size_t  count_comment,
int  position,
const char *  other_section,
int  idx 
)

Function to add a section.

Function creates a new section in the specified position. The position is relative to other sections. Duplicate sections are not allowed. In case a duplicate section is detected function will return error EEXIST.

Parameters
[in]ini_configConfiguration object to modify.
[in]sectionName of the section to add.
[in]commentsArray of comments. Can be NULL, if no comment is needed for the section. It is expected that comment lines start with the correct comment symbol. Function does not check this. Use empty string to express an empty line.
[in]count_commentCount of comments in the array. If 0, the array is expected to be NULL terminated and function will traverse array until its end.
[in]positionA constant that specifies the way the section should be added. For more information see "disposition constants" section of the collection (collection.h) interface. The value is used only in the add operation so see the explanation in the "insert" paragraph. Since duplicate sections are not allowed any constants that request addition of a duplicate will cause function to return an error.
[in]other_sectionUsed in conjunction with position constant. In some cases it is convenient to add a section that is immediately before or after another section. While position defines where it should be added, this parameter defines the section to relate to.
[in]idxIndex, allows treating set of sections as an array and add Nth section.
Returns
0 - Success.
EEXIST - Section already exists.
ENOSYS - Unknown position value.
ENOMEM - No memory to add value.
EINVAL - Invalid argument.
int ini_config_comment_section ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  comments[],
size_t  count_comment 
)

Function to update a comment for a section.

Function finds a section and updates or removes its comment.

Parameters
[in]ini_configConfiguration object to modify.
[in]sectionName of the section to change the comment for.
[in]commentsArray of comments. Can be NULL if no comment is needed for the section. It is expected that comment lines start with the correct comment symbol. Function does not check this. Use empty string to express an empty line.
[in]count_commentCount of comments in the array. If 0 the array is expected to be NULL terminated and function will traverse array until its end.
Returns
0 - Success.
ENOENT - Section is not found.
ENOMEM - No memory to add value.
EINVAL - Invalid argument.
int ini_config_rename_section ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  newname 
)

Function to rename a section.

Function finds a section and renames it.

Parameters
[in]ini_configConfiguration object to modify.
[in]sectionName of the section to find.
[in]newnameNew section name.
Returns
0 - Success.
ENOENT - Section is not found.
ENOMEM - No memory to add value.
EINVAL - Invalid argument.
int ini_config_delete_section_by_name ( struct ini_cfgobj *  ini_config,
const char *  section 
)

Function to delete a section by name.

Function is a convenience wrapper around ini_config_delete_section_by_position function.

Parameters
[in]ini_configConfiguration object to modify.
[in]sectionName of the section to delete.
Returns
0 - Success.
ENOENT - Section is not found.
ENOMEM - No memory to add value.
EINVAL - Invalid argument.
int ini_config_delete_section_by_position ( struct ini_cfgobj *  ini_config,
int  position,
const char *  section,
int  idx 
)

Function to delete a section by position or name.

Function allows removing a specific section by its relative position in the list of sections or by its name.

Parameters
[in]ini_configConfiguration object to modify.
[in]positionA constant that specifies the way the section should be deleted. For more information see "disposition constants" section of the collection interface. The value is used only in delete operation so see the explanation in the "delete" paragraph. There can't be duplicate sections. However function respects all of the listed constants. To find and delete a particular section one can use COL_DSP_FIRSTDUP constant. One should just expect that there is only one instance of every section if any.
[in]sectionUsed in conjunction with position constant. In some cases it is convenient to add a section immediately before or after another value. While position defines where it should be added, this parameter defines the section to relate to.
[in]idxIndex of the position. For example one can specify that the third section should be deleted.
Returns
0 - Success.
ENOENT - Section is not found.
ENOMEM - No memory to add value.
EINVAL - Invalid argument.
int ini_config_add_str_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
const char *  value,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to a add string value to a particular section.

Depending on the flags function adds, or deletes and adds, or just modifies the configuration value stored in the configuration object.

NOTE: all other ini_config_add_xxx_value functions are implemented as wrappers around this function so they have the same behavior and logic.

Parameters
[in]ini_configConfiguration object to modify.
[in]sectionName of the section to modify.
[in]keyKey of the value to add or modify.
[in]valueString that represents the value.
[in]commentsArray of comments. Can be NULL if no comment is needed for the section. It is expected that comment lines start with the correct comment symbol. Function does not check this. Use empty string to express an empty line.
[in]count_commentCount of comments in the array. If 0, the array is expected to be NULL terminated and function will traverse array until its end.
[in]borderThe boundary the value should be wrapped at. The usual value is 80 characters.
[in]positionA constant that specifies the way the value should be added. For more information see "disposition constants" section of the collection interface. The value is used only in add operation so see the explanation in the "insert" paragraph.
[in]other_keyUsed in conjunction with 'position' constant. In some cases it is convenient to add a value that should be placed immediately before or after another value. While position defines where it should be added, this parameter defines the key to relate to.
[in]idxIndex in the whole section or among duplicates. For example one can specify that the value should be added as a third duplicate. This is convenient if INI file allows duplicate keys.
[in]flagsThese constants define the main behavior of the function. The function can thus be used to build configuration object from scratch (in this case no checks would be needed), to modify a specific key which can be identified by index among duplicate keys in the same section. For more information see Flags used in add_xxx_value functions.
Returns
0 - Success.
EEXIST - The value already exists.
ENOENT - The value not found.
ENOSYS - Unknown flag or position value.
ENOMEM - No memory to add value.
EINVAL - Invalid argument.
int ini_config_add_int_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
int  value,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add an integer value to a particular section.

Function is similar to ini_config_add_str_value except it uses an integer argument for the value input.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_add_long_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
long  value,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add a long value to a particular section.

Function is similar to ini_config_add_str_value except it uses a long integer argument for the value input.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_add_ulong_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
unsigned long  value,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add an unsigned long value to a particular section.

Function is similar to ini_config_add_str_value except it uses an unsigned long integer argument for the value input.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_add_unsigned_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
unsigned  value,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add an unsigned value to a particular section.

Function is similar to ini_config_add_str_value except it uses an unsigned argument for the value input.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_add_int32_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
int32_t  value,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add an int32 value to a particular section.

Function is similar to ini_config_add_str_value except it uses an int32 argument for the value input.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_add_uint32_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
uint32_t  value,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add an uint32 value to a particular section.

Function is similar to ini_config_add_str_value except it uses an uint32 argument for the value input.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_add_int64_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
int64_t  value,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add an int64 value to a particular section.

Function is similar to ini_config_add_str_value except it uses an int64 argument for the value input.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_add_uint64_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
uint64_t  value,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add an uint64 value to a particular section.

Function is similar to ini_config_add_str_value except it uses an uint64 argument for the value input.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_add_double_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
double  value,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add a double value to a particular section.

Function is similar to ini_config_add_str_value except it uses a double argument for the value input.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_add_bin_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
void *  value,
size_t  value_len,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add a binary value to a particular section.

Binary values are represented by a HEX string where two HEX digits represent one byte of the source data. The value is surrounded by a pair of single quotes.

Function is similar to ini_config_add_str_value except it uses a void argument for the value input. The length of the data is specified by by the value_len argument.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_add_const_str_arr_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
const char *  value_str_arr[],
size_t  count_str,
char  sep,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add a value that consists of an array of constant strings to a particular section.

Function is similar to ini_config_add_str_value except it uses a string array argument and a count for the value input.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_add_str_arr_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
char *  value_str_arr[],
size_t  count_str,
char  sep,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add a value that consists of an array of strings to a particular section.

Function is similar to ini_config_add_str_value except it uses a string array argument and a count for the value input.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_add_int_arr_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
int *  value_int_arr,
size_t  count_int,
char  sep,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add a value that consists of an array of integers to a particular section.

Function is similar to ini_config_add_str_value except it uses a integer array argument and a count for the value input.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_add_long_arr_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
long *  value_long_arr,
size_t  count_long,
char  sep,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add a value that consists of an array of long integers to a particular section.

Function is similar to ini_config_add_str_value except it uses a long integer array argument and a count for the value input.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_add_double_arr_value ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
double *  value_double_arr,
size_t  count_double,
char  sep,
const char *  comments[],
size_t  count_comment,
int  border,
int  position,
const char *  other_key,
int  idx,
enum INI_VA  flags 
)

Function to add a value that consists of an array of doubles to a particular section.

Function is similar to ini_config_add_str_value except it uses a double array argument and a count for the value input.

For logic, behavior and return values see ini_config_add_str_value.

int ini_config_delete_value ( struct ini_cfgobj *  ini_config,
const char *  section,
int  position,
const char *  key,
int  idx 
)

Function to delete a value.

Function deletes a value specified either by key or by position. For example the caller can remove first or last key of the section as well as first, last or specific instance of a specific key. If key is searched by index and index is out of range the function would return ENOENT indicating that specifically requested key is not found.

Parameters
[in]ini_configConfiguration object to modify.
[in]sectionName of the section to remove the key from.
[in]positionA constant that specifies the way the key should be removed. For more information see "disposition constants" section of the collection interface, and specifically the "delete" paragraph.
[in]keyUsed in conjunction with 'position' constant. Depending on the value of the position argument the key argument can specify the key to delete or the key that the delete operation should be relative to.
[in]idxIndex of duplicates. For example one can specify that he wants to delete the third duplicate of a specific key. If there are less duplicates, i.e. the index is out of range, the function will return ENOENT.
Returns
0 - Value was removed.
ENOENT - The value not found.
int ini_config_update_comment ( struct ini_cfgobj *  ini_config,
const char *  section,
const char *  key,
const char *  comments[],
size_t  count_comment,
int  idx 
)

Function to update a comment.

Function can be used to find and modify a comment for a specific key in a specific section.

Parameters
[in]ini_configConfiguration object to modify.
[in]sectionName of the section to find the key.
[in]keyThe key to find.
[in]commentsThe array of comments. Can be NULL. If NULL, the existing comment will be removed if any. The comment lines are expected to start with a standard comment symbol. The function does not check this. Use empty string to express an empty line.
[in]count_commentCount of comments. If 0 the comment is constructed using array of strings above. It is expected to be NULL terminated.
[in]idxIndex of duplicates. For example one can specify that he wants to find the third duplicate of a specific key. If there are less duplicates, i.e. the index is out of range, the function will return ENOENT.
Returns
0 - Value was removed.
ENOENT - The value not found.