FreeBSD Manual Pages
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 us- ing structs types. A structs type is a C structure that contains in- formation describing some other C data structure. This information can be used to access the contents of the described data structure dynami- cally 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 prede- fined 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-delimit- ing 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 ac- cessed 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 in- voking 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 ze- ros. 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 conse- quence, this memory may live on the stack, or the heap. Any data structures that are stored in stack variables and are initialized dur- ing 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 in- voked 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 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 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 allo- cated 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 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 represented by the byte-order independent, self-delimiting binary en- coding described by code. On success, the actual number of bytes con- sumed 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 allo- cated 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 parameters 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.0 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_free&sektion=3&manpath=FreeBSD+Ports+15.0>