head	1.18;
access;
symbols
	LMTP2NNTP_1_4_1:1.18
	LMTP2NNTP_1_4_0:1.18
	VAL_0_9_4:1.18
	VAL_0_9_3:1.17
	LMTP2NNTP_1_3_0:1.17
	LMTP2NNTP_1_3b2:1.17
	LMTP2NNTP_1_3b1:1.17
	LMTP2NNTP_1_3a3:1.17
	LMTP2NNTP_1_3a2:1.17
	LMTP2NNTP_1_3a1:1.17
	VAL_0_9_2:1.17
	VAL_0_9_1:1.16
	LMTP2NNTP_1_2_0:1.13
	LMTP2NNTP_1_2b4:1.13
	LMTP2NNTP_1_2b3:1.13
	LMTP2NNTP_1_2b2:1.13
	LMTP2NNTP_1_2b1:1.13
	LMTP2NNTP_1_2a8:1.13
	LMTP2NNTP_1_2a7:1.13
	LMTP2NNTP_1_2a6:1.12
	LMTP2NNTP_1_2a5:1.12
	VAL_0_9_0:1.12
	LMTP2NNTP_1_2a4:1.11
	LMTP2NNTP_1_2a3:1.9;
locks; strict;
comment	@# @;


1.18
date	2005.10.03.07.22.13;	author rse;	state Exp;
branches;
next	1.17;

1.17
date	2004.04.04.10.40.50;	author rse;	state Exp;
branches;
next	1.16;

1.16
date	2003.02.17.14.35.25;	author rse;	state Exp;
branches;
next	1.15;

1.15
date	2003.02.17.14.27.40;	author rse;	state Exp;
branches;
next	1.14;

1.14
date	2003.02.17.13.49.39;	author rse;	state Exp;
branches;
next	1.13;

1.13
date	2003.02.02.14.22.43;	author rse;	state Exp;
branches;
next	1.12;

1.12
date	2002.03.15.11.35.09;	author rse;	state Exp;
branches;
next	1.11;

1.11
date	2002.03.13.18.39.40;	author rse;	state Exp;
branches;
next	1.10;

1.10
date	2002.03.13.18.35.58;	author rse;	state Exp;
branches;
next	1.9;

1.9
date	2002.01.17.13.26.31;	author rse;	state Exp;
branches;
next	1.8;

1.8
date	2002.01.17.13.01.58;	author rse;	state Exp;
branches;
next	1.7;

1.7
date	2002.01.17.12.19.09;	author rse;	state Exp;
branches;
next	1.6;

1.6
date	2002.01.17.11.50.06;	author rse;	state Exp;
branches;
next	1.5;

1.5
date	2002.01.17.09.22.18;	author rse;	state Exp;
branches;
next	1.4;

1.4
date	2002.01.16.20.47.56;	author rse;	state Exp;
branches;
next	1.3;

1.3
date	2002.01.16.14.09.18;	author rse;	state Exp;
branches;
next	1.2;

1.2
date	2002.01.09.13.36.41;	author rse;	state Exp;
branches;
next	1.1;

1.1
date	2002.01.09.10.44.28;	author rse;	state Exp;
branches;
next	;


desc
@@


1.18
log
@Bumped year in copyright messages for new year 2005
@
text
@##
##  OSSP val - Value Access
##  Copyright (c) 2002-2005 Ralf S. Engelschall <rse@@engelschall.com>
##  Copyright (c) 2002-2005 The OSSP Project <http://www.ossp.org/>
##  Copyright (c) 2002-2005 Cable & Wireless <http://www.cw.com/>
##
##  This file is part of OSSP val, a value access library which
##  can be found at http://www.ossp.org/pkg/lib/val/.
##
##  Permission to use, copy, modify, and distribute this software for
##  any purpose with or without fee is hereby granted, provided that
##  the above copyright notice and this permission notice appear in all
##  copies.
##
##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
##  SUCH DAMAGE.
##
##  val.pod: library manual page
##

