Annotation of embedaddon/libpdel/structs/type/structs_type_array.3, revision 1.1.1.1
1.1 misho 1: .\" Copyright (c) 2001-2002 Packet Design, LLC.
2: .\" All rights reserved.
3: .\"
4: .\" Subject to the following obligations and disclaimer of warranty,
5: .\" use and redistribution of this software, in source or object code
6: .\" forms, with or without modifications are expressly permitted by
7: .\" Packet Design; provided, however, that:
8: .\"
9: .\" (i) Any and all reproductions of the source or object code
10: .\" must include the copyright notice above and the following
11: .\" disclaimer of warranties; and
12: .\" (ii) No rights are granted, in any manner or form, to use
13: .\" Packet Design trademarks, including the mark "PACKET DESIGN"
14: .\" on advertising, endorsements, or otherwise except as such
15: .\" appears in the above copyright notice or in the software.
16: .\"
17: .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
18: .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
19: .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
20: .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
21: .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
22: .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
23: .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
24: .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
25: .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
26: .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
27: .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
28: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
29: .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
30: .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
31: .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
33: .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
34: .\" THE POSSIBILITY OF SUCH DAMAGE.
35: .\"
36: .\" Author: Archie Cobbs <archie@freebsd.org>
37: .\"
38: .\" $Id: structs_type_array.3,v 1.10 2004/06/02 17:24:38 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt STRUCTS_TYPE_ARRAY 3
42: .Os
43: .Sh NAME
44: .Nm STRUCTS_ARRAY_TYPE ,
45: .Nm STRUCTS_FIXEDARRAY_TYPE
46: .Nd structs types for arrays
47: .Sh LIBRARY
48: PDEL Library (libpdel, \-lpdel)
49: .Sh SYNOPSIS
50: .In sys/types.h
51: .In pdel/structs/structs.h
52: .In pdel/structs/type/array.h
53: .Fn DEFINE_STRUCTS_ARRAY struct_name elem_ctype
54: .Fn STRUCTS_ARRAY_TYPE elem_stype mtype xml_tag
55: .Fn STRUCTS_FIXEDARRAY_TYPE elem_stype elem_size array_len xml_tag
56: .Ft int
57: .Fn structs_array_length "const struct structs_type *type" "const char *name" "const void *data"
58: .Ft int
59: .Fn structs_array_reset "const struct structs_type *type" "const char *name" "void *data"
60: .Ft int
61: .Fn structs_array_insert "const struct structs_type *type" "const char *name" "u_int index" "void *data"
62: .Ft int
63: .Fn structs_array_delete "const struct structs_type *type" "const char *name" "u_int index" "void *data"
64: .Ft int
65: .Fn structs_array_prep "const struct structs_type *type" "const char *name" "void *data"
66: .Sh DESCRIPTION
67: .Ss Macros
68: The
69: .Fn STRUCTS_ARRAY_TYPE
70: and
71: .Fn STRUCTS_FIXEDARRAY_TYPE
72: macros define a
73: .Xr structs 3
74: type (i.e., a
75: .Dv "struct structs_type" )
76: for describing variable and fixed length arrays, respectively.
77: In both macros,
78: .Fa elem_stype
79: is a pointer to the structs type describing the array elements, and
80: .Fa xml_tag
81: is an XML tag (ASCII string) used to tag individual array elements
82: when the array is expressed in XML.
83: .Pp
84: For
85: .Fn STRUCTS_ARRAY_TYPE ,
86: the described data structure must be a
87: .Dv "struct structs_array" :
88: .Pp
89: .Bd -literal -offset 0n
90: struct structs_array {
91: u_int length; /* number of elements */
92: void *elems; /* elements */
93: };
94: .Ed
95: .Pp
96: The
97: .Fa length
98: field contains the number of elements in the array.
99: The array itself is pointed to by
100: .Fa elems ,
101: which must be cast to the appropriate type.
102: .Fa mtype
103: is the
104: .Xr typed_mem 3
105: type used to dynamically allocate the array.
106: .Pp
107: The elements of the array are subfields whose names are their index
108: in the array.
109: For example, if a subfield of a data structure named
110: .Dq foo.bar
111: has an array type, then the elements of the array are named
112: .Dq foo.bar.0,
113: .Dq foo.bar.1,
114: etc.
115: .Pp
116: As a special case,
117: .Dq foo.bar.length
118: is a read-only virtual subfield of type
119: .Xr structs_type_uint 3
120: that returns the length of the array.
121: This
122: .Dq length
123: field does not appear in the output of
124: .Xr structs_xml_output 3
125: or
126: .Xr structs_traverse 3 .
127: .Pp
128: To define a structure equivalent to a
129: .Li "struct structs_array"
130: that declares
131: .Fa elems
132: to have the correct C type for the array elements, use the
133: .Fn DEFINE_STRUCTS_ARRAY
134: macro, where
135: .Fa struct_name
136: is the name of the structure (or empty if no name is desired) and
137: .Fa elem_ctype
138: is the C type of a single element.
139: Then the
140: .Fa elems
141: field will be declared to have type
142: .Fa "elem_ctype *" .
143: .Pp
144: .Fn STRUCTS_FIXEDARRAY_TYPE
145: defines a structs type for an array that has a fixed length specified by
146: .Fa array_len .
147: The described data structure is simply
148: .Fa array_len
149: consecutive instances of
150: .Fa elem_stype ,
151: each of which must have size
152: .Fa elem_size .
153: In other words,
154: .Fa elem_size
155: must be equal to
156: .Fa "elem_stype->size" .
157: .Ss Functions
158: The following functions are included to facilitate handling variable
159: length arrays.
160: In all cases,
161: .Fa type
162: is the
163: .Xr structs 3
164: type for the data structure pointed to by
165: .Fa data ,
166: and
167: .Fa name
168: indicates the variable length array sub-field of
169: .Fa data .
170: If
171: .Fa name
172: is
173: .Dv NULL
174: or the empty string, then
175: .Fa data
176: itself is the variable length array.
177: .Pp
178: .Fn structs_array_length
179: returns the length of the array.
180: .Pp
181: .Fn structs_array_reset
182: resets the array to zero length.
183: Any existing elements are automatically freed.
184: .Pp
185: .Fn structs_array_insert
186: inserts a new element into the array at position
187: .Fa index ,
188: which must be between zero and the length of the array, inclusive.
189: The new element is automatically initialized to the default value
190: for its type.
191: .Pp
192: .Fn structs_array_delete
193: frees and removes the element at position
194: .Fa index ,
195: which must be greater than or equal to zero and strictly less than the
196: length of the array.
197: .Pp
198: .Fn structs_array_prep
199: can be used when filling in an array that is initially empty
200: by consecutively setting each element.
201: The prefixes of
202: .Fa name
203: are taken in order from shortest to longest (i.e.,
204: .Fa name
205: itself).
206: For each prefix that corresponds to an array element, the element
207: index is examined.
208: If the index is less than the length of the array, nothing happens.
209: If the index is greater than the length of the array, an error occurs.
210: Otherwise, a new element is added to the end of the array.
211: Therefore, if
212: .Fn structs_array_prep
213: is invoked before setting each leaf element (such as returned by
214: .Xr structs_traverse 3) ,
215: then the extension of any internal arrays will happen automatically.
216: .Sh SEE ALSO
217: .Xr libpdel 3 ,
218: .Xr structs 3 ,
219: .Xr structs_type 3 ,
220: .Xr typed_mem 3
221: .Sh EXAMPLES
222: .Bd -literal -offset 0n
223:
224: /* Define my variable length array of IP addresses structure */
225: DEFINE_STRUCTS_ARRAY(ip_array, struct in_addr);
226:
227: /* My variable length array of IP addresses */
228: static struct ip_array variable_ip_array;
229:
230: /* Structs type describing "variable_ip_array": >= 0 IP addresses */
231: static const struct structs_type vip_array_type
232: = STRUCTS_ARRAY_TYPE(&structs_type_ip4, "vip_array_memory", "ip");
233:
234: #define FIXED_ARRAY_LEN 12
235:
236: /* My fixed length array of IP addresses */
237: static struct in_addr fixed_ip_array[FIXED_ARRAY_LEN];
238:
239: /* Structs type describing "fixed_ip_array": 12 IP addresses */
240: static const struct structs_type vip_array_type
241: = STRUCTS_FIXEDARRAY_TYPE(&structs_type_ip4,
242: sizeof(struct in_addr), FIXED_ARRAY_LEN, "ip");
243: .Ed
244: .Sh HISTORY
245: The PDEL library was developed at Packet Design, LLC.
246: .Dv "http://www.packetdesign.com/"
247: .Sh AUTHORS
248: .An Archie Cobbs Aq archie@freebsd.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to structs_type_array.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / structs / type