libini_config  0.6.0
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...
 
int ini_config_file_backup (struct ini_cfgfile *file_ctx, const char *backup_dir, const char *backup_tpl, struct access_check *backup_access, unsigned max_num)
 Save configuration in a backup configuration file. More...
 
int ini_config_change_access (struct ini_cfgfile *file_ctx, struct access_check *new_access)
 Change permissions and ownership of the file. More...
 
int ini_config_save (struct ini_cfgfile *file_ctx, struct access_check *new_access, struct ini_cfgobj *ini_config)
 Save configuration in a file. More...
 
int ini_config_save_as (struct ini_cfgfile *file_ctx, const char *filename, struct access_check *new_access, struct ini_cfgobj *ini_config)
 Save configuration with a new name. More...
 
enum index_utf_t ini_config_get_bom (struct ini_cfgfile *file_ctx)
 Return the encoding indicator. More...
 
int ini_config_set_bom (struct ini_cfgfile *file_ctx, enum index_utf_t bom)
 Set the encoding indicator. 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...
 
const 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_augment (struct ini_cfgobj *base_cfg, const char *path, const char *patterns[], const char *sections[], struct access_check *check_perm, int error_level, uint32_t collision_flags, uint32_t parse_flags, uint32_t merge_flags, struct ini_cfgobj **result_cfg, struct ref_array **error_list, struct ref_array **success_list)
 Augment configuration. 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.

For functions to create or alter configuration object in memory see API to create and modify configuration objects.

Function Documentation

◆ ini_config_create()

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.

◆ ini_config_destroy()

void ini_config_destroy ( struct ini_cfgobj *  ini_config)

Destroy a configuration object.

Frees configuration data.

Parameters
[in]ini_configConfiguration object.

◆ ini_config_clean_state()

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.

◆ ini_config_file_open()

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.

◆ ini_config_file_from_mem()

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.

◆ ini_config_file_close()

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.

◆ ini_config_file_reopen()

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.

◆ ini_config_file_destroy()

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.

◆ ini_config_file_backup()

int ini_config_file_backup ( struct ini_cfgfile *  file_ctx,
const char *  backup_dir,
const char *  backup_tpl,
struct access_check backup_access,
unsigned  max_num 
)

Save configuration in a backup configuration file.

Creates a backup version of the data in a given configuration file. It is expected that file context was created by some open or reopen function first. Then the caller can make this call to save the data aside before parsing the configuration file and making changes to it.

The caller can specify a backup directory to save the file in. If directory is not specified then a current working directory will be used. If the directory is invalid or caller does not have access to it an error will be returned.

>The template specifies the file name to use for the backup. >For example:

my_file.conf.d.save my_filed.conf.bak >The template can contain only one 'd' placeholder. This placeholder

will be replaced by a number. If previously created backup files are found in the given directory. The function will start with 1 and will try to find an available unused file name in the given directory up until it reaches the limit specified in the max_num argument. Function will return EEXIST if it runs out of attempts to save the file.

The caller can optionally pass an access structure. The access structure would specify what mode and ownership to use for the newly created file. If the access structure is not specified the access data of the original file context will be used. If file object does not have stats explicitly read at the time when the object is created then the stats will be collected but not saved. If the file was a memory mapped file and no access structure is passed in, the function will use effective UID and GID of the running process and mode will be set to: S_IFREG | S_IRUSR | S_IWUSR

Parameters
[in]file_ctxFile context of the file to backup.
[in]backup_dirPath to backup directory. Can be NULL.
[in]backup_tplFile name template with d placeholder.
[in]backup_accessOptional access overwrite structure. See access_check for more details.
[in]max_numMaximum number of retries to try to create a specific backup file.
Returns
0 - Success.
EINVAL - Invalid parameter.
EIXIST - All possible backup file names are already taken.
ENOMEM - No memory.

Function can return other errors that standard libc functions line open, chmod, and chown return.

◆ ini_config_change_access()

int ini_config_change_access ( struct ini_cfgfile *  file_ctx,
struct access_check new_access 
)

Change permissions and ownership of the file.

Function changes access mode and permissions of the file associated with the given context. If there is no file associated with the context because the context is created using a memory buffer, then the function will return an error EINVAL.

Parameters
[in]file_ctxFile context of the file to change access.
[in]new_accessStructure that defines what access should be set on the file. See access_check for more details.
Returns
0 - Success.
EINVAL - Invalid parameter.

Function can return other errors that standard chmod and chown functions return.

◆ ini_config_save()

int ini_config_save ( struct ini_cfgfile *  file_ctx,
struct access_check new_access,
struct ini_cfgobj *  ini_config 
)

