.\" 
.\" Copyright 2002 Michael B. Allen <mba2000 ioplex.com>
.\" 
.TH cfg 3m "Apr 29, 2005" "libmba-0.9.1" "MBA Library Functions"
.SH NAME
cfg \- persistent configuration properties interface
.SH SYNOPSIS
.nf
.B #include <mba/cfg.h>
.sp
.BI "int cfg_init(struct cfg *" cfg ", struct allocator *" al ");
.br
.BI "int cfg_deinit(struct cfg *" cfg ");
.br
.BI "struct cfg *cfg_new(struct allocator *" al ");
.br
.BI "int cfg_del(void *" cfg ");
.br
.sp
.BI "int cfg_load(struct cfg *" cfg ", const char *" filename ");
.br
.BI "int cfg_load_str(struct cfg *" cfg ", const tchar *" src ", const tchar *" slim ");
.br
.BI "int cfg_load_env(struct cfg *" cfg ");
.br
.BI "int cfg_load_cgi_query_string(struct cfg *cfg, const tchar *qs);
.br
.BI "int cfg_store(struct cfg *" cfg ", const char *" filename ");
.br
.BI "int cfg_fwrite(struct cfg *" cfg ", FILE *" stream ");
.br
.sp
.BI "void cfg_iterate(void *" cfg ", iter_t *" iter ");
.br
.BI "const tchar *cfg_next(void *" cfg ", iter_t *" iter ");
.br
.BI "int cfg_get_str(struct cfg *" cfg ",
.BI "            tchar *" dst ",
.BI "            int " dn ",
.BI "            const tchar *" def ",
.BI "            const tchar *" name ");
.br
.BI "int cfg_vget_str(struct cfg *" cfg ",
.BI "            tchar *" dst ",
.BI "            int " dn ",
.BI "            const tchar *" def ",
.BI "            const tchar *" name ",
.BI "            ...);
.br
.BI "int cfg_get_short(struct cfg *" cfg ", short *" dst ", short " def ", const tchar *" name ");
.br
.BI "int cfg_get_int(struct cfg *" cfg ", int *" dst ", int " def ", const tchar *" name ");
.br
.BI "int cfg_get_long(struct cfg *" cfg ", long *" dst ", long " def ", const tchar *" name ");
.br
.BI "int cfg_vget_short(struct cfg *" cfg ", short *" dst ", short " def ", const tchar *" name ", ...);
.br
.BI "int cfg_vget_int(struct cfg *" cfg ", int *" dst ", int " def ", const tchar *" name ", ...);
.br
.BI "int cfg_vget_long(struct cfg *" cfg ", long *" dst ", long " def ", const tchar *" name ", ...);
.br

.fi
.SH DESCRIPTION
The
.BR "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
.B cfg
files. The following is a sample of serialized properties (the
.B cfg
file format):
.PP
.RS
.nf
.ta 4n 19n 31n

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

