In the context of the Configuration module, a config file consists of sections and parameter assignements.
A section begins with the name of the section - which can't contain whitespaces - is followed by a '{'
(which must be on a line by itself) and continues until the corresponding '}'
is found.
Sections can contain other sections or parameter assignements of the form:
name value
The file is line-based, that is, each newline-terminated line represents either a section name or a parameter assignement.
Comments start from the hash sign ('#'
) and eat all the characters they encounter until the end of the line.
Section and parameter names are case sensitive.
Leading and trailing whitespace in section and parameter names is irrelevant. Leading and trailing whitespace in a parameter value is discarded. Internal whitespace within a parameter value is retained verbatim.
As a corollary, any line containing only whitespace is ignored.
The value in parameters is always a string (no quotes needed) whose case is preserved.
It is possible to use variable substitution which allows to define a symbol name to be replaced by an arbitrary text string, with the classic bottom-up scoping.
Also, by means of the "include"
directive it is possible to load other configuration files into the one which is currently parsed.
A simple example follows:
last_name blues
type musician
# elwood's brother
name
{
first joliet
middle jake
last ${last_name} # use substitution
}
address city of chicago
A parameter name can be equivalently expressed through its "qualified name" using the following dotted notation:
# the very same elwood's brother
name.first joliet
name.middle jake
name.last blues
Once you have a well-formed configuration file, you can load it into memory using u_config_load_from_file and then manipulate the corresponding u_config_t object to obtain values of the parameters (keys
) you are interested in via u_config_get_subkey_value and friends, as illustrated in the following example:
u_config_t *top = NULL, *name_sect; const char *first_name, *middle_name, *last_name; // load and parse the configuration file "my.conf" dbg_err_if (u_config_load_from_file("./my.conf", &top)); // get the section whose name is "name" dbg_err_if (u_config_get_subkey(top, "name", &name_sect)); // get values of parameters "first", "middle" and "last" in section "name" first_name = u_config_get_subkey_value(name_sect, "first"); middle_name = u_config_get_subkey_value(name_sect, "middle"); last_name = u_config_get_subkey_value(name_sect, "last"); ... u_config_free(top);
After you have successfully loaded your configuration file, you could modify its values using u_config_set_value as needed, and than save it back to file with u_config_print_to_fp. The loop is closed.
When you're done, don't forget to release the top-level u_config_t object via u_config_free.
Other misc things that may be worth noting:
Data Structures | |
struct | u_config_driver_s |
Configuration loading driver callbacks. More... | |
Typedefs | |
typedef struct u_config_s | u_config_t |
Configuration base type. | |
typedef struct u_config_driver_s | u_config_driver_t |
Configuration loading driver type. | |
Enumerations | |
enum | u_config_walk_t { U_CONFIG_WALK_PREORDER, U_CONFIG_WALK_POSTORDER } |
Configuration tree walking strategies (See u_config_walk). More... | |
Functions | |
int | u_config_sort_children (u_config_t *c, int(*config_cmp)(u_config_t **, u_config_t **)) |
Sort config children. | |
void | u_config_print_to_fp (u_config_t *c, FILE *fp, int lev) |
Print configuration to the given file stream pointer. | |
void | u_config_print (u_config_t *c, int lev) |
Print configuration to stdout . | |
int | u_config_add_child (u_config_t *c, const char *key, u_config_t **pc) |
Add a child node with a given key to the supplied u_config_t object. | |
u_config_t * | u_config_get_child_n (u_config_t *c, const char *key, int n) |
Get the n-th child by a given key. | |
u_config_t * | u_config_get_child (u_config_t *c, const char *key) |
Get a child with a given key. | |
int | u_config_get_subkey_nth (u_config_t *c, const char *subkey, int n, u_config_t **pc) |
Get the n-th configuration object child corresponding to a given subkey. | |
int | u_config_get_subkey (u_config_t *c, const char *subkey, u_config_t **pc) |
Get a child configuration object corresponding to a given subkey. | |
int | u_config_set_value (u_config_t *c, const char *val) |
Assign val to c's key. | |
int | u_config_add_key (u_config_t *c, const char *key, const char *val) |
Append the given key/value pair into a config object. | |
int | u_config_set_key (u_config_t *c, const char *key, const char *val) |
Put the given key/value pair into a config object. | |
int | u_config_load_from (u_config_t *c, u_config_gets_t cb, void *arg, int overwrite) |
Load from an opaque data source. | |
int | u_config_load (u_config_t *c, int fd, int overwrite) |
Load a configuration file. | |
int | u_config_load_from_file (const char *file, u_config_t **pc) |
Create a configuration object read from a configuration file. | |
int | u_config_create (u_config_t **pc) |
Create a config object. | |
int | u_config_del_child (u_config_t *c, u_config_t *child) |
Remove a child (and all its sub-children) from a config object. | |
int | u_config_free (u_config_t *c) |
Free a config object and all its children. | |
const char * | u_config_get_key (u_config_t *c) |
Return the key of a config object. | |
const char * | u_config_get_value (u_config_t *c) |
Return the value of a config object. | |
const char * | u_config_get_subkey_value (u_config_t *c, const char *subkey) |
Return the value of a subkey. | |
int | u_config_get_subkey_value_i (u_config_t *c, const char *subkey, int def, int *out) |
Return the value of an integer subkey. | |
int | u_config_get_subkey_value_b (u_config_t *c, const char *subkey, int def, int *out) |
Return the value of a boolean subkey. | |
int | u_config_load_from_drv (const char *uri, u_config_driver_t *drv, int overwrite, u_config_t **pc) |
Load a configuration object using the supplied u_config_driver_t. | |
int | u_config_has_children (u_config_t *c) |
Tell if a given config object has children nodes. | |
int | u_config_save_to_buf (u_config_t *c, char *buf, size_t size) |
Marshall a config object into a memory buffer. | |
int | u_config_load_from_buf (char *buf, size_t len, u_config_t **pc) |
Unmarshall a config object from a memory buffer. | |
void | u_config_walk (u_config_t *c, u_config_walk_t s, void(*cb)(u_config_t *)) |
Traverse the configuration tree. |
enum u_config_walk_t |
int u_config_add_child | ( | u_config_t * | c, | |
const char * | key, | |||
u_config_t ** | pc | |||
) |
Create a child u_config_t object with key key
, attached to the supplied c
.
c | the parent u_config_t object | |
key | the key which will be assigned to the newly created child | |
pc | the newly created child attached to pc |
0 | on success | |
~0 | on failure |
Definition at line 308 of file config.c.
References u_config_create(), and u_strdup().
int u_config_add_key | ( | u_config_t * | c, | |
const char * | key, | |||
const char * | val | |||
) |
Append the given key
, val
pair into the supplied u_config_t object c
.
c | the u_config_t object that is manipulated | |
key | the key to insert | |
val | the value to insert |
0 | on success | |
~0 | on error |
int u_config_create | ( | u_config_t ** | pc | ) |
Create a new u_config_t object. The returned object is completely empty, use u_config_set_key to set its key/value pairs
pc | value-result that will get the new configuration object |
0 | on success | |
~0 | on failure |
Definition at line 644 of file config.c.
References u_config_free(), and u_zalloc().
Referenced by u_config_add_child(), u_config_load_from_buf(), and u_config_load_from_drv().
int u_config_del_child | ( | u_config_t * | c, | |
u_config_t * | child | |||
) |
Remove a child and all its sub-children from a config object.
c | parent u_config_t object | |
child | child to remove |
0 | on success | |
~0 | on failure |
Definition at line 673 of file config.c.
References u_config_free().
int u_config_free | ( | u_config_t * | c | ) |
Free a config object and all its children.
c | configuration object |
0 | on success | |
~0 | on failure |
Definition at line 701 of file config.c.
References u_config_free(), and u_free().
Referenced by u_config_create(), u_config_del_child(), u_config_free(), u_config_load_from_buf(), and u_config_load_from_drv().
u_config_t* u_config_get_child | ( | u_config_t * | c, | |
const char * | key | |||
) |
Get the child with key key
from its parent u_config_t object c
c | the parent u_config_t object | |
key | the key that shall be searched |
NULL
if no child was found Definition at line 362 of file config.c.
References u_config_get_child_n().
Referenced by u_config_get_subkey_nth().
u_config_t* u_config_get_child_n | ( | u_config_t * | c, | |
const char * | key, | |||
int | n | |||
) |
Get the child with key key
at index n
from c
.
c | the parent u_config_t object | |
key | the key that must be searched | |
n | the index for the child object that we are expected to retrieve |
NULL
if no child was found Definition at line 339 of file config.c.
Referenced by u_config_get_child(), u_config_get_subkey_nth(), and u_config_walk().
const char* u_config_get_key | ( | u_config_t * | c | ) |
Return the key string of the supplied u_config_t object c
c | an u_config_t object |
NULL
), and NULL
if c
is NULL
int u_config_get_subkey | ( | u_config_t * | c, | |
const char * | subkey, | |||
u_config_t ** | pc | |||
) |
Get a child config object (actually the first one) corresponding to the given subkey subkey
from parent c
c | the parent u_config_t object | |
subkey | a subkey value | |
pc | the found child (if found) as a result argument |
0 | on success | |
~0 | on error (i.e. no match) |
Definition at line 425 of file config.c.
References u_config_get_subkey_nth().
Referenced by u_config_get_subkey_nth(), u_config_get_subkey_value(), and u_config_set_value().
int u_config_get_subkey_nth | ( | u_config_t * | c, | |
const char * | subkey, | |||
int | n, | |||
u_config_t ** | pc | |||
) |
Get the child config object corresponding to the given subkey subkey
at index n
c | the parent u_config_t object | |
subkey | a subkey value | |
n | the index at which the child object is retrieved | |
pc | a result argument carrying the found object reference if the search was successful |
0 | on success | |
~0 | on error (i.e. no match) |
Definition at line 383 of file config.c.
References u_config_get_child(), u_config_get_child_n(), u_config_get_subkey(), and u_strndup().
Referenced by u_config_get_subkey().
const char* u_config_get_subkey_value | ( | u_config_t * | c, | |
const char * | subkey | |||
) |
Return the value of the child config object whose key is subkey
.
c | configuration object | |
subkey | the key value of the child config object |
NULL
on failure Definition at line 767 of file config.c.
References u_config_get_subkey(), and u_config_get_value().
Referenced by u_config_get_subkey_value_b(), u_config_get_subkey_value_i(), and u_config_set_value().
int u_config_get_subkey_value_b | ( | u_config_t * | c, | |
const char * | subkey, | |||
int | def, | |||
int * | out | |||
) |
Return the bool value of the child config object whose key is subkey
. Recognized bool values are (case insensitive) yes/no
, 1/0
, enable/disable
.
c | configuration object | |
subkey | the key value of the child config object | |
def | the value to return if the key is missing | |
out | on exit will get the bool value of the key |
0 | on success | |
~0 | if the key value is not a bool keyword |
Definition at line 825 of file config.c.
References u_config_get_subkey_value().
int u_config_get_subkey_value_i | ( | u_config_t * | c, | |
const char * | subkey, | |||
int | def, | |||
int * | out | |||
) |
Return the integer value (u_atoi is used for conversion) of the child config object whose key is subkey
.
c | configuration object | |
subkey | the key value of the child config object | |
def | the value to return if the key is missing | |
out | on exit will get the integer value of the key |
0 | on success | |
~0 | if the key value is not an int |
Definition at line 792 of file config.c.
References u_atoi(), and u_config_get_subkey_value().
const char* u_config_get_value | ( | u_config_t * | c | ) |
Return the value string of a config object.
c | configuration object |
NULL
), and NULL
if c
is NULL
Definition at line 750 of file config.c.
Referenced by u_config_get_subkey_value().
int u_config_has_children | ( | u_config_t * | c | ) |
Tell if the supplied u_config_t object c
has at least one child node
c | an u_config_t object |
1 | if answer is yes | |
0 | if answer is no |
Definition at line 926 of file config.c.
Referenced by u_config_print_to_fp(), and u_config_walk().
int u_config_load | ( | u_config_t * | c, | |
int | fd, | |||
int | overwrite | |||
) |
Fill a config object with key/value pairs loaded from the configuration file linked to the file descriptor fd
. If overwrite
is not zero, values of keys with the same name will overwrite previous values, otherwise new keys with the same name will be added.
c | a u_config_t object | |
fd | file descriptor opened for reading | |
overwrite | if set to 1 overwrite keys with the same name, otherwise new key with the same name will be added |
0 | on success | |
~0 | on error |
int u_config_load_from | ( | u_config_t * | c, | |
u_config_gets_t | cb, | |||
void * | arg, | |||
int | overwrite | |||
) |
Load configuration data from a data source; a gets()-like function must be provided by the caller to read the configuration line-by-line.
c | an u_config_t object | |
cb | line reader callback with gets(3) prototype | |
arg | opaque argument passed to the cb function | |
overwrite | if set to 1 overwrite keys with the same name, otherwise new key with the same name will be added |
0 | on success | |
~0 | on error |
int u_config_load_from_buf | ( | char * | buf, | |
size_t | len, | |||
u_config_t ** | pc | |||
) |
Read a config object from the memory buffer buf
. In case of success, the newly created u_config_t object is given back via the result-argument pc
.
buf | a memory buffer containing a serialized config object | |
len | the dimension of buf in bytes | |
pc | a result-argument carrying the deserialized config object |
0 | on success | |
~0 | on failure |
Definition at line 981 of file config.c.
References u_config_create(), and u_config_free().
int u_config_load_from_drv | ( | const char * | uri, | |
u_config_driver_t * | drv, | |||
int | overwrite, | |||
u_config_t ** | pc | |||
) |
Load a configuration object from the resource specified by uri
, using the supplied u_config_driver_t drv
. If successful, the loaded object will be returned as a result-argument at *pc
.
uri | a string indicating the name of the resource from which the config object will be loaded. If set (i.e. non NULL ), it is supplied as-is to the open callback of the drv object | |
drv | the configured u_config_driver_t that implements the interface to the resorce from which the config object is loaded | |
overwrite | if set to 1 keys with the same name will be overwritten, otherwise a key with the same name of an already existing one will be appended | |
pc | on success, contains the reference to the created u_config_t object |
0 | on success | |
~0 | on failure |
Definition at line 883 of file config.c.
References u_config_driver_s::close, u_config_driver_s::gets, u_config_driver_s::open, u_config_create(), and u_config_free().
Referenced by u_config_load_from_file().
int u_config_load_from_file | ( | const char * | file, | |
u_config_t ** | pc | |||
) |
Create a configuration object reading from a config file
file | the configuration file path name | |
pc | value-result that will get the new configuration object |
0 | on success | |
~0 | on error |
Definition at line 621 of file config.c.
References u_config_load_from_drv().
void u_config_print | ( | u_config_t * | c, | |
int | lev | |||
) |
Print a configuration object and its children to stdout
. For each config object all keys/values pair will be printed.
c | configuration object | |
lev | nesting level; must be zero |
Definition at line 288 of file config.c.
References u_config_print_to_fp().
void u_config_print_to_fp | ( | u_config_t * | c, | |
FILE * | fp, | |||
int | lev | |||
) |
Print a configuration object and its children to fp
. For each config object all keys/values pair will be printed.
c | an u_config_t object | |
fp | reference to a file stream opened for writing | |
lev | nesting level; must be zero |
Definition at line 234 of file config.c.
References u_config_has_children(), and u_config_print_to_fp().
Referenced by u_config_print(), and u_config_print_to_fp().
int u_config_save_to_buf | ( | u_config_t * | c, | |
char * | buf, | |||
size_t | size | |||
) |
Serialize the supplied u_config_t object c
and push it into the size
bytes memory buffer buf
. In case the supplied buffer is too small the function returns an error.
c | the candidate u_config_t object for serialization | |
buf | a pre-allocated buffer of size bytes | |
size | size in bytes of buf |
0 | on success | |
~0 | on failure |
Definition at line 945 of file config.c.
References u_string_c(), u_string_create(), u_string_free(), u_string_len(), and u_strlcpy().
int u_config_set_key | ( | u_config_t * | c, | |
const char * | key, | |||
const char * | val | |||
) |
Put the given key
, val
pair into the supplied u_config_t object c
. If the same key is found into c
, it is overwritten.
c | the u_config_t object that is manipulated | |
key | the key to insert | |
val | the value to insert |
0 | on success | |
~0 | on error |
int u_config_set_value | ( | u_config_t * | c, | |
const char * | val | |||
) |
Assign the given value val
to the u_config_t object c
c | the u_config_t object that will be manipulated | |
val | the value that will be assigned to c |
0 | on success | |
~0 | on error |
Definition at line 441 of file config.c.
References u_config_get_subkey(), u_config_get_subkey_value(), u_strdup(), u_string_append(), u_string_c(), u_string_create(), u_string_free(), u_string_set(), and u_string_trim().
int u_config_sort_children | ( | u_config_t * | c, | |
int(*)(u_config_t **, u_config_t **) | config_cmp | |||
) |
Sort config children using the given comparison function.
The comparison function must return an integer less than, equal to, or greater than zero if the first argument is respectively less than, equal to, or greater than the second.
c | an u_config_t object | |
config_cmp | a function which compares two u_config_t objects |
0 | on success | |
~0 | on failure |
Definition at line 180 of file config.c.
References u_free(), and u_zalloc().
void u_config_walk | ( | u_config_t * | c, | |
u_config_walk_t | s, | |||
void(*)(u_config_t *) | cb | |||
) |
Traverse the configuration tree rooted at c
and invoke the supplied callback function cb
on each visited node. The walk strategy s
can be one of U_CONFIG_WALK_PREORDER or U_CONFIG_WALK_POSTORDER for pre- or post-order respectively.
c | A configuration tree. | |
s | Walk strategy, one of u_config_walk_t values. | |
cb | Callback function to be invoked on each visited node. |
Definition at line 1014 of file config.c.
References u_config_get_child_n(), u_config_has_children(), u_config_walk(), U_CONFIG_WALK_POSTORDER, and U_CONFIG_WALK_PREORDER.
Referenced by u_config_walk().