=pod

=head1 NAME

B<OSSP val> - Value Access

=head1 SYNOPSIS

=over 4

=item B<Constants>

C<VAL_MAXNAME>,
C<VAL_TYPE_VAL>,
C<VAL_TYPE_PTR>,
C<VAL_TYPE_CHAR>,
C<VAL_TYPE_SHORT>,
C<VAL_TYPE_INT>,
C<VAL_TYPE_LONG>,
C<VAL_TYPE_FLOAT>,
C<VAL_TYPE_DOUBLE>
C<VAL_OK>,
C<VAL_ERR_ARG>,
C<VAL_ERR_USE>,
C<VAL_ERR_MEM>,
C<VAL_ERR_HSH>,
C<VAL_ERR_INT>,
C<VAL_ERR_SYS>.

=item B<Data Types>

C<val_t>,
C<val_cb_t>,
C<val_rc_t>.

=item B<Functions>

C<val_create>,
C<val_destroy>,
C<val_reg>,
C<val_unreg>,
C<val_query>,
C<val_set>,
C<val_get>,
C<val_vset>,
C<val_vget>,
C<val_apply>.

=back

=head1 DESCRIPTION

B<OSSP val> 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).

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.

=head1 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 elements
are references to other C<val_t> structures and only the very last
element is a reference to an actual variable.

=head1 APPLICATION PROGRAMMING INTERFACE (API)

=head2 API CONSTANTS

The following constants exist in the B<OSSP val> API:

=over 4

=item C<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.

=item C<VAL_TYPE_>I<ID>

Type of value when registering a variable using B<val_reg>() or querying
for the type using B<val_query>(). Most are self-explanatory because
directly correspond to the basic ISO-C data types. C<VAL_TYPE_VAL> is used
to mount a C<val_t> structure into an existing C<val_t> structure to
support structured names (see example section for details).

The following particular types exist: C<VAL_TYPE_VAL> (C<val_t
*>), C<VAL_TYPE_PTR> (C<void *>), C<VAL_TYPE_CHAR> (C<char>),
C<VAL_TYPE_SHORT> (C<short int>), C<VAL_TYPE_INT> (C<int>),
C<VAL_TYPE_LONG> (C<long int>), C<VAL_TYPE_FLOAT> (C<float>),
C<VAL_TYPE_DOUBLE> (C<double float>).

=item C<VAL_OK>, C<VAL_ERR_>I<ID>

Return codes (of type C<val_rc_t>) for every API function. Signals success
(C<VAL_OK>), invalid argument passed to function, bad usage of a function,
memory usage reached C<VAL_MAXNAME> limit, error in internal hash function to
be examined through C<errno>, internal error in storage as result from
structure corruption, or system errors including out of memory to be examined
through C<errno>.

The following particular return codes exist: C<VAL_OK>, C<VAL_ERR_ARG>,
C<VAL_ERR_USE>, C<VAL_ERR_MEM>, C<VAL_ERR_HSH>, C<VAL_ERR_INT>,
C<VAL_ERR_SYS>.

=back

=head2 API DATA TYPES

The following data types exist in the B<OSSP val> API:

=over 4

=item C<val_t>

Opaque handle data type created by B<val_create>() and passed to all
other functions to reference the the same group of values.

=item C<val_cb_t>

Function data type for the callback to be used with B<val_apply>().

=item C<val_rc_t>

Data type returned by every function. See B<API CONSTANTS> C<VAL_OK> and
C<VAL_ERR_>I<ID>.

=back

=head2 API FUNCTIONS

The following functions exist in the B<OSSP val> API:

=over 4

=item val_rc_t B<val_create>(val_t **I<pval>);

Creates a new value access structure and updates the given pointer
I<pval> to reference it.

=item val_rc_t B<val_destroy>(val_t *I<val>);

Destroys the value access structure referenced by I<val>.

=item val_rc_t B<val_reg>(val_t *I<val>, const char *I<name>, int I<type>, const char *I<desc>, void *I<storage>);

