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

FreeBSD Manual Pages

  
 
  

home | help
STRUCTS(3)	       FreeBSD Library Functions Manual		    STRUCTS(3)

NAME
     structs --	library	for data structure introspection

LIBRARY
     PDEL Library (libpdel, -lpdel)

SYNOPSIS
     #include <sys/types.h>
     #include <pdel/structs/structs.h>

     int
     structs_init(const	struct structs_type *type, const char *name,
	 void *data);

     int
     structs_reset(const struct	structs_type *type, const char *name,
	 void *data);

     int
     structs_free(const	struct structs_type *type, const char *name,
	 void *data);

     int
     structs_equal(const struct	structs_type *type, const char *name,
	 const void *data1, const void *data2);

     const struct structs_type *
     structs_find(const	struct structs_type *type, const char *name,
	 void **datap, int set_union);

     int
     structs_get(const struct structs_type *type, const	char *name,
	 const void *from, void	*to);

     int
     structs_set(const struct structs_type *type, const	void *from,
	 const char *name, void	*to);

     char *
     structs_get_string(const struct structs_type *type, const char *name,
	 const void *data, const char *mtype);

     int
     structs_set_string(const struct structs_type *type, const char *name,
	 const char *ascii, void *data,	char *ebuf, size_t emax);

     int
     structs_get_binary(const struct structs_type *type, const char *name,
	 const void *data, const char *mtype, struct structs_data *code);

     int
     structs_set_binary(const struct structs_type *type, const char *name,
	 const struct structs_data *code, void *data, char *ebuf,
	 size_t	emax);

     int
     structs_traverse(const struct structs_type	*type, const void *data,
	 char ***listp,	const char *mtype);

