GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  STRUCTS (3)

NAME

structs - library for data structure introspection

CONTENTS

Library
Synopsis
Description
     Overview
     Data Structure Initialization
     Structs Functions
Return Values
See Also
History
Authors

LIBRARY

PDEL Library (libpdel, -lpdel)

SYNOPSIS


.In sys/types.h
.In 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 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.

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


.An Archie Cobbs Aq archie@freebsd.org
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.