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:

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_tu_config_get_child_n (u_config_t *c, const char *key, int n)
 Get the n-th child by a given key.
u_config_tu_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

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


←Products
© 2005-2012 - KoanLogic S.r.l. - All rights reserved