Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
val(3)				 Value Access				val(3)

NAME
       OSSP val	- Value	Access

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 vari-
       ables. 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 combi-
       nation with flexible configuration parsing and supporting loosely-cou-
       pled 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 ele-
       ments 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	query-
	   ing 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 exist-
	   ing "val_t" structure to support structured names (see example sec-
	   tion	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	vari-
	   able	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	argu-
	   ments.

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

       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 immedi-
	   ately 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@lot-
       terer.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>

03-Oct-2005			   VAL 0.9.4				val(3)

NAME | SYNOPSIS | DESCRIPTION | STRUCTURED NAMES | APPLICATION PROGRAMMING INTERFACE (API) | SEE ALSO | EXAMPLES | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=val&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help