FreeBSD Manual Pages
STRUCTS_TYPE_ARRAY(3) Library Functions Manual STRUCTS_TYPE_ARRAY(3) NAME STRUCTS_ARRAY_TYPE, STRUCTS_FIXEDARRAY_TYPE -- structs types for arrays LIBRARY PDEL Library (libpdel, -lpdel) SYNOPSIS #include <sys/types.h> #include <pdel/structs/structs.h> #include <pdel/structs/type/array.h> DEFINE_STRUCTS_ARRAY(struct_name, elem_ctype); STRUCTS_ARRAY_TYPE(elem_stype, mtype, xml_tag); STRUCTS_FIXEDARRAY_TYPE(elem_stype, elem_size, array_len, xml_tag); int structs_array_length(const struct structs_type *type, const char *name, const void *data); int structs_array_reset(const struct structs_type *type, const char *name, void *data); int structs_array_insert(const struct structs_type *type, const char *name, u_int index, void *data); int structs_array_delete(const struct structs_type *type, const char *name, u_int index, void *data); int structs_array_prep(const struct structs_type *type, const char *name, void *data); DESCRIPTION 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 ar- ray itself is pointed to by elems, which must be cast to the appropri- ate 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 de- clares 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, inclu- sive. 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 ini- tially 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, noth- ing 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 ar- ray. Therefore, if structs_array_prep() is invoked before setting each leaf element (such as returned by structs_traverse(3)), then the exten- sion of any internal arrays will happen automatically. SEE ALSO libpdel(3), structs(3), structs_type(3), typed_mem(3) EXAMPLES /* Define my variable length array of IP addresses structure */ DEFINE_STRUCTS_ARRAY(ip_array, struct in_addr); /* My variable length array of IP addresses */ static struct ip_array variable_ip_array; /* Structs type describing "variable_ip_array": >= 0 IP addresses */ static const struct structs_type vip_array_type = STRUCTS_ARRAY_TYPE(&structs_type_ip4, "vip_array_memory", "ip"); #define FIXED_ARRAY_LEN 12 /* My fixed length array of IP addresses */ static struct in_addr fixed_ip_array[FIXED_ARRAY_LEN]; /* Structs type describing "fixed_ip_array": 12 IP addresses */ static const struct structs_type vip_array_type = STRUCTS_FIXEDARRAY_TYPE(&structs_type_ip4, sizeof(struct in_addr), FIXED_ARRAY_LEN, "ip"); 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_TYPE_ARRAY(3)
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | SEE ALSO | EXAMPLES | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=structs_array_prep&sektion=3&manpath=FreeBSD+Ports+15.0>