Annotation of embedaddon/libpdel/structs/structs.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.3,v 1.16 2004/06/02 17:24:38 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt STRUCTS 3
42: .Os
43: .Sh NAME
44: .Nm structs
45: .Nd library for data structure introspection
46: .Sh LIBRARY
47: PDEL Library (libpdel, \-lpdel)
48: .Sh SYNOPSIS
49: .In sys/types.h
50: .In pdel/structs/structs.h
51: .Ft int
52: .Fn structs_init "const struct structs_type *type" "const char *name" "void *data"
53: .Ft int
54: .Fn structs_reset "const struct structs_type *type" "const char *name" "void *data"
55: .Ft int
56: .Fn structs_free "const struct structs_type *type" "const char *name" "void *data"
57: .Ft int
58: .Fn structs_equal "const struct structs_type *type" "const char *name" "const void *data1" "const void *data2"
59: .Ft const struct structs_type *
60: .Fn structs_find " const struct structs_type *type" "const char *name" "void **datap" "int set_union"
61: .Ft int
62: .Fn structs_get "const struct structs_type *type" "const char *name" "const void *from" "void *to"
63: .Ft int
64: .Fn structs_set "const struct structs_type *type" "const void *from" "const char *name" "void *to"
65: .Ft char *
66: .Fn structs_get_string "const struct structs_type *type" "const char *name" "const void *data" "const char *mtype"
67: .Ft int
68: .Fn structs_set_string "const struct structs_type *type" "const char *name" "const char *ascii" "void *data" "char *ebuf" "size_t emax"
69: .Ft int
70: .Fn structs_get_binary "const struct structs_type *type" "const char *name" "const void *data" "const char *mtype" "struct structs_data *code"
71: .Ft int
72: .Fn structs_set_binary "const struct structs_type *type" "const char *name" "const struct structs_data *code" "void *data" "char *ebuf" "size_t emax"
73: .Ft int
74: .Fn structs_traverse "const struct structs_type *type" "const void *data" "char ***listp" "const char *mtype"
75: .Sh DESCRIPTION
76: .\"
77: .Ss Overview
78: .\"
79: The
80: .Nm structs
81: library includes macros and functions for defining and using
82: .Nm structs
83: types.
84: A
85: .Nm structs
86: type is a C structure that contains information describing
87: some other C data structure.
88: This information can be used to access the contents of
89: the described data structure dynamically at run time.
90: The library provides several pre-defined types for commonly used
91: data structures, as well as macros for creating new types.
92: .Pp
93: A data structure is supported by the
94: .Nm structs
95: library if it can be described by a
96: .Nm structs
97: type (see
98: .Xr structs_type 3) .
99: There are two classes of types: primitive and complex.
100: Primitive types describe things such as integers, strings, etc.
101: They are user-definable, and several predefined primitive types are
102: supplied with the
103: .Nm structs
104: library.
105: Any data structure can be described by a primitive
106: .Nm structs
107: type if it has the following properties:
108: .Pp
109: .Bl -bullet -offset 3n -compact
110: .It
111: It has a fixed size known at compile time.
112: .It
113: It can be initialized, uninitialized, copied, and compared for equality.
114: .It
115: It can be converted into an ASCII string and back without losing information.
116: .It
117: It can be converted into a byte-order independent, self-delimiting
118: binary sequence and back without losing information.
119: .El
120: .Pp
121: The complex types are defined recursively in terms of other types,
122: and include the following:
123: .Pp
124: .Bl -enum -offset 3n -compact
125: .It
126: Pointers
127: .It
128: Fixed length arrays
129: .It
130: Variable length arrays
131: .It
132: Structures
133: .It
134: Unions
135: .Pp
136: .El
137: The complex types support accessing sub-elements dircectly by
138: name at run-time.
139: That is, array, structure, and union elements can be
140: accessed by field name or array index expressed as an ASCII string.
141: The accessed elements may be arbitrarily deep in the data structure.
142: .Pp
143: The upshot of all this is that if one takes the time to describe a data
144: structures with a
145: .Nm structs
146: type, then the following operations can be performed dynamically
147: and automatically on any instance of that data structure:
148: .Pp
149: .Bl -bullet -offset 3n -compact
150: .It
151: Initialization and uninitialization, including allocating
152: and freeing heap memory or other resources.
153: .It
154: Comparison of two instances for equality
155: .It
156: .Dq Deep
157: copying, i.e., creating a completely new instance
158: that is a copy of an original with no shared components.
159: .It
160: Access to arbitrary sub-fields by name (aka.
161: .Dq introspection
162: ).
163: .It
164: Conversion to/from ASCII (primitive types only)
165: .It
166: Conversion to/from XML, with precise input validation
167: .It
168: Conversion to/from XML-RPC "values"
169: .It
170: Conversion to/from a byte-order independent, self-delimiting byte sequence
171: .El
172: .Pp
173: .\"
174: .Ss Data Structure Initialization
175: .\"
176: A "data structure" is just a contiguous block of memory.
177: It may of course contain other sub-structures within it,
178: including pointers to yet other data structures, but for the purposes of the
179: .Nm structs
180: library a "data structure" just a block of memory that you can point to.
181: .Pp
182: Such a data structure can be in one of two states: uninitialized
183: or initialized.
184: For example, a region of heap memory freshly returned by
185: .Xr malloc 3
186: is unintialized.
187: The only valid
188: .Nm structs
189: operation on an uninitialized data structure is to initialize it;
190: this is done by invoking
191: .Fn structs_init
192: (see below).
193: .Pp
194: Initializing a data structure puts it in a known, valid, default state.
195: This may involve more than just filling the region of memory with zeros.
196: For example, it may cause additional heap memory to be allocated
197: (and initialized), hidden reference counts to be incremented, or other
198: resources to be allocated.
199: .Pp
200: Note that
201: .Fn structs_init
202: does not itself allocate the block of memory in which the data structure
203: is stored, it only initializes it.
204: The user code must handle allocation of the block of memory.
205: As a consequence, this memory may live on the stack, or the heap.
206: Any data structures that are stored in stack variables and are initialized
207: during execution of a function must be uninitialized before the function
208: returns to avoid resource leaks.
209: .Pp
210: .Fn structs_free
211: (see below)
212: is used to free any resources associated with an initialized data structure
213: and return it to the uninitialized state.
214: Note that this does not invoke
215: .Xr free 3
216: on the block of memory containing the data structure, though it may cause
217: .Xr free 3
218: to be invoked for any additional memory previously allocated by
219: .Fn structs_init .
220: .\"
221: .Ss Structs Functions
222: .\"
223: Generally speaking, in the functions shown above
224: .Fa type
225: points to the
226: .Nm structs
227: type describing a data structure,
228: .Fa data
229: points to an instance of that data structure, and
230: .Fa name
231: references by name the target sub-field or sub-element of the data structure
232: on which the operation is to take place.
233: If
234: .Fa name
235: is equal to
236: .Dv NULL
237: or the empty string then the entire data structure is the target.
238: In practice,
239: .Fa name
240: is often
241: .Dv NULL .
242: .Pp
243: .Fn structs_init
244: initializes the uninitialized sub-field
245: .Fa name
246: of the data structure pointed to by
247: .Fa data .
248: The data structure will be set to its default value, which is defined by
249: .Fa type.
250: .Pp
251: .Fn structs_reset
252: resets the already initialized sub-field
253: .Fa name
254: of the data structure pointed to by
255: .Fa data
256: to its default value, i.e., the same value that it would have after
257: a call to
258: .Fn structs_init .
259: .Pp
260: .Fn structs_free
261: uninitializes the sub-field
262: .Fa name
263: of the data structure pointed to by
264: .Fa data ,
265: freeing any resources previously allocated by
266: .Fn structs_init .
267: .Pp
268: .Fn structs_equal
269: compares the sub-fields
270: .Fa name
271: of the two data structures pointed to by
272: .Fa data1
273: and
274: .Fa data2
275: for equality.
276: It returns 1 if they are equal or 0 if not.
277: .Pp
278: .Fn structs_find
279: locates a sub-field of a data structure by name and returns its
280: .Nm structs
281: type.
282: When invoked,
283: .Fa "*datap"
284: should point to the data structure being searched.
285: Upon successful return, it will point to the sub-field named by
286: .Fa name .
287: If
288: .Fa set_union
289: is non-zero, then if during the search any unions are encountered
290: and the union's current field is different from the named field,
291: then the union's field is changed to the named field and its value
292: reset to the default value before continuing with the search.
293: .Pp
294: .Fn structs_get
295: generates a copy of the sub-field
296: .Fa name
297: in the data structure pointed to by
298: .Fa from
299: and places it in the uninitialized region of memory pointed to by
300: .Fa to ;
301: .Fa type
302: is the
303: .Nm structs
304: type of
305: .Fa from .
306: This is a recursive, or "deep" copy containing no shared elements with
307: .Fa from .
308: Note that the
309: .Nm structs
310: type of
311: .Fa "from.<name>"
312: and
313: .Fa to
314: must be the same.
315: Upon successful return,
316: .Fa to
317: will be initialized and therefore it is the caller's responsibility
318: to eventually uninitialize it.
319: .Pp
320: .Fn structs_set
321: changes the contents of the already initialized sub-field
322: .Fa name
323: in the data structure pointed to by
324: .Fa to
325: to be a copy of the data structure pointed to by
326: .Fa from ;
327: .Fa type
328: is the
329: .Nm structs
330: type of
331: .Fa to .
332: This is a recursive, or "deep" copy containing no shared elements with
333: .Fa from .
334: Note that the
335: .Nm structs
336: type of
337: .Fa "from"
338: and
339: .Fa "to.<name>"
340: must be the same.
341: .Fn structs_set
342: does not modify
343: .Fa from
344: in any way.
345: .Pp
346: .Fn structs_get_string
347: returns the ASCII form of the sub-field
348: .Fa name
349: in the data structure pointed to by
350: .Fa data .
351: This operation is only required to be implemented for primitive types.
352: The returned string is allocated with
353: .Xr typed_mem 3
354: type
355: .Fa mtype ,
356: and the caller is responsible for eventually freeing it.
357: .Pp
358: .Fn structs_set_string
359: changes the contents of the already initialized sub-field
360: .Fa name
361: in the data structure pointed to by
362: .Fa data
363: to the value represented by the ASCII string
364: .Fa ascii .
365: This operation is only required to be implemented for primitive types.
366: If there is an error, e.g.,
367: .Fa ascii
368: is not a valid representation of the type, then
369: .Fn structs_set_string
370: will return -1 and if
371: .Fa ebuf
372: is not
373: .Dv NULL
374: an error message (including terminating '\\0') will be printed into the buffer
375: .Fa ebuf ,
376: which is assumed to have length
377: .Fa emax .
378: .Pp
379: .Fn structs_get_binary
380: and
381: .Fn structs_set_binary
382: are similar, except that they work with byte-order independent,
383: self-delimiting binary data instead of ASCII strings.
384: .Pp
385: .Fn structs_get_binary
386: returns the binary encoding of the sub-field
387: .Fa name
388: in the data structure pointed to by
389: .Fa data .
390: The
391: .Fa code
392: argument is a pointer to a
393: .Li "struct structs_data" :
394: .Pp
395: .Bd -literal -compact -offset 3n
396: struct structs_data {
397: u_int length; /* number of bytes */
398: u_char *data; /* pointer to the bytes */
399: };
400: .Ed
401: .Pp
402: Upon successful return,
403: .Fa "code->data"
404: points to the binary encoding, which has length
405: .Fa "code->length"
406: and is allocated with
407: .Xr typed_mem 3
408: type
409: .Fa mtype .
410: The caller is eventually responsible for freeing
411: .Fa "code->data" .
412: .Pp
413: .Fn structs_set_binary
414: changes the contents of the already initialized sub-field
415: .Fa name
416: in the data structure pointed to by
417: .Fa data
418: to the value represented by the byte-order independent, self-delimiting
419: binary encoding described by
420: .Fa code .
421: On success, the actual number of bytes consumed is returned; this will
422: be less than or equal to
423: .Fa "code->length" .
424: If there is an error, e.g.,
425: the encoding was invalid, then
426: .Fn structs_set_binary
427: will return -1 and if
428: .Fa ebuf
429: is not
430: .Dv NULL
431: an error message (including terminating '\\0') will be printed into the buffer
432: .Fa ebuf ,
433: which is assumed to have length
434: .Fa emax .
435: .Pp
436: .Fn structs_traverse
437: generates a list of the names of all of the "leaf" sub-structures in
438: the data structure pointed to by
439: .Fa data ;
440: these will all have primitive
441: .Nm structs
442: type.
443: It returns the number of elements in the array.
444: A pointer to the array is stored in the location referenced by
445: .Fa listp.
446: Each name in the array, as well as the array itself, is allocated with
447: .Xr typed_mem 3
448: type
449: .Fa mtype .
450: The caller is responsible for freeing all array elements as well as
451: the array itself.
452: .Sh RETURN VALUES
453: All of the above functions indicate an error condition by returning
454: either -1 or
455: .Dv NULL
456: and setting
457: .Va errno
458: to an appropriate value.
459: .Pp
460: Whenever there is an error, no partial work is done: the state of
461: the parameters has not changed, and nothing has been allocated or freed.
462: .Sh SEE ALSO
463: .Xr libpdel 3 ,
464: .Xr structs_type 3 ,
465: .Xr structs_type_array 3 ,
466: .Xr structs_type_boolean 3 ,
467: .Xr structs_type_bpf 3 ,
468: .Xr structs_type_data 3 ,
469: .Xr structs_type_dnsname 3 ,
470: .Xr structs_type_ether 3 ,
471: .Xr structs_type_float 3 ,
472: .Xr structs_type_id 3 ,
473: .Xr structs_type_int 3 ,
474: .Xr structs_type_ip4 3 ,
475: .Xr structs_type_null 3 ,
476: .Xr structs_type_pointer 3 ,
477: .Xr structs_type_regex 3 ,
478: .Xr structs_type_string 3 ,
479: .Xr structs_type_struct 3 ,
480: .Xr structs_type_time 3 ,
481: .Xr structs_type_union 3 ,
482: .Xr structs_xml_input 3 ,
483: .Xr structs_xmlrpc 3 ,
484: .Xr typed_mem 3
485: .Sh HISTORY
486: The PDEL library was developed at Packet Design, LLC.
487: .Dv "http://www.packetdesign.com/"
488: .Sh AUTHORS
489: .An Archie Cobbs Aq archie@freebsd.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to structs.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