Registers a value under I<name> of type I<type> in I<val>. An optional
description or C<NULL> can be passed through I<desc> which can be
queried through B<val_query>() and is also passed to the callback of
B<val_apply>(). The value that belongs to the given I<name> is expected
to be found at I<storage>. Passing C<NULL> as I<storage> will create
an internal data storage in I<val> so it can only be accessed through
B<val_get>(), B<val_set>() or after the actual storage address was
queried using B<val_query>().

=item val_rc_t B<val_unreg>(val_t *I<val>, const char *I<name>);

Unregisters the value under I<name> from I<val>.

=item val_rc_t B<val_query>(val_t *I<val>, const char *I<name>, int *I<ptype>, char **I<pdesc>, void **I<pstorage>);

Queries a value I<name> in I<val> and returns its type, description and
storage address. All of I<ptype>, I<pdesc> and I<pstorage> are optional
and C<NULL> can be passed in if this information is not needed. Passing
C<NULL> to all query result pointers just checks for existence of the
value I<name> in I<val>.

=item val_rc_t B<val_set>(val_t *I<val>, const char *I<name>, ...);

Sets the value I<name> in I<val> to the data passed in as the variable
argument (expected to be of the I<type> specified at B<val_reg>() time).
Unless the actual storage address was queried using B<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.

=item val_rc_t B<val_get>(val_t *I<val>, const char *I<name>, ...);

Gets the value I<name> in I<val> and stores it wherever the passed variable
argument points to. The storage location is expected to be of the I<type>
specified at B<val_reg>() time.

=item val_rc_t B<val_vset>(val_t *I<val>, const char *I<name>, va_list I<ap>);

Exactly like B<val_set>() but uses a C<va_list> for the variable arguments.

=item val_rc_t B<val_vget>(val_t *I<val>, const char *I<name>, va_list I<ap>);

Exactly like B<val_get>() but uses a C<va_list> for the variable arguments.

=item val_rc_t B<val_apply>(val_t *I<val>, const char *I<name>, int I<depth>, val_cb_t I<cb>, void *I<ctx>);

Iterates over all values in I<val>, starting with I<name>, which can be
either a data storage or I<val_t> reference, down to a given recursion
I<depth>. If I<name> is set to the empty string the search starts
immediately at I<val>. For every value, the callback I<cb>() is executed.
The callback has to be a function with the following prototype:

val_rc_t cb(void *I<ctx>, const char *I<name>, int I<type>, const char *I<desc>, void *I<storage>);

The I<ctx> is the passed-through context I<ctx> of B<val_apply>().
The I<name> is the structured name relative to the I<val> passed to
B<val_apply>(), I<type> signals the type of value I<storage> points to
and I<desc> is the text which was optionally passed to B<val_reg>().

=back

=head1 SEE ALSO

B<OSSP var> (Variable Expansion)

=head1 EXAMPLES

A few simple examples on how to use B<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 C<VAL_OK>, of course.

=head2 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

=head2 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

=head2 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

=head1 HISTORY

B<OSSP val> was invented in January 2002 by Thomas Lotterer
E<lt>thomas@@lotterer.netE<gt> and Ralf S. Engelschall
E<lt>rse@@engelschall.comE<gt> for use in the B<OSSP> project. Its
creation was prompted by the requirement to locate values for B<OSSP
var> based expansions in B<OSSP lmtp2nntp>.

=head1 AUTHORS

 Thomas Lotterer     <thomas@@lotterer.net>
 Ralf S. Engelschall <rse@@engelschall.com>

=cut

@


1.17
log
@adjust copyrights
@
text
@d3 3
a5 3
##  Copyright (c) 2002-2004 Ralf S. Engelschall <rse@@engelschall.com>
##  Copyright (c) 2002-2004 The OSSP Project <http://www.ossp.org/>
##  Copyright (c) 2002-2004 Cable & Wireless <http://www.cw.com/>
@


