libini_config  0.4.0
 All Functions Enumerations Enumerator Groups Pages
Functions
Core interface functions

Functions

int ini_config_create (struct ini_cfgobj **ini_config)
 Create a configuration object. More...
 
void ini_config_destroy (struct ini_cfgobj *ini_config)
 Destroy a configuration object. More...
 
void ini_config_clean_state (struct ini_cfgobj *ini_config)
 Flush cached search data. More...
 
int ini_config_file_open (const char *filename, uint32_t metadata_flags, struct ini_cfgfile **file_ctx)
 Create a configuration file object. More...
 
int ini_config_file_from_mem (void *data_buf, uint32_t data_len, struct ini_cfgfile **file_ctx)
 Create a configuration file object using memory buffer. More...
 
void ini_config_file_close (struct ini_cfgfile *file_ctx)
 Close configuration file after parsing. More...
 
int ini_config_file_reopen (struct ini_cfgfile *file_ctx_in, struct ini_cfgfile **file_ctx_out)
 Reopen the configuration file. More...
 
void ini_config_file_destroy (struct ini_cfgfile *file_ctx)
 Close configuration file and free all data. More...
 
unsigned ini_config_error_count (struct ini_cfgobj *ini_config)
 Check parsing errors count. More...
 
int ini_config_get_errors (struct ini_cfgobj *ini_config, char ***errors)
 Get array of parsing errors. More...
 
void ini_config_free_errors (char **errors)
 Free array of parsing errors. More...
 
void ini_config_print_errors (FILE *file, char **error_list)
 Print errors to a file. More...
 
const char * ini_config_get_filename (struct ini_cfgfile *file_ctx)
 Get the fully resolved file name. More...
 
struct stat * ini_config_get_stat (struct ini_cfgfile *file_ctx)
 Get pointer to collected stat data. More...
 
void ini_config_file_print (struct ini_cfgfile *file_ctx)
 Print file context. More...
 
int ini_config_access_check (struct ini_cfgfile *file_ctx, uint32_t flags, uid_t uid, gid_t gid, mode_t mode, mode_t mask)
 Check file properties. More...
 
int ini_config_changed (struct ini_cfgfile *file_ctx1, struct ini_cfgfile *file_ctx2, int *changed)
 Check if file has changed. More...
 
int ini_config_parse (struct ini_cfgfile *file_ctx, int error_level, uint32_t collision_flags, uint32_t parse_flags, struct ini_cfgobj *ini_config)
 Parse the file and populate a configuration object. More...
 
int ini_config_copy (struct ini_cfgobj *ini_config, struct ini_cfgobj **ini_new)
 Create a copy of the configuration object. More...
 
int ini_config_merge (struct ini_cfgobj *first, struct ini_cfgobj *second, uint32_t collision_flags, struct ini_cfgobj **result)
 Merge two configuration objects. More...
 
int ini_config_set_wrap (struct ini_cfgobj *ini_config, uint32_t boundary)
 Set the folding boundary. More...
 
int ini_config_serialize (struct ini_cfgobj *ini_config, struct simplebuffer *sbobj)
 Serialize configuration object. More...
 

Detailed Description

Functions in this section allow manipulation with the configuration file, parsing data from the configuration file and storing it in a configuration object, merging configuration objects and other operations.

This interface is currently incomplete as it does not allow:

Function Documentation

int ini_config_create ( struct ini_cfgobj **  ini_config)

Create a configuration object.

Allocates an object that will store configuration data. Configuration object is populated by parsing a file.

Parameters
[out]ini_configConfiguration object.
Returns
0 - Success.
EINVAL - Invalid parameter.
ENOMEM - No memory.
void ini_config_destroy ( struct ini_cfgobj *  ini_config)

Destroy a configuration object.

Frees configuration data.

Parameters
[in]ini_configConfiguration object.
void ini_config_clean_state ( struct ini_cfgobj *  ini_config)

Flush cached search data.

Frees cached search data. This will cause any iteration over the same keys to start over.

Parameters
[in]ini_configConfiguration object.
int ini_config_file_open ( const char *  filename,
uint32_t  metadata_flags,
struct ini_cfgfile **  file_ctx 
)

Create a configuration file object.

Create a file object for parsing a configuration file.