DESCRIPTION
   Overview
     The structs library includes macros and functions for defining and	using
     structs types.  A structs type is a C structure that contains information
     describing	some other C data structure.  This information can be used to
     access the	contents of the	described data structure dynamically at	run
     time.  The	library	provides several pre-defined types for commonly	used
     data structures, as well as macros	for creating new types.

     A data structure is supported by the structs library if it	can be de-
     scribed by	a structs type (see structs_type(3)).  There are two classes
     of	types: primitive and complex.  Primitive types describe	things such as
     integers, strings,	etc.  They are user-definable, and several predefined
     primitive types are supplied with the structs library.  Any data struc-
     ture can be described by a	primitive structs type if it has the following
     properties:

	+o   It has a fixed size	known at compile time.
	+o   It can be initialized, uninitialized, copied, and compared for
	    equality.
	+o   It can be converted	into an	ASCII string and back without losing
	    information.
	+o   It can be converted	into a byte-order independent, self-delimiting
	    binary sequence and	back without losing information.

     The complex types are defined recursively in terms	of other types,	and
     include the following:

	1.   Pointers
	2.   Fixed length arrays
	3.   Variable length arrays
	4.   Structures
	5.   Unions

     The complex types support accessing sub-elements dircectly	by name	at
     run-time.	That is, array,	structure, and union elements can be accessed
     by	field name or array index expressed as an ASCII	string.	 The accessed
     elements may be arbitrarily deep in the data structure.

     The upshot	of all this is that if one takes the time to describe a	data
     structures	with a structs type, then the following	operations can be per-
     formed dynamically	and automatically on any instance of that data struc-
     ture:

	+o   Initialization and uninitialization, including allocating and
	    freeing heap memory	or other resources.
	+o   Comparison of two instances	for equality
	+o   "Deep" copying, i.e., creating a completely	new instance that is a
	    copy of an original	with no	shared components.
	+o   Access to arbitrary	sub-fields by name (aka.  "introspection" ).
	+o   Conversion to/from ASCII (primitive	types only)
	+o   Conversion to/from XML, with precise input validation
	+o   Conversion to/from XML-RPC "values"
	+o   Conversion to/from a byte-order independent, self-delimiting byte
	    sequence

   Data	Structure Initialization
     A "data structure"	is just	a contiguous block of memory.  It may of
     course contain other sub-structures within	it, including pointers to yet
     other data	structures, but	for the	purposes of the	structs	library	a
     "data structure" just a block of memory that you can point	to.

     Such a data structure can be in one of two	states:	uninitialized or ini-
     tialized.	For example, a region of heap memory freshly returned by
     malloc(3) is unintialized.	 The only valid	structs	operation on an	unini-
     tialized data structure is	to initialize it; this is done by invoking
     structs_init() (see below).

     Initializing a data structure puts	it in a	known, valid, default state.
     This may involve more than	just filling the region	of memory with zeros.
     For example, it may cause additional heap memory to be allocated (and
     initialized), hidden reference counts to be incremented, or other re-
     sources to	be allocated.

     Note that structs_init() does not itself allocate the block of memory in
     which the data structure is stored, it only initializes it.  The user
     code must handle allocation of the	block of memory.  As a consequence,
     this memory may live on the stack,	or the heap.  Any data structures that
     are stored	in stack variables and are initialized during execution	of a
     function must be uninitialized before the function	returns	to avoid re-
     source leaks.

     structs_free() (see below)	is used	to free	any resources associated with
     an	initialized data structure and return it to the	uninitialized state.
     Note that this does not invoke free(3) on the block of memory containing
     the data structure, though	it may cause free(3) to	be invoked for any ad-
     ditional memory previously	allocated by structs_init().

   Structs Functions
     Generally speaking, in the	functions shown	above type points to the
     structs type describing a data structure, data points to an instance of
     that data structure, and name references by name the target sub-field or
     sub-element of the	data structure on which	the operation is to take
     place.  If	name is	equal to NULL or the empty string then the entire data
     structure is the target.  In practice, name is often NULL.

     structs_init() initializes	the uninitialized sub-field name of the	data
     structure pointed to by data.  The	data structure will be set to its de-
     fault value, which	is defined by type.

     structs_reset() resets the	already	initialized sub-field name of the data
     structure pointed to by data to its default value,	i.e., the same value
     that it would have	after a	call to	structs_init().

     structs_free() uninitializes the sub-field	name of	the data structure
     pointed to	by data, freeing any resources previously allocated by
     structs_init().

     structs_equal() compares the sub-fields name of the two data structures
     pointed to	by data1 and data2 for equality.  It returns 1 if they are
     equal or 0	if not.

     structs_find() locates a sub-field	of a data structure by name and	re-
     turns its structs type.  When invoked, *datap should point	to the data
     structure being searched.	Upon successful	return,	it will	point to the
     sub-field named by	name.  If set_union is non-zero, then if during	the
     search any	unions are encountered and the union's current field is	dif-
     ferent from the named field, then the union's field is changed to the
     named field and its value reset to	the default value before continuing
     with the search.

     structs_get() generates a copy of the sub-field name in the data struc-
     ture pointed to by	from and places	it in the uninitialized	region of mem-
     ory pointed to by to; type	is the structs type of from.  This is a	recur-
     sive, or "deep" copy containing no	shared elements	with from.  Note that
     the structs type of from._name_ and to must be the	same.  Upon successful
     return, to	will be	initialized and	therefore it is	the caller's responsi-
     bility to eventually uninitialize it.

     structs_set() changes the contents	of the already initialized sub-field
     name in the data structure	pointed	to by to to be a copy of the data
     structure pointed to by from; type	is the structs type of to.  This is a
     recursive,	or "deep" copy containing no shared elements with from.	 Note
     that the structs type of from and to._name_ must be the same.
     structs_set() does	not modify from	in any way.

     structs_get_string() returns the ASCII form of the	sub-field name in the
     data structure pointed to by data.	 This operation	is only	required to be
     implemented for primitive types.  The returned string is allocated	with
     typed_mem(3) type mtype, and the caller is	responsible for	eventually
     freeing it.

     structs_set_string() changes the contents of the already initialized sub-
     field name	in the data structure pointed to by data to the	value repre-
     sented by the ASCII string	ascii.	This operation is only required	to be
     implemented for primitive types.  If there	is an error, e.g., ascii is
     not a valid representation	of the type, then structs_set_string() will
     return -1 and if ebuf is not NULL an error	message	(including terminating
     '\0') will	be printed into	the buffer ebuf, which is assumed to have
     length emax.

     structs_get_binary() and structs_set_binary() are similar,	except that
     they work with byte-order independent, self-delimiting binary data	in-
     stead of ASCII strings.

     structs_get_binary() returns the binary encoding of the sub-field name in
     the data structure	pointed	to by data.  The code argument is a pointer to
     a struct structs_data:

	struct structs_data {
	    u_int     length;	    /* number of bytes */
	    u_char    *data;	    /* pointer to the bytes */
	};

     Upon successful return, code-_data	points to the binary encoding, which
     has length	code-_length and is allocated with typed_mem(3)	type mtype.
     The caller	is eventually responsible for freeing code-_data.

     structs_set_binary() changes the contents of the already initialized sub-
     field name	in the data structure pointed to by data to the	value repre-
     sented by the byte-order independent, self-delimiting binary encoding de-
     scribed by	code.  On success, the actual number of	bytes consumed is re-
     turned; this will be less than or equal to	code-_length.  If there	is an
     error, e.g., the encoding was invalid, then structs_set_binary() will re-
     turn -1 and if ebuf is not	NULL an	error message (including terminating
     '\0') will	be printed into	the buffer ebuf, which is assumed to have
     length emax.

     structs_traverse()	generates a list of the	names of all of	the "leaf"
     sub-structures in the data	structure pointed to by	data; these will all
     have primitive structs type.  It returns the number of elements in	the
     array.  A pointer to the array is stored in the location referenced by
     listp. Each name in the array, as well as the array itself, is allocated
     with typed_mem(3) type mtype.  The	caller is responsible for freeing all
     array elements as well as the array itself.

RETURN VALUES
     All of the	above functions	indicate an error condition by returning ei-
     ther -1 or	NULL and setting errno to an appropriate value.

     Whenever there is an error, no partial work is done: the state of the pa-
     rameters has not changed, and nothing has been allocated or freed.

SEE ALSO
     libpdel(3), structs_type(3), structs_type_array(3),
     structs_type_boolean(3), structs_type_bpf(3), structs_type_data(3),
     structs_type_dnsname(3), structs_type_ether(3), structs_type_float(3),
     structs_type_id(3), structs_type_int(3), structs_type_ip4(3),
     structs_type_null(3), structs_type_pointer(3), structs_type_regex(3),
     structs_type_string(3), structs_type_struct(3), structs_type_time(3),
     structs_type_union(3), structs_xml_input(3), structs_xmlrpc(3),
     typed_mem(3)

HISTORY
     The PDEL library was developed at Packet Design, LLC.
     http://www.packetdesign.com/

AUTHORS
     Archie Cobbs <archie@freebsd.org>

FreeBSD	13.0			April 22, 2002			  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS

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

home | help