libini_config
0.6.1
|
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. More...
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... | |
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.
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.
[out] | ini_config | Configuration object. |
void ini_config_destroy | ( | struct ini_cfgobj * | ini_config | ) |
Destroy a configuration object.
Frees configuration data.
[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.
[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.
[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. |
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.
[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. |
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.
[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.
[in] | file_ctx_in | Original configuration file object. |
[out] | file_ctx_out | A new configuration file object. |
void ini_config_file_destroy | ( | struct ini_cfgfile * | file_ctx | ) |
Close configuration file and free all data.
Closes file and frees the context.
[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
[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. |
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.
[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. |
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.
[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. |
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.
[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.
[in] | file_ctx | File context. |
[in] | bom | BOM type indicator to set. |
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.
[in] | ini_config | Configuration object. |
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.
[in] | ini_config | Configuration object. |
[out] | errors | Array of error strings. |
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.
[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.
[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.
[in] | file_ctx | Configuration file object. |
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.
[in] | file_ctx | Configuration file object. |
void ini_config_file_print | ( | struct ini_cfgfile * | file_ctx | ) |
Print file context.
Function is useful for debugging purposes only.
[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.
[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 |
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:
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.
[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. |
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.
[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. |
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.
[in] | ini_config | Original configuration object. |
[out] | ini_new | A new 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.
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.
[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. |
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.
[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. These use POSIX Basic Regular Expressions. |
[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. These use POSIX Basic Regular Expressions. |
[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. |
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.
[in] | ini_config | Configuration object. |
[in] | boundary | Wrapping boundary. |
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.
[in] | ini_config | Configuration object. |
[out] | sbobj | Serialized configuration. |