A "configuration file object" is different from a "configuration object". The former stores metadata about a file the configuration data is read from, while the latter holds the configuration itself.

Parameters
[in]filenameName or path to the ini file. This argument can contain a short or a fully qualified file name. If a short name is specified the full path will be resolved internally.
[in]metadata_flagsFlags that specify what additional data if any needs to be collected about the ini file.
[out]file_ctxConfiguration file object.
Returns
0 - Success.
EINVAL - Invalid parameter.
ENOMEM - No memory.
int ini_config_file_from_mem ( void *  data_buf,
uint32_t  data_len,
struct ini_cfgfile **  file_ctx 
)

Create a configuration file object using memory buffer.

Create a file object for parsing a configuration file. Configuration will use provided memory instead of the actual file.

A "configuration file object" is different from a "configuration object". The former stores metadata about a file the configuration data is read from, while the latter holds the configuration itself.

Parameters
[in]data_bufIn memory configuration data. Needs to be NULL terminated.
[in]data_lenLength of memory data not including terminating NULL.
[out]file_ctxConfiguration file object.
Returns
0 - Success.
EINVAL - Invalid parameter.
ENOMEM - No memory.
void ini_config_file_close ( struct ini_cfgfile *  file_ctx)

Close configuration file after parsing.

Closes file but keeps the context. File can be reopened and reread using ini_config_file_reopen function.

Parameters
[in]file_ctxConfiguration file object.
int ini_config_file_reopen ( struct ini_cfgfile *  file_ctx_in,
struct ini_cfgfile **  file_ctx_out 
)

Reopen the configuration file.

Creates a new file object from the original one. The file configuration objects then can be compared to determine whether the file actually changed.

Parameters
[in]file_ctx_inOriginal configuration file object.
[out]file_ctx_outA new configuration file object.
Returns
0 - Success.
EINVAL - Invalid parameter.
ENOMEM - No memory.
void ini_config_file_destroy ( struct ini_cfgfile *  file_ctx)

Close configuration file and free all data.

Closes file and frees the context.

Parameters
[in]file_ctxConfiguration file object.
unsigned ini_config_error_count ( struct ini_cfgobj *  ini_config)

Check parsing errors count.

Query the configuration file object about how many parsing errors were found during last parsing operation.

Parameters
[in]ini_configConfiguration object.
Returns
Number of errors.
int ini_config_get_errors ( struct ini_cfgobj *  ini_config,
char ***  errors 
)

Get array of parsing errors.

Function returns a newly allocated array of strings that should be later freed by the ini_config_free_errors function. Array can be referenced as a normal array of strings. The NULL entry indicates the end of the array.

Parameters
[in]ini_configConfiguration object.
[out]errorsArray of error strings.
Returns
0 - Success.
EINVAL - Invalid parameter.
ENOMEM - No memory.
void ini_config_free_errors ( char **  errors)

Free array of parsing errors.

Free array of parsing errors previously allocated by using ini_config_get_errors function.

Parameters
[in]errorsArray of error strings.
void ini_config_print_errors ( FILE *  file,
char **  error_list 
)

Print errors to a file.

Prints array of parsing errors previously allocated by using ini_config_get_errors function into a provided file.

Parameters
[in]fileFile or stream to send errors to.
[in]error_listArray of error strings.
const char* ini_config_get_filename ( struct ini_cfgfile *  file_ctx)

Get the fully resolved file name.

Returns the full name to the configuration file that was resolved by the library.

Parameters
[in]file_ctxConfiguration file object.
Returns
Full file name.
struct stat* ini_config_get_stat ( struct ini_cfgfile *  file_ctx)

Get pointer to collected stat data.

Returns the pointer to the internal stat structure. If stat data was not collected when the file was open function would return NULL.

Parameters
[in]file_ctxConfiguration file object.
Returns
Pointer to the stat structure.
void ini_config_file_print ( struct ini_cfgfile *  file_ctx)

Print file context.

Function is useful for debugging purposes only.

Parameters
[in]file_ctxConfiguration file object.
int ini_config_access_check ( struct ini_cfgfile *  file_ctx,
uint32_t  flags,
uid_t  uid,
gid_t  gid,
mode_t  mode,
mode_t  mask 
)

Check file properties.

