ossp-pkg/val/val.pod
1.4
##
## val - OSSP Value Library
## 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/>
##
## This file is part of OSSP val, a Value library which
## can be found at http://www.ossp.org/pkg/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 Library
=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_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 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, it is interesting whenevery 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.
=head1 API CONSTANTS
=over 4
=item C<VAL_MAXNAME>
=item C<VAL_TYPE_>I<ID>
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>
=item C<VAL_OK>, C<VAL_ERR_>I<ID>
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
=head1 API DATA TYPES
=over 4
=item C<val_t>
=item C<val_cb_t>
=item C<val_rc_t>
=back
=head1 API FUNCTIONS
=over 4
=item val_rc_t B<val_create>(val_t **I<pval>);
=item val_rc_t B<val_destroy>(val_t *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>);
=item val_rc_t B<val_query>(val_t *I<val>, const char *I<name>, int *I<ptype>, char **I<pdesc>, void **I<pstorage>);
=item val_rc_t B<val_set>(val_t *I<val>, const char *I<name>, ...);
=item val_rc_t B<val_get>(val_t *I<val>, const char *I<name>, ...);
=item val_rc_t B<val_vset>(val_t *I<val>, const char *I<name>, va_list I<ap>);
=item val_rc_t B<val_vget>(val_t *I<val>, const char *I<name>, va_list I<ap>);
=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>);
=back
=head1 SEE ALSO
OSSP var.
=head1 HISTORY
B<OSSP val> was invented in January 2002 by Thomas Lotterer and Ralf S.
Engelschall for use inside the OSSP lmtp2nntp project.
=head1 AUTHORS
Thomas Lotterer
Ralf S. Engelschall
=cut