1.16
log
@remove trailing whitespaces from source files and apply standard OSSP header to documents
@
text
@d3 3
a5 3
##  Copyright (c) 2002-2003 Ralf S. Engelschall <rse@@engelschall.com>
##  Copyright (c) 2002-2003 The OSSP Project <http://www.ossp.org/>
##  Copyright (c) 2002-2003 Cable & Wireless Deutschland <http://www.cw.com/de/>
@


1.15
log
@cleanup manpage
@
text
@d43 1
a43 1
C<VAL_MAXNAME>, 
@


1.14
log
@fix typo
@
text
@d35 1
a35 1
B<OSSP val> - Value Access Library
d91 1
a91 1
with flexible configuration parsing and supporting loosly-coupled
d96 1
a96 1
Whenever the APIs calls for a name, it supports structured names where
d101 5
a105 1
=head1 API CONSTANTS
d118 1
a118 1
directly correspond to the basic C data types. C<VAL_TYPE_VAL> is used
d122 5
a126 3
The following particular types exist: C<VAL_TYPE_VAL>, C<VAL_TYPE_PTR>,
C<VAL_TYPE_CHAR>, C<VAL_TYPE_SHORT>, C<VAL_TYPE_INT>, C<VAL_TYPE_LONG>,
C<VAL_TYPE_FLOAT>, C<VAL_TYPE_DOUBLE>
d143 3
a145 1
=head1 API DATA TYPES
d165 3
a167 1
=head1 API FUNCTIONS
d173 2
a174 1
Creates a new value structure and updates the given pointer to reference it.
d178 1
a178 1
Destroys a I<val> structure.
d187 1
a187 1
an internal data storage in I<val> so it can only be access through
d193 1
a193 1
Unregisters the value under I<name> in I<val>.
d198 4
a201 4
storage address. All of I<ptype>, I<pdesc> and I<pstorage> are optional and
C<NULL> can be passed in if this information is not needed. Passing C<NULL> to
all query result pointers just checks for existence of the value I<name> in
I<val>.
d210 2
a211 1
the value is allowed to be be modified without notice to the library.
d215 1
a215 1
Gets the value I<name> in I<val> and stores it whereever the passed variable
d221 1
a221 1
Exactly like B<val_set>() but uses a C<va_list>.
d225 1
a225 1
Exactly like B<val_get>() but uses a C<va_list>.
d353 5
a357 2
B<OSSP val> was invented in January 2002 by Thomas Lotterer and Ralf S.
Engelschall for use with the B<OSSP lmtp2nntp> project.
d361 1
a361 1
 Thomas Lotterer     <thomas.lotterer@@cw.com>
@


1.13
log
@bump year in copyright messages
@
text
@d148 1
a148 1
Function data type for the callback to be used with B<var_apply>().
@


1.12
log
@ignore manpages and fix building of them
@
text
@d3 3
a5 3
##  Copyright (c) 2002 Ralf S. Engelschall <rse@@engelschall.com>
##  Copyright (c) 2002 The OSSP Project <http://www.ossp.org/>
##  Copyright (c) 2002 Cable & Wireless Deutschland <http://www.cw.com/de/>
@


1.11
log
@more source tree polishing
@
text
@a338 2
=back

@


1.10
log
@fix naming and URLs
@
text
@d96 4
a99 4
Whenever the APIs 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 C<val_t> structures and only the very last element is a reference to
an actual variable.
d234 1
a234 1
B<OSSP var> (Variable Expansion Library)
d344 1
a344 1
Engelschall for use with the OSSP lmtp2nntp project.
@


1.9
log
@more polishing
@
text
@d2 1
a2 1
##  val - OSSP Value Library
d7 2
a8 2
##  This file is part of OSSP val, a Value library which
##  can be found at http://www.ossp.org/pkg/val/.
d35 1
a35 1
B<OSSP val> - Value Library
d83 10
a92 10
B<OSSP val> is a flexible name to value mapping library for C variables.
It allows one to access C variables through name strings, although
the 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 C variables without having to
know the actual symbol/address/reference. The typical use cases are
in combination with flexible configuration parsing and supporting
loosly-coupled DSO-based module architectures.
d344 1
a344 1
Engelschall for use inside the OSSP lmtp2nntp project.
@


