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

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

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

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