1. Cfg
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 '='. String encoding is locale dependant.
1.1. The cfg structure
The cfg structure
Synopsis
#include <mba/cfg.h>
struct cfg;
Description
The cfg structure maintains a list of serialized comments and properties.
1.2. Memory management functions
These functions should be used to create and destroy cfg objects.
The cfg_new function
Synopsis
#include <mba/cfg.h>
struct cfg *cfg_new(void);
Description
The cfg_new function returns a new cfg object with no properties.
The cfg_del function
Synopsis
#include <mba/cfg.h>
void cfg_del(void *this);
Description
The cfg_del function frees the cfg object and all properties within it.
1.3. Load and store functions
The cfg_load function
Synopsis
#include <mba/cfg.h>
int cfg_load(struct cfg *this, const char *filename);
Description
The cfg_load function loads the properties in filename into the cfg object this.
Returns
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.
The cfg_store function
Synopsis
#include <mba/cfg.h>
int cfg_store(struct cfg *this, const char *filename);
Description
The cfg_store function serializes the properties in this cfg object and stores them in filename.
Returns
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.
1.4. Property manipulation functions
The cfg_iterate function
Synopsis
#include <mba/cfg.h>
void cfg_iterate(void *this, iter_t *iter);
Description
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.
The cfg_next function
Synopsis
#include <mba/cfg.h>
const char *cfg_next(void *this, iter_t *iter);
Returns
The cfg_next function returns the next property in this cfg object or NULL if all keys have been enumerated.
The cfg_get_str function
Synopsis
#include <mba/cfg.h>
int cfg_get_str(struct cfg *this,
char *dst,
int dn,
const char *def,
const char *name);
Description
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.
Returns
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.
The cfg_vget_str function
Synopsis
#include <mba/cfg.h>
int cfg_vget_str(struct cfg *this,
char *dst,
int dn,
const char *def,
const char *name,
...);
Description
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 */
Returns
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.
The cfg_get_short function
Synopsis
#include <mba/cfg.h>
int cfg_get_short(struct cfg *this, short *dst, short def, const char *name);
Description
The cfg_get_short function is a convienence function that retrieves the property identified by name from this 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.
Returns
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.
The cfg_get_int function
Synopsis
#include <mba/cfg.h>
int cfg_get_int(struct cfg *this, int *dst, int def, const char *name);
Description
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.
Returns
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.
The cfg_get_long function
Synopsis
#include <mba/cfg.h>
int cfg_get_long(struct cfg *this, long *dst, long def, const char *name);
Description
The cfg_get_long function is a convienence function that retrieves the property identified by name from this 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.
Returns
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.
The cfg_vget_short function
Synopsis
#include <mba/cfg.h>
int cfg_vget_short(struct cfg *this, short *dst, short def, const char *name, ...);
Description
The cfg_vget_short function is a convienence function that retrieves the property identified by name from this 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.
Returns
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.
The cfg_vget_int function
Synopsis
#include <mba/cfg.h>
int cfg_vget_int(struct cfg *this, int *dst, int def, const char *name, ...);
Description
The cfg_vget_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. 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
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.
The cfg_vget_long function
Synopsis
#include <mba/cfg.h>
int cfg_vget_long(struct cfg *this, long *dst, long def, const char *name, ...);
Description
The cfg_vget_long function is a convienence function that retrieves the property identified by name from this 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
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.
The cfg_set_str function
Synopsis
#include <mba/cfg.h>
int cfg_set_str(struct cfg *this, const char *src, int sn, const char *name);
Description
Currently this function is not implemented.
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
The cfg_set_str function returns -1 and sets errno to an appropriate value if the operation failed or 0 if the property could no be copied.
Copyright 2002 Michael B. Allen <mballen@erols.com>