1.8
log
@- add a third example
- add a little bit more tests to first examples
- remove all error checking because in examples
  we generally ommit this for easier reading
- display expected output
@
text
@d87 6
a92 4
easily). In general, it is interesting whenever you need access to C
variable symbols without having to know the actual address/reference.
The typical use cases are in combination with flexible configuration
parsing and supporting loosly-coupled DSO-based module architectures.
d112 9
a120 13
Type of value when registering a variable using B<val_reg>() or querying for
the type using B<val_query>(). Most are self-explanatory, C<VAL_TYPE_VAL> is
used to mount a C<val_t> structure into an existing C<val_t> structure to
support structured names.

C<VAL_TYPE_VAL>,
C<VAL_TYPE_PTR>,
C<VAL_TYPE_CHAR>,
C<VAL_TYPE_SHORT>,
C<VAL_TYPE_INT>,
C<VAL_TYPE_LONG>,
C<VAL_TYPE_FLOAT>,
C<VAL_TYPE_DOUBLE>
d124 9
a132 11
Return codes for every API function. Signals success, invalid argument passed
to function, bad usage of a function, memoryusage reached C<VAL_MAXNAME>
limit, error in internal hash function to be examined through C<errno>,
internal error in storage as result from structure corruption, or system
errors including out of memory.

C<VAL_ERR_ARG>,
C<VAL_ERR_USE>,
C<VAL_ERR_MEM>,
C<VAL_ERR_HSH>,
C<VAL_ERR_INT>,
d143 2
a144 2
Handle created by B<val_create>() and passed to all other functions to reference
the the same group of variables.
d148 1
a148 1
Callback to be used B<var_apply>().
d152 1
a152 1
Code returned by every function. See C<API_CONSTANTS> C<VAL_OK> and
d163 1
a163 1
Creates an I<val> and updates the given pointer to reference it.
d167 1
a167 1
Destroys an I<val>, freeing up memory.
d171 8
a178 7
Registers a variable I<name> using I<type> in I<val>. An optional description
or NULL can be passed through I<desc> which can be queried through
B<val_query>() and is also passed to the callback of B<val_apply>(). The value
that belongs to the given I<name> is expected to be found at I<storage>.
Passing NULL as I<storage> will create an inline data store in I<val> so it
can only be access through B<val_get>(), B<val_set>() or after the actual
storage address was queried using B<val_query>().
d182 1
a182 1
Unregisters a variable I<name> in I<val>.
d186 1
a186 1
Queries a variable I<name> in I<val> and returns it's type, description and
d188 3
a190 2
NULL can be passed in if this information is not needed. Passing NULL to all
query result pointers just checks for existence of I<name>.
d194 6
a199 4
Sets the value of variable I<name> in I<val> to the data passed in as vararg.
Unless the actual storage address was queried using B<val_query>() this is
mandatory for inline data. Usually not the value but a pointer to it is stored
to the value can be modified without notice to the library.
d203 3
a205 2
Gets the value of variable I<name> in I<val> and stores it whereever the
passed vararg points to.
d209 1
a209 3
Like B<val_set>() but takes a C<va_list> as input to allow recursive
execution. Acutally, B<val_set>() ist just a wrapper around
B<val_vset>().
d213 1
a213 3
Like B<val_get>() but takes a C<va_list> as input to allow recursive
execution. Acutally, B<val_get>() ist just a wrapper around
B<val_vget>().
d217 12
a228 13
Iterates through all elements of I<val>, starting with I<name> which can be
either a data store or I<val> reference, down to a given recursion I<depth>.
When I<name> is set to the empty string the search starts immediately at
I<val>.  For every element, the callback I<cb>() is executed and a context
I<ctx> is passed to it along with other information described below.

