cfg(3m)

NAME
cfg - persistent configuration properties interface

SYNOPSIS
#include <mba/cfg.h>

struct cfg {
struct linkedlist *list;
};

struct cfg *cfg_new(void);
void cfg_del(void *this);

int cfg_load(struct cfg *this, const char *filename);
int cfg_store(struct cfg *this, const char *filename);

int cfg_get_str(struct cfg *this,
            char *dst,
            int dn,
            const char *def,
            const char *name);
int cfg_vget_str(struct cfg *this,
            char *dst,
            int dn,
            const char *def,
            const char *name,
            ...);
int cfg_get_int(struct cfg *this, int *dst, int def, const char *name);
int cfg_set_str(struct cfg *this, const char *src, int sn, const char *name);

DESCRIPTION
The cfg(3m) module provides an interface to load and store comments and key/value pairs. A small state machine parser preserves all space tokens and comments in order between loading, manipulating, and storing cfg files. The following is a sample of serialized properties (the cfg file format):

    # This is a comment
    addr = 192.168.1.15
    !port = 15000
    user.1 = miallen
    user.2 = gchan

Both '#' and '!' and comments. Keys are separated from values with '='. String encoding is locale dependant.

new Return a new cfg object with no properties.

del Deallocate the cfg object and all properties within.

load
    The cfg_load function loads the properties in filename into the cfg object this.

store
    The cfg_store function serializes the properties in this cfg object and stores them in filename.

get_str
    The cfg_get_str function retrieves a property identified by name into the memory spcecified by dst as a string. No more than dn bytes of dst will be written to. If the value is truncated a trailing ' ' will be included. If the named property is not in the list, the string def will be copied into dst.

vget_str
    The cfg_vget_str function retrieves a property identified by name into the memory spcecified by dst as a string. The name parameter is a format specifier that is parsed by vsprintf(3) before being passed to cfg_get_str. This permits complex keys to be constructed in-situ. To iterate over each element in a list of at most 10 properties named user.0, user.1, user.2, ... the following might be used:

    for (i = 0; i < 10; i++)
    	if (cfg_vget_str(cfg, buf, BUFSIZ, NULL, "user.%d", idx)) == 0)
    		break;   /* end of list */

get_int
    The cfg_get_int function is a convienence function that retrieves the property identified by name from this cfg object, converts it to an integer with strtol(3), and stores the value in dst. If the named property does not exist, def will be copied to dst.

set_str
    The cfg_set_str function appends the string property in src to the list associated with the cfg object this with the key name. No more than sn bytes of the src string will be copied.

RETURNS

load
    The cfg_load function returns 0 and sets errno to an appropriate value if the operation failed or non-zero if the properties were successfully loaded.

store
    The cfg_store function returns 0 and sets errno to an appropriate value if the operation failed or non-zero if the properties were successfully stored.

get_str
    The cfg_get_str function returns 0 and sets errno to an appropriate value if the operation failed or non-zero if the string was successfully copied.

vget_str
    The cfg_vget_str function returns 0 and sets errno to an appropriate value if the operation failed or non-zero if the string was successfully copied.

get_int
    The cfg_get_int function returns 0 and sets errno to an appropriate value if the operation failed or non-zero if the integer was successfully retrieved.

set_str
    The cfg_set_str function returns 0 and sets errno to an appropriate value if the operation failed or non-zero if the property could no be copied.