GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  VAL (3)

NAME

OSSP val - Value Access

CONTENTS

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 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.

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 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 querying 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 existing val_t structure to support structured names (see example section 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 variable 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 arguments.
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 arguments.
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 immediately 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@lotterer.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>



Search for    or go to Top of page |  Section 3 |  Main Index


03-Oct-2005 VAL (3) VAL 0.9.4

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.