Annotation of embedaddon/libpdel/structs/type/structs_type_union.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_union.3,v 1.16 2004/12/16 16:49:57 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt STRUCTS_TYPE_UNION 3
42: .Os
43: .Sh NAME
44: .Nm structs_type_union
45: .Nd structs types for C unions
46: .Sh LIBRARY
47: PDEL Library (libpdel, \-lpdel)
48: .Sh SYNOPSIS
49: .In sys/types.h
50: .In stddef.h
51: .In pdel/structs/structs.h
52: .In pdel/structs/type/union.h
53: .Fn DEFINE_STRUCTS_UNION struct_name union_name
54: .Fn STRUCTS_UNION_TYPE union_name field_list
55: .Fn STRUCTS_UNION_FIELD field_name field_type
56: .Ft int
57: .Fn structs_union_set "const struct structs_type *type" "const char *name" "void *data" "const char *field_name"
58: .Sh DESCRIPTION
59: The
60: .Fn STRUCTS_UNION_TYPE
61: macro defines a
62: .Xr structs 3
63: type (i.e., a
64: .Dv "struct structs_type" )
65: for describing a
66: .Li "struct structs_union" ,
67: which is an intermediate structure describing a
68: .Li union
69: .Fa union_name .
70: .Pp
71: .Bd -literal -compact -offset 3n
72: struct structs_union {
73: const char *const field_name; /* name of field currently in use */
74: void *un; /* pointer to the union itself */
75: };
76: .Ed
77: .Pp
78: The
79: .Fa field_name
80: always indicates which of the union fields is currently in use.
81: It should never be modified directly; instead, use the function
82: .Fn structs_union_set
83: (see below).
84: .Fa un
85: points to the actual union, which is stored in a separately allocated buffer
86: .Xr typed_mem 3
87: type
88: .Li "union union_name" .
89: This buffer is only large enough to hold the specific field currently in use.
90: .Pp
91: To define a structure equivalent to a
92: .Li "struct structs_union"
93: that declares
94: .Fa un
95: to have the correct C type for the union used (instead of
96: .Li "void *") ,
97: use the
98: .Fn DEFINE_STRUCTS_UNION
99: macro, where
100: .Fa struct_name
101: is the name of the structure (or empty if no name is desired) and
102: .Fa union_name
103: is the name of the represented union.
104: Then the
105: .Fa un
106: field will be declared to have type
107: .Fa "union union_name *" .
108: .Pp
109: The union's fields are accessible by name.
110: Of course, only one field may be accessed at a time, and changing the
111: current union field causes the previous field contents to be lost.
112: .Pp
113: As a special case, the field named
114: .Dq field_name
115: is also read-only accessible and always returns the name of the union
116: field currently in use.
117: The union itself must not contain a field named
118: .Dq field_name,
119: or else it will not be accessible.
120: The
121: .Dq field_name
122: field does not appear in the output of
123: .Xr structs_xml_output 3
124: or
125: .Xr structs_traverse 3 .
126: .Pp
127: .Fn STRUCTS_UNION_TYPE
128: defines a
129: .Xr structs 3
130: type for a C union.
131: The
132: .Fa field_list
133: parameter must point to an array of
134: .Li "struct structs_ufield"
135: structures describing each union field:
136: .Pp
137: .Bd -literal -compact -offset 3n
138: /* This structure describes one field in a union */
139: struct structs_ufield {
140: const char *name; /* field name */
141: const struct structs_type *type; /* field type */
142: };
143: .Ed
144: .Pp
145: The
146: .Fn STRUCTS_UNION_FIELD
147: macro should be used to define an entry in the field array:
148: .Fa field_name
149: is the name of the field and
150: .Fa field_type
151: is a pointer to the
152: .Xr structs 3
153: type describing the field.
154: .Pp
155: The fields need not be listed in the array in the same order as they
156: are declared in the C union.
157: However, the array must be terminated with
158: .Dv STRUCTS_UNION_FIELD_END ,
159: which is defined as follows:
160: .Pp
161: .Dl #define STRUCTS_UNION_FIELD_END { NULL, NULL }
162: .Pp
163: The first field in the list is the
164: .Dq "default field"
165: and it is chosen as the current field when a union data type is initialized.
166: When a union data type is read in as XML by
167: .Xr structs_xml_input 3 ,
168: if the innermost XML tag is omitted (i.e., the one that specifies the
169: field name) and the default field has primitive type, then the default
170: field is assumed.
171: .Pp
172: .Fn structs_union_set
173: should be used to change the union field currently in use,
174: to guarantee that the old field's contents are properly deallocated
175: and the new field's contents are properly initialized.
176: The new field will be initialized to its default value.
177: The sub-field
178: .Fa name
179: of the object pointed to by
180: .Fa data
181: must correspond to a
182: .Li "struct structs_union"
183: (or equivalent structure), and
184: .Fa field_name
185: must match one of the union's field names.
186: The
187: .Xr structs_find 3
188: function may also be used to change the current union field.
189: .Sh RETURN VALUES
190: .Fn structs_union_set
191: returns zero if successful, otherwise -1 with
192: .Va errno
193: set appropriately.
194: .Sh SEE ALSO
195: .Xr libpdel 3 ,
196: .Xr structs 3 ,
197: .Xr structs_type 3 ,
198: .Xr structs_type_struct 3 ,
199: .Xr structs_xml_input
200: .Sh EXAMPLES
201: The program below sets a union field using the field name and
202: value specified on the command line:
203: .Pp
204: .Bd -literal -compact -offset 3n
205: #include <sys/types.h>
206: #include <sys/socket.h>
207: #include <netinet/in.h>
208: #include <arpa/inet.h>
209:
210: #include <stdio.h>
211: #include <stdlib.h>
212: #include <stdarg.h>
213: #include <err.h>
214:
215: #include <pdel/structs/structs.h>
216: #include <pdel/structs/type/union.h>
217: #include <pdel/structs/type/string.h>
218: #include <pdel/structs/type/ip4.h>
219: #include <pdel/structs/type/int.h>
220: #include <pdel/util/typed_mem.h>
221:
222: /* My union */
223: union foobar {
224: char *name;
225: u_int16_t index;
226: struct in_addr ipaddr;
227: };
228:
229: /* My structs_union structure */
230: DEFINE_STRUCTS_UNION(foobar_union, foobar);
231:
232: /* Structs type for a 'struct foobar_union' */
233: static const struct structs_ufield foobar_fields[] = {
234: STRUCTS_UNION_FIELD(name, &structs_type_string),
235: STRUCTS_UNION_FIELD(index, &structs_type_uint16),
236: STRUCTS_UNION_FIELD(ipaddr, &structs_type_ip4),
237: STRUCTS_UNION_FIELD_END
238: };
239: static const struct structs_type foobar_type =
240: STRUCTS_UNION_TYPE(foobar, &foobar_fields);
241:
242: static void
243: show_union(struct foobar_union *un)
244: {
245: /* Show the result */
246: if (strcmp(un->field_name, "name") == 0)
247: printf("name=\\"%s\\"\\n", un->un->name);
248: else if (strcmp(un->field_name, "index") == 0)
249: printf("index=%u\\n", un->un->index);
250: else if (strcmp(un->field_name, "ipaddr") == 0)
251: printf("ipaddr=%s\\n", inet_ntoa(un->un->ipaddr));
252: else
253: printf("unknown field \\"%s\\"\\n", un->field_name);
254: }
255:
256: int
257: main(int argc, char **argv)
258: {
259: struct foobar_union un;
260: const char *name;
261: char *value;
262: char ebuf[64];
263:
264: /* Initialize union */
265: if (structs_init(&foobar_type, NULL, &un) == -1)
266: err(1, "structs_init");
267: printf("Default value: ");
268: show_union(&un);
269:
270: /* Get the requested field's name and value from command line */
271: if (argc != 3)
272: errx(1, "usage: setfield <name> <value>");
273: name = argv[1];
274: value = argv[2];
275:
276: /* Set the requested field's value */
277: if (structs_set_string(&foobar_type, name,
278: value, &un, ebuf, sizeof(ebuf)) == -1)
279: errx(1, "%s: %s", name, ebuf);
280:
281: /* Show the result */
282: printf("New value: ");
283: show_union(&un);
284:
285: /* Done, clean up */
286: structs_free(&foobar_type, NULL, &un);
287: return (0);
288: }
289: .Ed
290: .Sh HISTORY
291: The PDEL library was developed at Packet Design, LLC.
292: .Dv "http://www.packetdesign.com/"
293: .Sh AUTHORS
294: .An Archie Cobbs Aq archie@freebsd.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to structs_type_union.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