=item val_rc_t (*)(void *I<ctx>, const char *I<name>, int I<type>, const char *I<desc>, void *I<data>)

Callback executed by B<val_apply>() for each element being processed. The
context I<ctx> input to B<val_apply>() is passed to the callback verbatim. The
I<name> is the structured name relative to the I<val> passed to
B<val_apply>(), I<type> signals the type of value I<data> points to and
I<desc> is a text which was optionally passed to B<val_reg>().
d234 1
a234 1
OSSP var.
d348 2
a349 2
 Thomas Lotterer
 Ralf S. Engelschall
@


1.7
log
@add val_unreg() function
@
text
@d242 100
a341 45
=over 4

=item simple create, reg, get, destroy

    #include <stdio.h>
    #include "val.h"

    int main(void)
    {
        val_rc_t rc;
        val_t *v;
        int example;
        int pullout;

        if ((rc = val_create(&v)) != VAL_OK) exit(-1);
        if ((rc = val_reg(v, "foo", VAL_TYPE_INT, "foo variable", (void *)&example)) != VAL_OK) exit(-1);
        example = 123;
        if ((rc = val_get(v, "foo", &pullout)) != VAL_OK) exit(-1);
        printf("pulled example and got %d\n", pullout);
        if ((rc = val_destroy(v)) != VAL_OK) exit(-1);
        return 0;
    }

=item reg inline data, structured name, set

    #include <stdio.h>
    #include "val.h"

    int main(void)
    {
        val_rc_t rc;
        val_t *v1, *v2;
        int pullout;

        if ((rc = val_create(&v1)) != VAL_OK) exit(-1);
        if ((rc = val_create(&v2)) != VAL_OK) exit(-1);
        if ((rc = val_reg(v1, "bar", VAL_TYPE_VAL, "child", (void *)&v2)) != VAL_OK) exit(-1);
        if ((rc = val_reg(v1, "bar.foo", VAL_TYPE_INT, "foo variable", NULL)) != VAL_OK) exit(-1);
        if ((rc = val_set(v2, "foo", 456)) != VAL_OK) exit(-1);
        if ((rc = val_get(v1, "bar.foo", &pullout)) != VAL_OK) exit(-1);
        printf("pulled example and got %d\n", pullout);
        if ((rc = val_destroy(v2)) != VAL_OK) exit(-1);
        if ((rc = val_destroy(v1)) != VAL_OK) exit(-1);
        return 0;
    }
@


1.6
log
@added two copy'n'past examples
@
text
@d71 1
d182 4
@


1.5
log
@completed documentation
@
text
@d235 50
@


1.4
log
@Provide the skeleton for the manual page.
Details will be filled in soon (Thomas?!)
@
text
@d86 1
a86 1
easily). In general, it is interesting whenevery you need access to C
d91 7
d104 3
d109 5
d125 6
d146 3
d151 2
d155 3
d166 2
d170 2
d174 8
d184 5
d191 5
d198 3
d203 4
d209 4
d214 14
@


1.3
log
@new OSSP val build environment
@
text
@d39 41
d82 72
a153 1
B<OSSP val> is ...
d157 1
a157 1
...
@


1.2
log
@Cleanup.

PR:
Submitted by:
Reviewed by:
Approved by:
Obtained from:
@
text
@d49 2
a50 2
B<OSSP val> was invented in January 2002 by Ralf S. Engelschall for use
inside the OSSP project.
d54 1
a55 2
 rse@@engelschall.com
 www.engelschall.com
@


1.1
log
@Create a fresh build environment for new born child OSSP val.
This soon to be written library will provide a user-land val
with O(1) time complexity and fixed size memory usage.
@
text
@d28 1
a28 1
##  val.pod: socket abstraction library manual page
d49 1
a49 1
B<OSSP val> was invented in Januar 2002 by Ralf S. Engelschall for use
@