Configuration

Overview

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:

by means of the u_config_driver_t abstraction, any data source is available for storing textual u_config_t objects: it is sufficient to supply a set of custom callbacks interfacing the desired storage system;
an u_config_t object can be marshalled/unmarshalled via the u_config_save_to_buf and u_config_load_from_buf functions respectively: as such it can be used as a generic message framing facility (though not particularly space efficient).

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.

Enumeration Type Documentation

enum u_config_walk_t

Enumerator:

U_CONFIG_WALK_PREORDER	Visit the node, then its children.
U_CONFIG_WALK_POSTORDER	Visit node's children, then the node.

Definition at line 86 of file config.h.

Function Documentation

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.

Parameters:

	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`

Return values:

	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.

Parameters:

	c	the u_config_t object that is manipulated
	key	the key to insert
	val	the value to insert

Return values:

	0	on success
	~0	on error

Definition at line 526 of file config.c.

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

Parameters:

pc

value-result that will get the new configuration object

Return values:

	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.

Parameters:

	c	parent u_config_t object
	child	child to remove

Return values:

	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.

Parameters:

c

configuration object

Return values:

	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

Parameters:

	c	the parent u_config_t object
	key	the key that shall be searched

Returns:: the reference to the found child, or 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.

Parameters:

	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

Returns:: the reference to the child if found, or 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

Parameters:

c

an u_config_t object

Returns:: the key string reference on success (which could be NULL), and NULL if c is NULL

Definition at line 733 of file config.c.

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

Parameters:

	c	the parent u_config_t object
	subkey	a subkey value
	pc	the found child (if found) as a result argument

Return values:

	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

Parameters:

	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

Return values:

	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.

Parameters:

	c	configuration object
	subkey	the key value of the child config object

Returns:: the value string on success, 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.

Parameters:

	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

Return values:

	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.

Parameters:

	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

Return values:

	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.

Parameters:

c

configuration object

Returns:: the value string on success (which could be 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

Parameters:

c

an u_config_t object

Return values:

	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.

Parameters:

	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

Return values:

	0	on success
	~0	on error

Definition at line 592 of file config.c.

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.

Parameters:

	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

Return values:

	0	on success
	~0	on error

Definition at line 564 of file config.c.

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.

Parameters:

	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

Return values:

	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.

Parameters:

	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

Return values:

	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

Parameters:

	file	the configuration file path name
	pc	value-result that will get the new configuration object

Return values:

	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.

Parameters:

	c	configuration object
	lev	nesting level; must be zero

Returns:: nothing

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.

Parameters:

	c	an u_config_t object
	fp	reference to a file stream opened for writing
	lev	nesting level; must be zero

Returns:: nothing

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.

Parameters:

	c	the candidate u_config_t object for serialization
	buf	a pre-allocated buffer of `size` bytes
	size	size in bytes of `buf`

Return values:

	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.

Parameters:

	c	the u_config_t object that is manipulated
	key	the key to insert
	val	the value to insert

Return values:

	0	on success
	~0	on error

Definition at line 544 of file config.c.

int u_config_set_value	(	u_config_t *	c,
		const char *	val
	)

Assign the given value val to the u_config_t object c

Parameters:

	c	the u_config_t object that will be manipulated
	val	the value that will be assigned to `c`

Return values:

	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.

Parameters:

	c	an u_config_t object
	config_cmp	a function which compares two u_config_t objects

Return values:

	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.

Parameters:

	c	A configuration tree.
	s	Walk strategy, one of u_config_walk_t values.
	cb	Callback function to be invoked on each visited node.

Returns:: nothing.

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().

Configuration

Overview

Data Structures

Typedefs

Enumerations

Functions

Enumeration Type Documentation

Function Documentation