--- val.pod 2003/02/17 13:49:39 1.14
+++ val.pod 2003/02/17 14:27:40 1.15
@@ -32,7 +32,7 @@
=head1 NAME
-B<OSSP val> - Value Access Library
+B<OSSP val> - Value Access
=head1 SYNOPSIS
@@ -88,17 +88,21 @@
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 loosly-coupled
+with flexible configuration parsing and supporting loosely-coupled
DSO-based module architectures.
=head1 STRUCTURED NAMES
-Whenever the APIs calls for a name, it supports structured names where
+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 API CONSTANTS
+=head1 APPLICATION PROGRAMMING INTERFACE (API)
+
+=head2 API CONSTANTS
+
+The following constants exist in the B<OSSP val> API:
=over 4
@@ -111,13 +115,15 @@
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 C data types. C<VAL_TYPE_VAL> is used
+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_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>
+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>
@@ -134,7 +140,9 @@
=back
-=head1 API DATA TYPES
+=head2 API DATA TYPES
+
+The following data types exist in the B<OSSP val> API:
=over 4
@@ -154,17 +162,20 @@
=back
-=head1 API FUNCTIONS
+=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 structure and updates the given pointer to reference it.
+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 a I<val> structure.
+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>);
@@ -173,21 +184,21 @@
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 access through
+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> in I<val>.
+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>.
+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>, ...);
@@ -196,21 +207,22 @@
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 notice to the library.
+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 whereever the passed variable
+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>.
+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>.
+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>);
@@ -338,12 +350,15 @@
=head1 HISTORY
-B<OSSP val> was invented in January 2002 by Thomas Lotterer and Ralf S.
-Engelschall for use with the B<OSSP lmtp2nntp> project.
+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@cw.com>
+ Thomas Lotterer <thomas@lotterer.net>
Ralf S. Engelschall <rse@engelschall.com>
=cut
|