.ta
.fi
.RE
.PP
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
.I USE_WCHAR
is defined, strings are
.IR "wchar_t" .
Otherwise string encoding is locale dependant. See the HTML documentation for the
.B text
module.
.PP
.TP
.B init
The
.B cfg_init
function initializes a
.B cfg
object. The object will have no properties. Memory for all
.B cfg
operations will be allocated from the allocator
.IR "al" .
It may be necessary to call
.B cfg_deinit
to release memory allocated from the allocator
.IR "al" .
.TP
.B deinit
The
.B cfg_deinit
function frees any resources associated with this
.B cfg
object. It is not necessary to deinitialize a
.B cfg
object if the memory backing it's allocator can be freed separately (e.g. using a
.BR "suba" (3m)
allocator backed with stack memory is more efficient).
.TP
.B new
The
.B cfg_new
function allocates memory from the allocator specified by the
.I al
parameter, initializes it with
.BR "cfg_init" ,
and returns a pointer to the new
.B cfg
object. The object will have no properties. The allocator specified by the
.I al
parameter will be used for all further memory management associated with this object. It may be necessary to call
.B cfg_del
to release memory allocated from the allocator
.IR "al" .
.TP
.B del
The
.B cfg_del
function frees the
.B cfg
object and all properties within it. It is not necessary to delete a
.B cfg
object if the memory backing it's allocator can be freed separately (e.g. using a
.BR "suba" (3m)
allocator backed with stack memory is more efficent).
.TP
.B load
The
.B cfg_load
function loads the properties in
.I filename
into the
.B cfg
object
.IR "cfg" .
.TP
.B load_str
The
.B cfg_load_str
function loads properties into this
.B cfg
object from the character string at
.I src
up to but not including the memory at
.IR "slim" .
.TP
.B load_env
The
.B cfg_load_env
function loads the process environment as properties.
.TP
.B load_cgi_query_string
The
.B cfg_load_cgi_query_string
function parses a
.I 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.
.PP
.RS
.nf
.ta 4n 19n 31n

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

.ta
.fi
.RE
.PP

.TP
.B store
The
.B cfg_store
function serializes the properties of the object
.B cfg
and stores them in
.IR "filename" .
.TP
.B fwrite
The
.B cfg_fwrite
function serializes the properties of the object
.B cfg
and stores them in
.IR "filename" .
.TP
.B iterate\fR, \fBnext
Enumerate each key in this
.B cfg
object. The
.B cfg_iterate
function initializes
.I iter
with the position of the first property in this
.BR "cfg" .
With each subsequent call to
.B cfg_next
the key of each property is returned or
.B NULL
if all keys have been enumerated.
.TP
.B get_str
The
.B cfg_get_str
function retrieves a property identified by
.I name
into the memory spcecified by
.I dst
as a string. No more than
.I dn
bytes of
.I 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
.I def
is not
.BR "NULL" ,
.I def
will be copied into
.IR "dst" .
.TP
.B vget_str
The
.B cfg_vget_str
function retrieves a property identified by
.I name
into the memory spcecified by
.I dst
as a string. The
.I name
parameter is a format specifier that is parsed by
.BR "vsprintf" (3)
before being passed to
.BR "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:
.PP
.RS
.nf
.ta 4n 19n 31n

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

.ta
.fi
.RE
.PP

