.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "val 3"
.TH val 3 "VAL 0.9.4" "03-Oct-2005" "Value Access"
.SH "NAME"
\&\fBOSSP val\fR \- Value Access
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.IP "\fBConstants\fR" 4
.IX Item "Constants"
\&\f(CW\*(C`VAL_MAXNAME\*(C'\fR,
\&\f(CW\*(C`VAL_TYPE_VAL\*(C'\fR,
\&\f(CW\*(C`VAL_TYPE_PTR\*(C'\fR,
\&\f(CW\*(C`VAL_TYPE_CHAR\*(C'\fR,
\&\f(CW\*(C`VAL_TYPE_SHORT\*(C'\fR,
\&\f(CW\*(C`VAL_TYPE_INT\*(C'\fR,
\&\f(CW\*(C`VAL_TYPE_LONG\*(C'\fR,
\&\f(CW\*(C`VAL_TYPE_FLOAT\*(C'\fR,
\&\f(CW\*(C`VAL_TYPE_DOUBLE\*(C'\fR
\&\f(CW\*(C`VAL_OK\*(C'\fR,
\&\f(CW\*(C`VAL_ERR_ARG\*(C'\fR,
\&\f(CW\*(C`VAL_ERR_USE\*(C'\fR,
\&\f(CW\*(C`VAL_ERR_MEM\*(C'\fR,
\&\f(CW\*(C`VAL_ERR_HSH\*(C'\fR,
\&\f(CW\*(C`VAL_ERR_INT\*(C'\fR,
\&\f(CW\*(C`VAL_ERR_SYS\*(C'\fR.
.IP "\fBData Types\fR" 4
.IX Item "Data Types"
\&\f(CW\*(C`val_t\*(C'\fR,
\&\f(CW\*(C`val_cb_t\*(C'\fR,
\&\f(CW\*(C`val_rc_t\*(C'\fR.
.IP "\fBFunctions\fR" 4
.IX Item "Functions"
\&\f(CW\*(C`val_create\*(C'\fR,
\&\f(CW\*(C`val_destroy\*(C'\fR,
\&\f(CW\*(C`val_reg\*(C'\fR,
\&\f(CW\*(C`val_unreg\*(C'\fR,
\&\f(CW\*(C`val_query\*(C'\fR,
\&\f(CW\*(C`val_set\*(C'\fR,
\&\f(CW\*(C`val_get\*(C'\fR,
\&\f(CW\*(C`val_vset\*(C'\fR,
\&\f(CW\*(C`val_vget\*(C'\fR,
\&\f(CW\*(C`val_apply\*(C'\fR.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\s-1OSSP\s0 val\fR is a flexible name to value mapping library for ISO-C
variables. 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).
.PP
In general, this is used for accessing ISO-C variables without having to
know the actual symbol/address. The typical use cases are in combination
with flexible configuration parsing and supporting loosely-coupled
DSO-based module architectures.
.SH "STRUCTURED NAMES"
.IX Header "STRUCTURED NAMES"
Whenever the \s-1API\s0 calls for a name, it supports structured names where
elements are separated by a dot. It is assumed that the leading elements
are references to other \f(CW\*(C`val_t\*(C'\fR structures and only the very last
element is a reference to an actual variable.
.SH "APPLICATION PROGRAMMING INTERFACE (API)"
.IX Header "APPLICATION PROGRAMMING INTERFACE (API)"
.Sh "\s-1API\s0 \s-1CONSTANTS\s0"
.IX Subsection "API CONSTANTS"
The following constants exist in the \fB\s-1OSSP\s0 val\fR \s-1API:\s0
.ie n .IP """VAL_MAXNAME""" 4
.el .IP "\f(CWVAL_MAXNAME\fR" 4
.IX Item "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.
.ie n .IP """VAL_TYPE_""\fR\fI\s-1ID\s0" 4
.el .IP "\f(CWVAL_TYPE_\fR\fI\s-1ID\s0\fR" 4
.IX Item "VAL_TYPE_ID"
Type of value when registering a variable using \fBval_reg\fR() or querying
for the type using \fBval_query\fR(). Most are self-explanatory because
directly correspond to the basic ISO-C data types. \f(CW\*(C`VAL_TYPE_VAL\*(C'\fR is used
to mount a \f(CW\*(C`val_t\*(C'\fR structure into an existing \f(CW\*(C`val_t\*(C'\fR structure to
support structured names (see example section for details).
.Sp
The following particular types exist: \f(CW\*(C`VAL_TYPE_VAL\*(C'\fR (\f(CW\*(C`val_t
*\*(C'\fR), \f(CW\*(C`VAL_TYPE_PTR\*(C'\fR (\f(CW\*(C`void *\*(C'\fR), \f(CW\*(C`VAL_TYPE_CHAR\*(C'\fR (\f(CW\*(C`char\*(C'\fR),
\&\f(CW\*(C`VAL_TYPE_SHORT\*(C'\fR (\f(CW\*(C`short int\*(C'\fR), \f(CW\*(C`VAL_TYPE_INT\*(C'\fR (\f(CW\*(C`int\*(C'\fR),
\&\f(CW\*(C`VAL_TYPE_LONG\*(C'\fR (\f(CW\*(C`long int\*(C'\fR), \f(CW\*(C`VAL_TYPE_FLOAT\*(C'\fR (\f(CW\*(C`float\*(C'\fR),
\&\f(CW\*(C`VAL_TYPE_DOUBLE\*(C'\fR (\f(CW\*(C`double float\*(C'\fR).
.ie n .IP """VAL_OK""\fR, \f(CW""VAL_ERR_""\fR\fI\s-1ID\s0" 4
.el .IP "\f(CWVAL_OK\fR, \f(CWVAL_ERR_\fR\fI\s-1ID\s0\fR" 4
.IX Item "VAL_OK, VAL_ERR_ID"
Return codes (of type \f(CW\*(C`val_rc_t\*(C'\fR) for every \s-1API\s0 function. Signals success
(\f(CW\*(C`VAL_OK\*(C'\fR), invalid argument passed to function, bad usage of a function,
memory usage reached \f(CW\*(C`VAL_MAXNAME\*(C'\fR limit, error in internal hash function to
be examined through \f(CW\*(C`errno\*(C'\fR, internal error in storage as result from
structure corruption, or system errors including out of memory to be examined
through \f(CW\*(C`errno\*(C'\fR.
.Sp
The following particular return codes exist: \f(CW\*(C`VAL_OK\*(C'\fR, \f(CW\*(C`VAL_ERR_ARG\*(C'\fR,
\&\f(CW\*(C`VAL_ERR_USE\*(C'\fR, \f(CW\*(C`VAL_ERR_MEM\*(C'\fR, \f(CW\*(C`VAL_ERR_HSH\*(C'\fR, \f(CW\*(C`VAL_ERR_INT\*(C'\fR,
\&\f(CW\*(C`VAL_ERR_SYS\*(C'\fR.
.Sh "\s-1API\s0 \s-1DATA\s0 \s-1TYPES\s0"
.IX Subsection "API DATA TYPES"
The following data types exist in the \fB\s-1OSSP\s0 val\fR \s-1API:\s0
.ie n .IP """val_t""" 4
.el .IP "\f(CWval_t\fR" 4
.IX Item "val_t"
Opaque handle data type created by \fBval_create\fR() and passed to all
other functions to reference the the same group of values.
.ie n .IP """val_cb_t""" 4
.el .IP "\f(CWval_cb_t\fR" 4
.IX Item "val_cb_t"
Function data type for the callback to be used with \fBval_apply\fR().
.ie n .IP """val_rc_t""" 4
.el .IP "\f(CWval_rc_t\fR" 4
.IX Item "val_rc_t"
Data type returned by every function. See \fB\s-1API\s0 \s-1CONSTANTS\s0\fR \f(CW\*(C`VAL_OK\*(C'\fR and
\&\f(CW\*(C`VAL_ERR_\*(C'\fR\fI\s-1ID\s0\fR.
.Sh "\s-1API\s0 \s-1FUNCTIONS\s0"
.IX Subsection "API FUNCTIONS"
The following functions exist in the \fB\s-1OSSP\s0 val\fR \s-1API:\s0
.IP "val_rc_t \fBval_create\fR(val_t **\fIpval\fR);" 4
.IX Item "val_rc_t val_create(val_t **pval);"
Creates a new value access structure and updates the given pointer
\&\fIpval\fR to reference it.
.IP "val_rc_t \fBval_destroy\fR(val_t *\fIval\fR);" 4
.IX Item "val_rc_t val_destroy(val_t *val);"
Destroys the value access structure referenced by \fIval\fR.
.IP "val_rc_t \fBval_reg\fR(val_t *\fIval\fR, const char *\fIname\fR, int \fItype\fR, const char *\fIdesc\fR, void *\fIstorage\fR);" 4
.IX Item "val_rc_t val_reg(val_t *val, const char *name, int type, const char *desc, void *storage);"
Registers a value under \fIname\fR of type \fItype\fR in \fIval\fR. An optional
description or \f(CW\*(C`NULL\*(C'\fR can be passed through \fIdesc\fR which can be
queried through \fBval_query\fR() and is also passed to the callback of
\&\fBval_apply\fR(). The value that belongs to the given \fIname\fR is expected
to be found at \fIstorage\fR. Passing \f(CW\*(C`NULL\*(C'\fR as \fIstorage\fR will create
an internal data storage in \fIval\fR so it can only be accessed through
\&\fBval_get\fR(), \fBval_set\fR() or after the actual storage address was
queried using \fBval_query\fR().
.IP "val_rc_t \fBval_unreg\fR(val_t *\fIval\fR, const char *\fIname\fR);" 4
.IX Item "val_rc_t val_unreg(val_t *val, const char *name);"
Unregisters the value under \fIname\fR from \fIval\fR.
.IP "val_rc_t \fBval_query\fR(val_t *\fIval\fR, const char *\fIname\fR, int *\fIptype\fR, char **\fIpdesc\fR, void **\fIpstorage\fR);" 4
.IX Item "val_rc_t val_query(val_t *val, const char *name, int *ptype, char **pdesc, void **pstorage);"
Queries a value \fIname\fR in \fIval\fR and returns its type, description and
storage address. All of \fIptype\fR, \fIpdesc\fR and \fIpstorage\fR are optional
and \f(CW\*(C`NULL\*(C'\fR can be passed in if this information is not needed. Passing
\&\f(CW\*(C`NULL\*(C'\fR to all query result pointers just checks for existence of the
value \fIname\fR in \fIval\fR.
.IP "val_rc_t \fBval_set\fR(val_t *\fIval\fR, const char *\fIname\fR, ...);" 4
.IX Item "val_rc_t val_set(val_t *val, const char *name, ...);"
Sets the value \fIname\fR in \fIval\fR to the data passed in as the variable
argument (expected to be of the \fItype\fR specified at \fBval_reg\fR() time).
Unless the actual storage address was queried using \fBval_query\fR() 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.
.IP "val_rc_t \fBval_get\fR(val_t *\fIval\fR, const char *\fIname\fR, ...);" 4
.IX Item "val_rc_t val_get(val_t *val, const char *name, ...);"
Gets the value \fIname\fR in \fIval\fR and stores it wherever the passed variable
argument points to. The storage location is expected to be of the \fItype\fR
specified at \fBval_reg\fR() time.
.IP "val_rc_t \fBval_vset\fR(val_t *\fIval\fR, const char *\fIname\fR, va_list \fIap\fR);" 4
.IX Item "val_rc_t val_vset(val_t *val, const char *name, va_list ap);"
Exactly like \fBval_set\fR() but uses a \f(CW\*(C`va_list\*(C'\fR for the variable arguments.
.IP "val_rc_t \fBval_vget\fR(val_t *\fIval\fR, const char *\fIname\fR, va_list \fIap\fR);" 4
.IX Item "val_rc_t val_vget(val_t *val, const char *name, va_list ap);"
Exactly like \fBval_get\fR() but uses a \f(CW\*(C`va_list\*(C'\fR for the variable arguments.
.IP "val_rc_t \fBval_apply\fR(val_t *\fIval\fR, const char *\fIname\fR, int \fIdepth\fR, val_cb_t \fIcb\fR, void *\fIctx\fR);" 4
.IX Item "val_rc_t val_apply(val_t *val, const char *name, int depth, val_cb_t cb, void *ctx);"
Iterates over all values in \fIval\fR, starting with \fIname\fR, which can be
either a data storage or \fIval_t\fR reference, down to a given recursion
\&\fIdepth\fR. If \fIname\fR is set to the empty string the search starts
immediately at \fIval\fR. For every value, the callback \fIcb\fR() is executed.
The callback has to be a function with the following prototype:
.Sp
val_rc_t cb(void *\fIctx\fR, const char *\fIname\fR, int \fItype\fR, const char *\fIdesc\fR, void *\fIstorage\fR);
.Sp
The \fIctx\fR is the passed-through context \fIctx\fR of \fBval_apply\fR().
The \fIname\fR is the structured name relative to the \fIval\fR passed to
\&\fBval_apply\fR(), \fItype\fR signals the type of value \fIstorage\fR points to
and \fIdesc\fR is the text which was optionally passed to \fBval_reg\fR().
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fB\s-1OSSP\s0 var\fR (Variable Expansion)
.SH "EXAMPLES"
.IX Header "EXAMPLES"
A few simple examples on how to use \fB\s-1OSSP\s0 val\fR are following. For
easier reading all error checks are omitted. In a production program you
have to check every \fIval_xxx()\fR call against \f(CW\*(C`VAL_OK\*(C'\fR, of course.
.Sh "Simple Internal Value"
.IX Subsection "Simple Internal Value"
Source:
.PP
.Vb 2
\& #include <stdio.h>
\& #include "val.h"
.Ve
.PP
.Vb 5
\& int main(void)
\& {
\&     val_rc_t rc;
\&     val_t *v;
\&     int tmp;
.Ve
.PP
.Vb 8
\&     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\en", tmp);
\&     val_destroy(v);
\&     return 0;
\& }
.Ve
.PP
Output:
.PP
.Vb 1
\&  foo=123
.Ve
.Sh "Simple External Value"
.IX Subsection "Simple External Value"
Source:
.PP
.Vb 2
\& #include <stdio.h>
\& #include "val.h"
.Ve
.PP
.Vb 6
\& int main(void)
\& {
\&     val_rc_t rc;
\&     val_t *v;
\&     int foo;
\&     int tmp;
.Ve
.PP
.Vb 14
\&     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\en", foo, tmp);
\&     val_set(v, "foo", 456);
\&     val_get(v, "foo", &tmp);
\&     printf("2. foo=%d tmp=%d\en", foo, tmp);
\&     example = 789;
\&     val_get(v, "foo", &tmp);
\&     printf("3. foo=%d tmp=%d\en", foo, tmp);
\&     val_destroy(v);
\&     return 0;
\& }
.Ve
.PP
Output:
.PP
.Vb 3
\& 1. foo=123 tmp=123
\& 2. foo=456 tmp=456
\& 3. foo=789 tmp=789
.Ve
.Sh "Structured Internal Values"
.IX Subsection "Structured Internal Values"
Source:
.PP
.Vb 2
\& #include <stdio.h>
\& #include "val.h"
.Ve
.PP
.Vb 5
\& int main(void)
\& {
\&     val_rc_t rc;
\&     val_t *v1, *v2;
\&     int tmp;
.Ve
.PP
.Vb 16
\&     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\en", tmp);
\&     val_get(v1, "bar.foo", &tmp);
\&     printf("2. bar.foo=%d\en", tmp);
\&     val_set(v1, "bar.foo", 456);
\&     val_get(v2, "foo", &tmp);
\&     printf("3. foo=%d\en", tmp);
\&     val_destroy(v2);
\&     val_destroy(v1);
\&     return 0;
\& }
.Ve
.PP
Output:
.PP
.Vb 3
\& 1. foo=123
\& 2. bar.foo=123
\& 3. foo=456
.Ve
.SH "HISTORY"
.IX Header "HISTORY"
\&\fB\s-1OSSP\s0 val\fR was invented in January 2002 by Thomas Lotterer
<thomas@lotterer.net> and Ralf S. Engelschall
<rse@engelschall.com> for use in the \fB\s-1OSSP\s0\fR project. Its
creation was prompted by the requirement to locate values for \fB\s-1OSSP\s0
var\fR based expansions in \fB\s-1OSSP\s0 lmtp2nntp\fR.
.SH "AUTHORS"
.IX Header "AUTHORS"
.Vb 2
\& Thomas Lotterer     <thomas@lotterer.net>
\& Ralf S. Engelschall <rse@engelschall.com>
.Ve