Save configuration in a file.

Function is a wrapper around ini_config_save_as with argument filename as NULL.

For more information see ini_config_save_as.

◆ ini_config_save_as()

int ini_config_save_as ( struct ini_cfgfile *  file_ctx,
const char *  filename,
struct access_check new_access,
struct ini_cfgobj *  ini_config 
)

Save configuration with a new name.

Function uses an existing file context but a new file name. The file context will be used to perform operation to save file. By default the ownership, mode and BOM of the new file will be derived from the existing context. The rest of the context will be reinitialized. Configuration will be serialized and saved in the file using encoding specified by BOM type. The BOM prefix will also be added if needed. After saving the file the function initializes the context and reads the file back. At this moment the file context is ready for the parsing again.

Parameters
[in]file_ctxFile context to use for saving.
[in]filenameName of the file to save into. If NULL the file name of the context will be used. If the context was originally created as a memory mapped configuration buffer and filename is NULL the function will return error EINVAL.
[in]new_accessStructure that defines what access should be set on the file. See access_check for more details.
[in]ini_configConfiguration to save.
Returns
0 - Success.
EINVAL - Invalid parameter.

Function can return other errors that standard open, chmod and chown functions return.

◆ ini_config_get_bom()

enum index_utf_t ini_config_get_bom ( struct ini_cfgfile *  file_ctx)

Return the encoding indicator.

When the file object is created the configuration data is inspected for encoding indicator called BOM. This function returns a constant that indicates what type of BOM was detected.

Parameters
[in]file_ctxFile context.

Function returns the constant of type enum index_utf_t.

◆ ini_config_set_bom()

int ini_config_set_bom ( struct ini_cfgfile *  file_ctx,
enum index_utf_t  bom 
)

Set the encoding indicator.

When the file object is created the configuration data is inspected for encoding indicator called BOM. The BOM indicator is recorded in the file object and used when the file is saved. If the caller wants to change the encoding before saving he can use this function to alter the BOM type.

Parameters
[in]file_ctxFile context.
[in]bomBOM type indicator to set.
Returns
0 - Success.
EINVAL - Invalid parameter.

◆ ini_config_error_count()

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.

◆ ini_config_get_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.

◆ ini_config_free_errors()

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.

◆ ini_config_print_errors()

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.

◆ ini_config_get_filename()

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.

◆ ini_config_get_stat()

const 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.

◆ ini_config_file_print()

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.

◆ ini_config_access_check()

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.

◆ ini_config_changed()

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.

◆ ini_config_parse()

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.

◆ ini_config_copy()

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.

◆ ini_config_merge()

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.

◆ ini_config_augment()

int ini_config_augment ( struct ini_cfgobj *  base_cfg,
const char *  path,
const char *  patterns[],
const char *  sections[],
struct access_check check_perm,
int  error_level,
uint32_t  collision_flags,
uint32_t  parse_flags,
uint32_t  merge_flags,
struct ini_cfgobj **  result_cfg,
struct ref_array **  error_list,
struct ref_array **  success_list 
)

Augment configuration.

Function merges the main configuration file with the configuration file snippets read from a specified directory ordered according to the locale setting.

Parameters
[in]base_cfgA configuration object that will be augmented.
[in]pathPath to a directory where configuration snippets will be read from.
[in]patternsList of regular expressions that the name of a snippet file has to match to be considered for merge.
[in]sectionsList of regular expressions that the section names in the snippet file need to match. If file contains sections that do not match any patterns the file is skipped and error is recorded.
[in]check_permPointer to structure that holds criteria for the access check.
[in]error_levelFlags that control actions in case of parsing error in a snippet file.
[in]collision_flagsThese flags control how the potential collisions between keys and sections within the snippet file will be handled. For more information see collision flag definitions.
[in]parse_flagsFlags that control parsing process, for example how to handle spaces at the beginning of the line.
[in]merge_flagsFlags that control handling of the duplicate sections or keys during merging of the snippets. They are different from the collision flags because duplicate sections and keys inside are snippets most likely will be handled as 'last value wins' while during merge the attempt to overwrite a specific section might be treated as an error.
[out]result_cfgA new configuration object, the result of the merge.
[out]error_listList of strings that contains all encountered errors. It can be NULL, in this case list of errors is not populated.
[out]success_listList of strings that contains file names of snippets that were successfully merged. It can be NULL, in this case list of files is not populated.
Returns
0 - Success.
EINVAL - Invalid parameter.
ENOMEM - No memory.

◆ ini_config_set_wrap()

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.

◆ ini_config_serialize()

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.