.TP
.B get_short
The
.B cfg_get_short
function is a convienence function that retrieves the property identified by
.I name
from
.I cfg
.B cfg
object, converts it to a short integer with
.BR "strtol" (3),
and stores the value in
.IR "dst" .
If the named property does not exist,
.I def
will be copied to
.IR "dst" .
.TP
.B get_int
The
.B cfg_get_int
function is a convienence function that retrieves the property identified by
.I name
from
.I cfg
.B cfg
object, converts it to an integer with
.BR "strtol" (3),
and stores the value in
.IR "dst" .
If the named property does not exist,
.I def
will be copied to
.IR "dst" .
.TP
.B get_long
The
.B cfg_get_long
function is a convienence function that retrieves the property identified by
.I name
from
.I cfg
.B cfg
object, converts it to a long integer with
.BR "strtol" (3),
and stores the value in
.IR "dst" .
If the named property does not exist,
.I def
will be copied to
.IR "dst" .
.TP
.B vget_short
The
.B cfg_vget_short
function is a convienence function that retrieves the property identified by
.I name
from
.I cfg
.B cfg
object, converts it to a short integer with
.BR "strtol" (3),
and stores the value in
.IR "dst" .
The
.I name
parameter and variable arguments are first reduced using
.BR "vsprintf" (3)
permitting complex keys to be constructed. If the named property does not exist,
.I def
will be copied to
.IR "dst" .
.TP
.B vget_int
The
.B cfg_vget_int
function is a convienence function that retrieves the property identified by
.I name
from
.I cfg
.B cfg
object, converts it to an integer with
.BR "strtol" (3),
and stores the value in
.IR "dst" .
The
.I name
parameter and variable arguments are first reduced using
.BR "vsprintf" (3)
permitting complex keys to be constructed. If the named property does not exist,
.I def
will be copied to
.IR "dst" .
.TP
.B vget_long
The
.B cfg_vget_long
function is a convienence function that retrieves the property identified by
.I name
from
.I cfg
.B cfg
object, converts it to a long integer with
.BR "strtol" (3),
and stores the value in
.IR "dst" .
The
.I name
parameter and variable arguments are first reduced using
.BR "vsprintf" (3)
permitting complex keys to be constructed. If the named property does not exist,
.I def
will be copied to
.IR "dst" .
.SH RETURNS
.TP
.B init
The
.B cfg_init
function returns -1 and sets
.I errno
to an appropriate value if an error occured or 0 if the object was successfully initialized.
.TP
.B deinit
The
.B cfg_deinit
function returns -1 and sets
.I errno
to an appropriate value if an error occured or 0 if resources were successfully freed.
.TP
.B new
The
.B cfg_new
function returns a new
.B cfg
object if the operation succeeded or
.B NULL
if the operation failed in which case
.I errno
is set appropriately.
.TP
.B del
The
.B cfg_del
function return 0 if the operation was successful or -1 if it failed in which case
.I errno
will be set accordingly.
.TP
.B load
The
.B cfg_load
function returns -1 and sets
.I errno
to an appropriate value if the operation failed or 0 if the properties were successfully loaded.
.TP
.B load_env
The
.B cfg_load_env
function returns -1 and sets
.I errno
to an appropriate value if the operation failed or 0 if the process environment was successfully loaded.
.TP
.B load_cgi_query_string
The
.B cfg_load_cgi_query_string
function returns 0 if the query string parameters were valid and loaded successfully. Otherwise -1 is returned and
.I errno
is set appropriately.
.TP
.B store
The
.B cfg_store
function returns -1 and sets
.I errno
to an appropriate value if the operation failed or 0 if the properties were successfully stored.
.TP
.B fwrite
The
.B cfg_fwrite
function returns -1 and sets
.I errno
to an appropriate value if the operation failed or 0 if the properties were successfully written.
.TP
.B next
The
.B cfg_next
function returns the next property in this
.B cfg
object or
.B NULL
if all keys have been enumerated.
.TP
.B get_str
If the named property is not found and
.I def
is
.B NULL
or the operation fails for another reason the
.B cfg_get_str
function will return -1 and set
.I errno
to an appropriate value. Otherwise 0 is returned to indicate the string was successfully copied.
.TP
.B vget_str
The
.B cfg_vget_str
function returns -1 and sets
.I errno
to an appropriate value if the operation failed or 0 if the string was successfully copied.
.TP
.B get_short
The
.B cfg_get_short
function returns -1 and sets
.I errno
to an appropriate value if the operation failed or 0 if the integer was successfully retrieved.
.TP
.B get_int
The
.B cfg_get_int
function returns -1 and sets
.I errno
to an appropriate value if the operation failed or 0 if the integer was successfully retrieved.
.TP
.B get_long
The
.B cfg_get_long
function returns -1 and sets
.I errno
to an appropriate value if the operation failed or 0 if the integer was successfully retrieved.
.TP
.B vget_short
The
.B cfg_vget_short
function returns -1 and sets
.I errno
to an appropriate value if the operation failed or 0 if the integer was successfully retrieved.
.TP
.B vget_int
The
.B cfg_vget_int
function returns -1 and sets
.I errno
to an appropriate value if the operation failed or 0 if the integer was successfully retrieved.
.TP
.B vget_long
The
.B cfg_vget_long
function returns -1 and sets
.I errno
to an appropriate value if the operation failed or 0 if the integer was successfully retrieved.