cfg(3m)

NAME
cfg - persistent configuration properties interface

SYNOPSIS
#include <mba/cfg.h>

int cfg_init(struct cfg *cfg, struct allocator *al);
int cfg_deinit(struct cfg *cfg);
struct cfg *cfg_new(struct allocator *al);
int cfg_del(void *cfg);

int cfg_load(struct cfg *cfg, const char *filename);
int cfg_load_str(struct cfg *cfg, const tchar *src, const tchar *slim);
int cfg_load_env(struct cfg *cfg);
int cfg_load_cgi_query_string(struct cfg *cfg, const tchar *qs);
int cfg_store(struct cfg *cfg, const char *filename);
int cfg_fwrite(struct cfg *cfg, FILE *stream);

void cfg_iterate(void *cfg, iter_t *iter);
const tchar *cfg_next(void *cfg, iter_t *iter);
int cfg_get_str(struct cfg *cfg,
            tchar *dst,
            int dn,
            const tchar *def,
            const tchar *name);
int cfg_vget_str(struct cfg *cfg,
            tchar *dst,
            int dn,
            const tchar *def,
            const tchar *name,
            ...);
int cfg_get_short(struct cfg *cfg, short *dst, short def, const tchar *name);
int cfg_get_int(struct cfg *cfg, int *dst, int def, const tchar *name);
int cfg_get_long(struct cfg *cfg, long *dst, long def, const tchar *name);
int cfg_vget_short(struct cfg *cfg, short *dst, short def, const tchar *name, ...);
int cfg_vget_int(struct cfg *cfg, int *dst, int def, const tchar *name, ...);
int cfg_vget_long(struct cfg *cfg, long *dst, long def, const tchar *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

Lines beginning with the '#' and '!' characters will be interpreted as comments. Keys are separated from values with '='. Reserved characters, leading and trailing spaces, and Unicode are supported with '\' escapes. If USE_WCHAR is defined, strings are wchar_t. Otherwise string encoding is locale dependant. See the HTML documentation for the text module.

init
    The cfg_init function initializes a cfg object. The object will have no properties. Memory for all cfg operations will be allocated from the allocator al. It may be necessary to call cfg_deinit to release memory allocated from the allocator al.

deinit
    The cfg_deinit function frees any resources associated with this cfg object. It is not necessary to deinitialize a cfg object if the memory backing it's allocator can be freed separately (e.g. using a suba(3m) allocator backed with stack memory is more efficient).

new The cfg_new function allocates memory from the allocator specified by the al parameter, initializes it with cfg_init, and returns a pointer to the new cfg object. The object will have no properties. The allocator specified by the al parameter will be used for all further memory management associated with this object. It may be necessary to call cfg_del to release memory allocated from the allocator al.

del The cfg_del function frees the cfg object and all properties within it. It is not necessary to delete a cfg object if the memory backing it's allocator can be freed separately (e.g. using a suba(3m) allocator backed with stack memory is more efficent).

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

load_str
    The cfg_load_str function loads properties into this cfg object from the character string at src up to but not including the memory at slim.

load_env
    The cfg_load_env function loads the process environment as properties.

load_cgi_query_string
    The cfg_load_cgi_query_string function parses a QUERY_STRING style string like the one below which would result in loading properties 'hl', 'lr', 'ie', 'oe' and 'group' with their respective values. Parameters with no values such as 'lr' will be loaded with an empty string.

    hl=en&lr=&ie=UTF-8&oe=UTF-8&group=comp.unix.programmer

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

fwrite
    The cfg_fwrite function serializes the properties of the object cfg and stores them in filename.

iterate, next
    Enumerate each key in this cfg object. The cfg_iterate function initializes iter with the position of the first property in this cfg. With each subsequent call to cfg_next the key of each property is returned or NULL if all keys have been enumerated.

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 '\0' will be included. If the named property is not in the list and the string def is not NULL, 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_short
    The cfg_get_short function is a convienence function that retrieves the property identified by name from cfg cfg object, converts it to a short integer with strtol(3), and stores the value in dst. If the named property does not exist, def will be copied to dst.

get_int
    The cfg_get_int function is a convienence function that retrieves the property identified by name from cfg 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.

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

vget_short
    The cfg_vget_short function is a convienence function that retrieves the property identified by name from cfg cfg object, converts it to a short integer with strtol(3), and stores the value in dst. The name parameter and variable arguments are first reduced using vsprintf(3) permitting complex keys to be constructed. If the named property does not exist, def will be copied to dst.

vget_int
    The cfg_vget_int function is a convienence function that retrieves the property identified by name from cfg cfg object, converts it to an integer with strtol(3), and stores the value in dst. The name parameter and variable arguments are first reduced using vsprintf(3) permitting complex keys to be constructed. If the named property does not exist, def will be copied to dst.

vget_long
    The cfg_vget_long function is a convienence function that retrieves the property identified by name from cfg cfg object, converts it to a long integer with strtol(3), and stores the value in dst. The name parameter and variable arguments are first reduced using vsprintf(3) permitting complex keys to be constructed. If the named property does not exist, def will be copied to dst.

RETURNS

init
    The cfg_init function returns -1 and sets errno to an appropriate value if an error occured or 0 if the object was successfully initialized.

deinit
    The cfg_deinit function returns -1 and sets errno to an appropriate value if an error occured or 0 if resources were successfully freed.

new The cfg_new function returns a new cfg object if the operation succeeded or NULL if the operation failed in which case errno is set appropriately.

del The cfg_del function return 0 if the operation was successful or -1 if it failed in which case errno will be set accordingly.

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

load_env
    The cfg_load_env function returns -1 and sets errno to an appropriate value if the operation failed or 0 if the process environment was successfully loaded.

load_cgi_query_string
    The cfg_load_cgi_query_string function returns 0 if the query string parameters were valid and loaded successfully. Otherwise -1 is returned and errno is set appropriately.

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

fwrite
    The cfg_fwrite function returns -1 and sets errno to an appropriate value if the operation failed or 0 if the properties were successfully written.

next
    The cfg_next function returns the next property in this cfg object or NULL if all keys have been enumerated.

get_str
    If the named property is not found and def is NULL or the operation fails for another reason the cfg_get_str function will return -1 and set errno to an appropriate value. Otherwise 0 is returned to indicate the string was successfully copied.

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

get_short
    The cfg_get_short function returns -1 and sets errno to an appropriate value if the operation failed or 0 if the integer was successfully retrieved.

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

get_long
    The cfg_get_long function returns -1 and sets errno to an appropriate value if the operation failed or 0 if the integer was successfully retrieved.

vget_short
    The cfg_vget_short function returns -1 and sets errno to an appropriate value if the operation failed or 0 if the integer was successfully retrieved.

vget_int
    The cfg_vget_int function returns -1 and sets errno to an appropriate value if the operation failed or 0 if the integer was successfully retrieved.

vget_long
    The cfg_vget_long function returns -1 and sets errno to an appropriate value if the operation failed or 0 if the integer was successfully retrieved.