val(3) Value Access val(3)NAME
OSSP val - Value Access
SYNOPSIS
Constants
"VAL_MAXNAME", "VAL_TYPE_VAL", "VAL_TYPE_PTR", "VAL_TYPE_CHAR",
"VAL_TYPE_SHORT", "VAL_TYPE_INT", "VAL_TYPE_LONG",
"VAL_TYPE_FLOAT", "VAL_TYPE_DOUBLE" "VAL_OK", "VAL_ERR_ARG",
"VAL_ERR_USE", "VAL_ERR_MEM", "VAL_ERR_HSH", "VAL_ERR_INT",
"VAL_ERR_SYS".
Data Types
"val_t", "val_cb_t", "val_rc_t".
Functions
"val_create", "val_destroy", "val_reg", "val_unreg", "val_query",
"val_set", "val_get", "val_vset", "val_vget", "val_apply".
DESCRIPTION
OSSP val is a flexible name to value mapping library for ISO-C vari‐
ables. It allows one to access ISO-C variables through name strings,
although the ISO-C language does neither provide such a dedicated
facility nor an evaluation construct (which could be used to implement
such a facility easily).
In general, this is used for accessing ISO-C variables without having
to know the actual symbol/address. The typical use cases are in combi‐
nation with flexible configuration parsing and supporting loosely-cou‐
pled DSO-based module architectures.
STRUCTURED NAMES
Whenever the API calls for a name, it supports structured names where
elements are separated by a dot. It is assumed that the leading ele‐
ments are references to other "val_t" structures and only the very last
element is a reference to an actual variable.
APPLICATION PROGRAMMING INTERFACE (API)
API CONSTANTS
The following constants exist in the OSSP val API:
"VAL_MAXNAME"
The maximum length of a variable name. For structured variables
this includes the concatenation of all elements within a path and
their separating dots.
"VAL_TYPE_"ID
Type of value when registering a variable using val_reg() or query‐
ing for the type using val_query(). Most are self-explanatory
because directly correspond to the basic ISO-C data types.
"VAL_TYPE_VAL" is used to mount a "val_t" structure into an exist‐
ing "val_t" structure to support structured names (see example sec‐
tion for details).
The following particular types exist: "VAL_TYPE_VAL" ("val_t *"),
"VAL_TYPE_PTR" ("void *"), "VAL_TYPE_CHAR" ("char"),
"VAL_TYPE_SHORT" ("short int"), "VAL_TYPE_INT" ("int"),
"VAL_TYPE_LONG" ("long int"), "VAL_TYPE_FLOAT" ("float"),
"VAL_TYPE_DOUBLE" ("double float").
"VAL_OK", "VAL_ERR_"ID
Return codes (of type "val_rc_t") for every API function. Signals
success ("VAL_OK"), invalid argument passed to function, bad usage
of a function, memory usage reached "VAL_MAXNAME" limit, error in
internal hash function to be examined through "errno", internal
error in storage as result from structure corruption, or system
errors including out of memory to be examined through "errno".
The following particular return codes exist: "VAL_OK",
"VAL_ERR_ARG", "VAL_ERR_USE", "VAL_ERR_MEM", "VAL_ERR_HSH",
"VAL_ERR_INT", "VAL_ERR_SYS".
API DATA TYPES
The following data types exist in the OSSP val API:
"val_t"
Opaque handle data type created by val_create() and passed to all
other functions to reference the the same group of values.
"val_cb_t"
Function data type for the callback to be used with val_apply().
"val_rc_t"
Data type returned by every function. See API CONSTANTS "VAL_OK"
and "VAL_ERR_"ID.
API FUNCTIONS
The following functions exist in the OSSP val API:
val_rc_t val_create(val_t **pval);
Creates a new value access structure and updates the given pointer
pval to reference it.
val_rc_t val_destroy(val_t *val);
Destroys the value access structure referenced by val.
val_rc_t val_reg(val_t *val, const char *name, int type, const char
*desc, void *storage);
Registers a value under name of type type in val. An optional
description or "NULL" can be passed through desc which can be
queried through val_query() and is also passed to the callback of
val_apply(). The value that belongs to the given name is expected
to be found at storage. Passing "NULL" as storage will create an
internal data storage in val so it can only be accessed through
val_get(), val_set() or after the actual storage address was
queried using val_query().
val_rc_t val_unreg(val_t *val, const char *name);
Unregisters the value under name from val.
val_rc_t val_query(val_t *val, const char *name, int *ptype, char
**pdesc, void **pstorage);
Queries a value name in val and returns its type, description and
storage address. All of ptype, pdesc and pstorage are optional and
"NULL" can be passed in if this information is not needed. Passing
"NULL" to all query result pointers just checks for existence of
the value name in val.
val_rc_t val_set(val_t *val, const char *name, ...);
Sets the value name in val to the data passed in as the variable
argument (expected to be of the type specified at val_reg() time).
Unless the actual storage address was queried using val_query()
this operation is mandatory for internally stored data. If external
storage is used, not the value but a pointer to it is stored in the
library, so the value is allowed to be be modified without explicit
notice to the library.
val_rc_t val_get(val_t *val, const char *name, ...);
Gets the value name in val and stores it wherever the passed vari‐
able argument points to. The storage location is expected to be of
the type specified at val_reg() time.
val_rc_t val_vset(val_t *val, const char *name, va_list ap);
Exactly like val_set() but uses a "va_list" for the variable argu‐
ments.
val_rc_t val_vget(val_t *val, const char *name, va_list ap);
Exactly like val_get() but uses a "va_list" for the variable argu‐
ments.
val_rc_t val_apply(val_t *val, const char *name, int depth, val_cb_t
cb, void *ctx);
Iterates over all values in val, starting with name, which can be
either a data storage or val_t reference, down to a given recursion
depth. If name is set to the empty string the search starts immedi‐
ately at val. For every value, the callback cb() is executed. The
callback has to be a function with the following prototype:
val_rc_t cb(void *ctx, const char *name, int type, const char
*desc, void *storage);
The ctx is the passed-through context ctx of val_apply(). The name
is the structured name relative to the val passed to val_apply(),
type signals the type of value storage points to and desc is the
text which was optionally passed to val_reg().
SEE ALSO
OSSP var (Variable Expansion)
EXAMPLES
A few simple examples on how to use OSSP val are following. For easier
reading all error checks are omitted. In a production program you have
to check every val_xxx() call against "VAL_OK", of course.
Simple Internal Value
Source:
#include <stdio.h>
#include "val.h"
int main(void)
{
val_rc_t rc;
val_t *v;
int tmp;
val_create(&v);
val_reg(v, "foo", VAL_TYPE_INT, "foo variable", NULL);
val_set(v, "foo", 123);
val_get(v, "foo", &tmp);
printf("foo=%d\n", tmp);
val_destroy(v);
return 0;
}
Output:
foo=123
Simple External Value
Source:
#include <stdio.h>
#include "val.h"
int main(void)
{
val_rc_t rc;
val_t *v;
int foo;
int tmp;
val_create(&v);
val_reg(v, "foo", VAL_TYPE_INT, "foo variable", (void *)&foo);
foo = 123;
val_get(v, "foo", &tmp);
printf("1. foo=%d tmp=%d\n", foo, tmp);
val_set(v, "foo", 456);
val_get(v, "foo", &tmp);
printf("2. foo=%d tmp=%d\n", foo, tmp);
example = 789;
val_get(v, "foo", &tmp);
printf("3. foo=%d tmp=%d\n", foo, tmp);
val_destroy(v);
return 0;
}
Output:
1. foo=123 tmp=123
2. foo=456 tmp=456
3. foo=789 tmp=789
Structured Internal Values
Source:
#include <stdio.h>
#include "val.h"
int main(void)
{
val_rc_t rc;
val_t *v1, *v2;
int tmp;
val_create(&v1);
val_create(&v2);
val_reg(v1, "bar", VAL_TYPE_VAL, "v2", (void *)&v2);
val_reg(v1, "bar.foo", VAL_TYPE_INT, "foo variable", NULL);
val_set(v2, "foo", 123);
val_get(v2, "foo", &tmp);
printf("1. foo=%d\n", tmp);
val_get(v1, "bar.foo", &tmp);
printf("2. bar.foo=%d\n", tmp);
val_set(v1, "bar.foo", 456);
val_get(v2, "foo", &tmp);
printf("3. foo=%d\n", tmp);
val_destroy(v2);
val_destroy(v1);
return 0;
}
Output:
1. foo=123
2. bar.foo=123
3. foo=456
HISTORY
OSSP val was invented in January 2002 by Thomas Lotterer <thomas@lot‐
terer.net> and Ralf S. Engelschall <rse@engelschall.com> for use in the
OSSP project. Its creation was prompted by the requirement to locate
values for OSSP var based expansions in OSSP lmtp2nntp.
AUTHORS
Thomas Lotterer <thomas@lotterer.net>
Ralf S. Engelschall <rse@engelschall.com>
03-Oct-2005 VAL 0.9.4 val(3)