Before parsing it makes sense to make sure that the file you are trying to read is properly owned and has proper permissions.

Parameters
[in]file_ctxConfiguration file object.
[in]flagsDefine what to check. One can check file permissions with mask, uid, and gid of the file.
[in]uidExpected uid of the file.
[in]gidExpected gid of the file.
[in]modeExpected mode of the file.
[in]maskMask to use in the mode check. Mask is always adjusted to include at least S_IRWXU, S_IRWXG and S_IRWXO
Returns
0 - Success.
EINVAL - Invalid parameter.
EACCES - File attributes do no match expectations.
int ini_config_changed ( struct ini_cfgfile *  file_ctx1,
struct ini_cfgfile *  file_ctx2,
int *  changed 
)

Check if file has changed.

Compares two configuration file objects. Determines if two objects are different by comparing:

  • time stamp
  • device ID
  • i-node

Function can be used to check if the file has changed since last time the it was read.

Note: If the file was deleted and quickly re-created the kernel seems to restore the same i-node. The stat structure keeps time granularity of seconds. As a result if the file is quickly recreated with the same contents like in the unit test the check would assume that file did not change. This is why the unit test has a one second delay.

Parameters
[in]file_ctx1First configuration file object.
[in]file_ctx2Second configuration file object.
[out]changedA value will be set to 0 if the objects are same and to 1 if they are different.
Returns
0 - Success.
EINVAL - Invalid parameter.
EACCES - File attributes do no match expectations.
int ini_config_parse ( struct ini_cfgfile *  file_ctx,
int  error_level,
uint32_t  collision_flags,
uint32_t  parse_flags,
struct ini_cfgobj *  ini_config 
)

Parse the file and populate a configuration object.

Function parses the file. It is assumed that the configuration object was just created. Using a non empty configuration object in a parsing operation would fail with EINVAL.

Parameters
[in]file_ctxConfiguration file object.
[in]error_levelFlags that control actions in case of parsing error.
[in]collision_flagsFlags that control handling of the duplicate sections or keys.
[in]parse_flagsFlags that control parsing process, for example how to handle spaces at the beginning of the line.
[out]ini_configConfiguration object.
Returns
0 - Success.
EINVAL - Invalid parameter.
ENOMEM - No memory.
int ini_config_copy ( struct ini_cfgobj *  ini_config,
struct ini_cfgobj **  ini_new 
)

Create a copy of the configuration object.

Function creates a deep copy of all the configuration data. Error list created during parsing is not copied over.

Parameters
[in]ini_configOriginal configuration object.
[out]ini_newA new configuration object.
Returns
0 - Success.
EINVAL - Invalid parameter.
ENOMEM - No memory.
int ini_config_merge ( struct ini_cfgobj *  first,
struct ini_cfgobj *  second,
uint32_t  collision_flags,
struct ini_cfgobj **  result 
)

Merge two configuration objects.

Function merges configuration objects and creates a new resulting object out of the two. IMPORTANT: Use same collision flags for reading of the files and then merging. Mixing the flags would lead to strange results that would be hard to debug.

Parameters
[in]firstA base object the other object will be merged with.
[in]secondThe object that will be merged to the first one.
[in]collision_flagsFlags that control handling of the duplicate sections or keys.
[out]resultA new configuration object, the result of the merge.
Returns
0 - Success.
EINVAL - Invalid parameter.
ENOMEM - No memory.
int ini_config_set_wrap ( struct ini_cfgobj *  ini_config,
uint32_t  boundary 
)

Set the folding boundary.

Set the folding boundary for multiline values. Use before serializing and saving to a file if the default boundary of 80 characters does not work for you.

Parameters
[in]ini_configConfiguration object.
[in]boundaryWrapping boundary.
Returns
0 - Success.
EINVAL - Invalid parameter.
int ini_config_serialize ( struct ini_cfgobj *  ini_config,
struct simplebuffer *  sbobj 
)

Serialize configuration object.

Serialize configuration object into provided buffer. Use buffer object functions to manipulate or save the buffer to a file/stream.

Parameters
[in]ini_configConfiguration object.
[out]sbobjSerialized configuration.
Returns
0 - Success.
EINVAL - Invalid parameter.
ENOMEM - No memory.