.\" Copyright (c) 2001-2002 Packet Design, LLC. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, .\" use and redistribution of this software, in source or object code .\" forms, with or without modifications are expressly permitted by .\" Packet Design; provided, however, that: .\" .\" (i) Any and all reproductions of the source or object code .\" must include the copyright notice above and the following .\" disclaimer of warranties; and .\" (ii) No rights are granted, in any manner or form, to use .\" Packet Design trademarks, including the mark "PACKET DESIGN" .\" on advertising, endorsements, or otherwise except as such .\" appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $Id: structs_type_array.3,v 1.1.1.1 2012/02/21 23:25:53 misho Exp $ .\" .Dd April 22, 2002 .Dt STRUCTS_TYPE_ARRAY 3 .Os .Sh NAME .Nm STRUCTS_ARRAY_TYPE , .Nm STRUCTS_FIXEDARRAY_TYPE .Nd structs types for arrays .Sh LIBRARY PDEL Library (libpdel, \-lpdel) .Sh SYNOPSIS .In sys/types.h .In pdel/structs/structs.h .In pdel/structs/type/array.h .Fn DEFINE_STRUCTS_ARRAY struct_name elem_ctype .Fn STRUCTS_ARRAY_TYPE elem_stype mtype xml_tag .Fn STRUCTS_FIXEDARRAY_TYPE elem_stype elem_size array_len xml_tag .Ft int .Fn structs_array_length "const struct structs_type *type" "const char *name" "const void *data" .Ft int .Fn structs_array_reset "const struct structs_type *type" "const char *name" "void *data" .Ft int .Fn structs_array_insert "const struct structs_type *type" "const char *name" "u_int index" "void *data" .Ft int .Fn structs_array_delete "const struct structs_type *type" "const char *name" "u_int index" "void *data" .Ft int .Fn structs_array_prep "const struct structs_type *type" "const char *name" "void *data" .Sh DESCRIPTION .Ss Macros The .Fn STRUCTS_ARRAY_TYPE and .Fn STRUCTS_FIXEDARRAY_TYPE macros define a .Xr structs 3 type (i.e., a .Dv "struct structs_type" ) for describing variable and fixed length arrays, respectively. In both macros, .Fa elem_stype is a pointer to the structs type describing the array elements, and .Fa xml_tag is an XML tag (ASCII string) used to tag individual array elements when the array is expressed in XML. .Pp For .Fn STRUCTS_ARRAY_TYPE , the described data structure must be a .Dv "struct structs_array" : .Pp .Bd -literal -offset 0n struct structs_array { u_int length; /* number of elements */ void *elems; /* elements */ }; .Ed .Pp The .Fa length field contains the number of elements in the array. The array itself is pointed to by .Fa elems , which must be cast to the appropriate type. .Fa mtype is the .Xr typed_mem 3 type used to dynamically allocate the array. .Pp 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 .Dq foo.bar has an array type, then the elements of the array are named .Dq foo.bar.0, .Dq foo.bar.1, etc. .Pp As a special case, .Dq foo.bar.length is a read-only virtual subfield of type .Xr structs_type_uint 3 that returns the length of the array. This .Dq length field does not appear in the output of .Xr structs_xml_output 3 or .Xr structs_traverse 3 . .Pp To define a structure equivalent to a .Li "struct structs_array" that declares .Fa elems to have the correct C type for the array elements, use the .Fn DEFINE_STRUCTS_ARRAY macro, where .Fa struct_name is the name of the structure (or empty if no name is desired) and .Fa elem_ctype is the C type of a single element. Then the .Fa elems field will be declared to have type .Fa "elem_ctype *" . .Pp .Fn STRUCTS_FIXEDARRAY_TYPE defines a structs type for an array that has a fixed length specified by .Fa array_len . The described data structure is simply .Fa array_len consecutive instances of .Fa elem_stype , each of which must have size .Fa elem_size . In other words, .Fa elem_size must be equal to .Fa "elem_stype->size" . .Ss Functions The following functions are included to facilitate handling variable length arrays. In all cases, .Fa type is the .Xr structs 3 type for the data structure pointed to by .Fa data , and .Fa name indicates the variable length array sub-field of .Fa data . If .Fa name is .Dv NULL or the empty string, then .Fa data itself is the variable length array. .Pp .Fn structs_array_length returns the length of the array. .Pp .Fn structs_array_reset resets the array to zero length. Any existing elements are automatically freed. .Pp .Fn structs_array_insert inserts a new element into the array at position .Fa 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. .Pp .Fn structs_array_delete frees and removes the element at position .Fa index , which must be greater than or equal to zero and strictly less than the length of the array. .Pp .Fn structs_array_prep can be used when filling in an array that is initially empty by consecutively setting each element. The prefixes of .Fa name are taken in order from shortest to longest (i.e., .Fa 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 .Fn structs_array_prep is invoked before setting each leaf element (such as returned by .Xr structs_traverse 3) , then the extension of any internal arrays will happen automatically. .Sh SEE ALSO .Xr libpdel 3 , .Xr structs 3 , .Xr structs_type 3 , .Xr typed_mem 3 .Sh EXAMPLES .Bd -literal -offset 0n /* 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"); .Ed .Sh HISTORY The PDEL library was developed at Packet Design, LLC. .Dv "http://www.packetdesign.com/" .Sh AUTHORS .An Archie Cobbs Aq archie@freebsd.org