Macros

The STRUCTS_ARRAY_TYPE() and STRUCTS_FIXEDARRAY_TYPE() macros define a structs(3) type (i.e., a struct structs_type) for describing variable and fixed length arrays, respectively. In both macros, elem_stype is a pointer to the structs type describing the array elements, and xml_tag is an XML tag (ASCII string) used to tag individual array elements when the array is expressed in XML.

For STRUCTS_ARRAY_TYPE(), the described data structure must be a struct structs_array:

    struct structs_array {
	u_int   length;       /* number of elements */
	void    *elems;       /* elements */
    };

The length field contains the number of elements in the array. The array itself is pointed to by elems, which must be cast to the appropriate type. mtype is the typed_mem(3) type used to dynamically allocate the array.

The elements of the array are subfields whose names are their index in the array. For example, if a subfield of a data structure named “foo.bar” has an array type, then the elements of the array are named “foo.bar.0,” “foo.bar.1,” etc.

As a special case, “foo.bar.length” is a read-only virtual subfield of type structs_type_uint(3) that returns the length of the array. This “length” field does not appear in the output of structs_xml_output(3) or structs_traverse(3).

To define a structure equivalent to a struct structs_array that declares elems to have the correct C type for the array elements, use the DEFINE_STRUCTS_ARRAY() macro, where struct_name is the name of the structure (or empty if no name is desired) and elem_ctype is the C type of a single element. Then the elems field will be declared to have type elem_ctype *.

STRUCTS_FIXEDARRAY_TYPE() defines a structs type for an array that has a fixed length specified by array_len. The described data structure is simply array_len consecutive instances of elem_stype, each of which must have size elem_size. In other words, elem_size must be equal to elem_stype->size.

Functions

The following functions are included to facilitate handling variable length arrays. In all cases, type is the structs(3) type for the data structure pointed to by data, and name indicates the variable length array sub-field of data. If name is NULL or the empty string, then data itself is the variable length array.

structs_array_length() returns the length of the array.

structs_array_reset() resets the array to zero length. Any existing elements are automatically freed.

structs_array_insert() inserts a new element into the array at position index, which must be between zero and the length of the array, inclusive. The new element is automatically initialized to the default value for its type.

structs_array_delete() frees and removes the element at position index, which must be greater than or equal to zero and strictly less than the length of the array.

structs_array_prep() can be used when filling in an array that is initially empty by consecutively setting each element. The prefixes of name are taken in order from shortest to longest (i.e., name itself). For each prefix that corresponds to an array element, the element index is examined. If the index is less than the length of the array, nothing happens. If the index is greater than the length of the array, an error occurs. Otherwise, a new element is added to the end of the array. Therefore, if structs_array_prep() is invoked before setting each leaf element (such as returned by structs_traverse(3)), then the extension of any internal arrays will happen automatically.