|
|
| |
STRUCTS(3) |
FreeBSD Library Functions Manual |
STRUCTS(3) |
structs —
library for data structure introspection
PDEL Library (libpdel, -lpdel)
#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);
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 described 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 structure can be described
by a primitive structs type if it has the following
properties:
- It has a fixed size known at compile time.
- It can be initialized, uninitialized, copied, and compared for
equality.
- It can be converted into an ASCII string and back without losing
information.
- 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:
- Pointers
- Fixed length arrays
- Variable length arrays
- Structures
- 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 performed dynamically and automatically on any
instance of that data structure:
- Initialization and uninitialization, including allocating and freeing heap
memory or other resources.
- Comparison of two instances for equality
- “Deep” copying, i.e., creating a completely new instance
that is a copy of an original with no shared components.
- Access to arbitrary sub-fields by name (aka. “introspection”
).
- Conversion to/from ASCII (primitive types only)
- Conversion to/from XML, with precise input validation
- Conversion to/from XML-RPC "values"
- Conversion to/from a byte-order independent, self-delimiting byte
sequence
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 initialized. For example, a region of heap memory freshly returned by
malloc(3)
is unintialized. The only valid structs operation on
an uninitialized 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 resources
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 resource 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 additional memory previously allocated by
structs_init ().
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 default 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 returns 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 different 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 structure pointed to by
from and places it in the uninitialized region of
memory pointed to by to; type is
the structs type of from. This
is a recursive, 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 responsibility 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 represented
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 instead 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 represented
by the byte-order independent, self-delimiting binary encoding described by
code. On success, the actual number of bytes consumed
is returned; 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
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_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.
All of the above functions indicate an error condition by returning either -1 or
NULL and setting errno to an
appropriate value.
Whenever there is an error, no partial work is done: the state of
the parameters has not changed, and nothing has been allocated or freed.
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)
The PDEL library was developed at Packet Design, LLC.
http://www.packetdesign.com/
Archie Cobbs ⟨archie@freebsd.org⟩
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |