STRUCTS(3) 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 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 de- scribed 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 in- formation. * 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 in- clude 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 ele- ments 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: * Initialization and uninitialization, including allocating and free- ing 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 struc- ture" 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 mal- loc(3) is unintialized. The only valid structs operation on an uninitial- ized 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 ini- tialized), 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 mem- ory may live on the stack, or the heap. Any data structures that are stored in stack variables and are initialized during execution of a func- tion 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 addi- tional 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 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 re- turn, to will be initialized and therefore it is the caller's responsibil- ity 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 struc- ture pointed to by from; type is the structs type of to. This is a recur- sive, 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 free- ing 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 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 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 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 para- meters 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 ports 15.quarterly April 22, 2002 STRUCTS(3)
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=structs_set&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>