Core interface functions


Functions
int	ini_config_create (struct ini_cfgobj **ini_config)
	Create a configuration object.
void	ini_config_destroy (struct ini_cfgobj *ini_config)
	Destroy a configuration object.
void	ini_config_clean_state (struct ini_cfgobj *ini_config)
	Flush cached search data.
int	ini_config_file_open (const char filename, uint32_t metadata_flags, struct ini_cfgfile *file_ctx)
	Create a configuration file object.
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.
void	ini_config_file_close (struct ini_cfgfile *file_ctx)
	Close configuration file after parsing.
int	ini_config_file_reopen (struct ini_cfgfile file_ctx_in, struct ini_cfgfile *file_ctx_out)
	Reopen the configuration file.
void	ini_config_file_destroy (struct ini_cfgfile *file_ctx)
	Close configuration file and free all data.
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.
int	ini_config_change_access (struct ini_cfgfile file_ctx, struct access_check new_access)
	Change permissions and ownership of the file.
int	ini_config_save (struct ini_cfgfile file_ctx, struct access_check new_access, struct ini_cfgobj *ini_config)
	Save configuration in a file.
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.
enum index_utf_t	ini_config_get_bom (struct ini_cfgfile *file_ctx)
	Return the encoding indicator.
int	ini_config_set_bom (struct ini_cfgfile *file_ctx, enum index_utf_t bom)
	Set the encoding indicator.
unsigned	ini_config_error_count (struct ini_cfgobj *ini_config)
	Check parsing errors count.
int	ini_config_get_errors (struct ini_cfgobj ini_config, char **errors)
	Get array of parsing errors.
void	ini_config_free_errors (char **errors)
	Free array of parsing errors.
void	ini_config_print_errors (FILE file, char *error_list)
	Print errors to a file.
const char *	ini_config_get_filename (struct ini_cfgfile *file_ctx)
	Get the fully resolved file name.
struct stat *	ini_config_get_stat (struct ini_cfgfile *file_ctx)
	Get pointer to collected stat data.
void	ini_config_file_print (struct ini_cfgfile *file_ctx)
	Print file context.
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.
int	ini_config_changed (struct ini_cfgfile file_ctx1, struct ini_cfgfile file_ctx2, int *changed)
	Check if file has changed.
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.
int	ini_config_copy (struct ini_cfgobj ini_config, struct ini_cfgobj *ini_new)
	Create a copy of the configuration object.
int	ini_config_merge (struct ini_cfgobj first, struct ini_cfgobj second, uint32_t collision_flags, struct ini_cfgobj **result)
	Merge two configuration objects.
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.
int	ini_config_set_wrap (struct ini_cfgobj *ini_config, uint32_t boundary)
	Set the folding boundary.
int	ini_config_serialize (struct ini_cfgobj ini_config, struct simplebuffer sbobj)
	Serialize configuration object.

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

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_config Configuration 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_config Configuration 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_config Configuration 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]`	filename	Name 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_flags	Flags that specify what additional data if any needs to be collected about the ini file.
`[out]`	file_ctx	Configuration 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_buf	In memory configuration data. Needs to be NULL terminated.
`[in]`	data_len	Length of memory data not including terminating NULL.
`[out]`	file_ctx	Configuration 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_ctx Configuration 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_in	Original configuration file object.
`[out]`	file_ctx_out	A 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_ctx Configuration file object.

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_ctx	File context of the file to backup.
`[in]`	backup_dir	Path to backup directory. Can be NULL.
`[in]`	backup_tpl	File name template with d placeholder.
`[in]`	backup_access	Optional access overwrite structure. See access_check for more details.
`[in]`	max_num	Maximum 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.

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_ctx	File context of the file to change access.
`[in]`	new_access	Structure 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.

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.

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_ctx	File context to use for saving.
`[in]`	filename	Name 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_access	Structure that defines what access should be set on the file. See access_check for more details.
`[in]`	ini_config	Configuration to save.

Returns:: 0 - Success.
EINVAL - Invalid parameter.

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

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_ctx File context.

Function returns the constant of type enum index_utf_t.

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_ctx	File context.
`[in]`	bom	BOM type indicator to set.

Returns:: 0 - Success.
EINVAL - Invalid parameter.

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_config Configuration 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_config	Configuration object.
`[out]`	errors	Array 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] errors Array 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]`	file	File or stream to send errors to.
`[in]`	error_list	Array 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_ctx Configuration file object.

Returns:: Full file name.

struct stat* ini_config_get_stat ( struct ini_cfgfile * file_ctx ) [read]

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_ctx Configuration 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_ctx Configuration 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_ctx	Configuration file object.
`[in]`	flags	Define what to check. One can check file permissions with mask, uid, and gid of the file.
`[in]`	uid	Expected uid of the file.
`[in]`	gid	Expected gid of the file.
`[in]`	mode	Expected mode of the file.
`[in]`	mask	Mask 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_ctx1	First configuration file object.
`[in]`	file_ctx2	Second configuration file object.
`[out]`	changed	A 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_ctx	Configuration file object.
`[in]`	error_level	Flags that control actions in case of parsing error.
`[in]`	collision_flags	Flags that control handling of the duplicate sections or keys.
`[in]`	parse_flags	Flags that control parsing process, for example how to handle spaces at the beginning of the line.
`[out]`	ini_config	Configuration 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_config	Original configuration object.
`[out]`	ini_new	A 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]`	first	A base object the other object will be merged with.
`[in]`	second	The object that will be merged to the first one.
`[in]`	collision_flags	Flags that control handling of the duplicate sections or keys.
`[out]`	result	A new configuration object, the result of the merge.

Returns:

0 - Success.

EINVAL - Invalid parameter.

ENOMEM - No memory.

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.

Parameters:

`[in]`	base_cfg	A configuration object that will be augmented.
`[in]`	path	Path to a directory where configuration snippets will be read from.
`[in]`	patterns	List of regular expressions that the name of a snippet file has to match to be considered for merge.
`[in]`	sections	List 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_perm	Pointer to structure that holds criteria for the access check.
`[in]`	error_level	Flags that control actions in case of parsing error in a snippet file.
`[in]`	collision_flags	These 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_flags	Flags that control parsing process, for example how to handle spaces at the beginning of the line.
`[in]`	merge_flags	Flags 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_cfg	A new configuration object, the result of the merge.
`[out]`	error_list	List of strings that contains all encountered errors. It can be NULL, in this case list of errors is not populated.
`[out]`	success_list	List 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.

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_config	Configuration object.
`[in]`	boundary	Wrapping 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_config	Configuration object.
`[out]`	sbobj	Serialized configuration.

Returns:

0 - Success.

EINVAL - Invalid parameter.

ENOMEM - No memory.