Annotation of embedaddon/libpdel/structs/structs_type.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.3,v 1.13 2004/06/02 17:24:38 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt STRUCTS_TYPE 3
42: .Os
43: .Sh NAME
44: .Nm structs_type
45: .Nd data structure description structure
46: .Sh LIBRARY
47: PDEL Library (libpdel, \-lpdel)
48: .Sh SYNOPSIS
49: .In sys/types.h
50: .In pdel/structs/structs.h
51: .Sh DESCRIPTION
52: A
53: .Nm "structs type"
54: defines information about, and provides methods for dealing with,
55: instances of a particular data structure.
56: This information enables the
57: .Xr structs 3
58: library to access instances of the data structure in a consistent
59: and automated fashion.
60: .Pp
61: A
62: .Nm "structs type"
63: is defined by a
64: .Li "struct structs_type" :
65: .Pp
66: .Bd -literal -compact -offset 3n
67: struct structs_type {
68: size_t size; /* size of an instance */
69: const char *name; /* human informative name */
70: int tclass; /* type class */
71: structs_init_t *init; /* type "init" method */
72: structs_copy_t *copy; /* type "copy" method */
73: structs_equal_t *equal; /* type "equal" method */
74: structs_ascify_t *ascify; /* type "ascify" method */
75: structs_binify_t *binify; /* type "binify" method */
76: structs_encode_t *encode; /* type "encode" method */
77: structs_decode_t *decode; /* type "decode" method */
78: structs_uninit_t *uninit; /* type "uninit" method */
79: union { /* type specific arguments */
80: const void *v;
81: const char *s;
82: int i;
83: } args[3];
84: };
85: .Ed
86: .Pp
87: .Fa size
88: is equal to the size of one instance of the data structure.
89: .Pp
90: The
91: .Fa name
92: is ignored by the
93: .Nm structs
94: library, but is useful for debugging purposes.
95: .Pp
96: .Fa tclass
97: is an internal field used by the
98: .Nm structs
99: library.
100: For completeness, the possible values are:
101: .Pp
102: .Bd -literal -compact -offset 3n
103: STRUCTS_TYPE_PRIMITIVE Primitive type
104: STRUCTS_TYPE_POINTER Pointer
105: STRUCTS_TYPE_ARRAY Variable length array
106: STRUCTS_TYPE_FIXEDARRAY Fixed length array
107: STRUCTS_TYPE_STRUCTURE Structure type
108: STRUCTS_TYPE_UNION Union
109: .Ed
110: .Pp
111: For user-defined types,
112: .Dv STRUCTS_TYPE_PRIMITIVE
113: should always be used.
114: .Pp
115: The
116: .Fn init
117: method has this type:
118: .Pp
119: .Bd -literal -compact -offset 3n
120: typedef int structs_init_t(const struct structs_type *type,
121: void *data);
122: .Ed
123: .Pp
124: It should initialize the uninitialized region of memory pointed to by
125: .Fa data
126: to be an instance of the type.
127: The instance should be equal to the default value for the type.
128: On success,
129: .Fn init
130: returns zero; otherwise, it returns -1 and sets
131: .Va errno
132: appropriately, and no resources have been allocated.
133: .Pp
134: The
135: .Fn copy
136: method has this type:
137: .Pp
138: .Bd -literal -compact -offset 3n
139: typedef int structs_copy_t(const struct structs_type *type,
140: const void *from, void *to);
141: .Ed
142: .Pp
143: It should initialize the uninitialized region of memory pointed to by
144: .Fa to
145: to be a new instance of the type equal to the instance pointed to by
146: .Fa from .
147: On success,
148: .Fn copy
149: returns zero; otherwise, it returns -1 and sets
150: .Va errno
151: appropriately, and no resources have been allocated.
152: .Pp
153: The
154: .Fn equal
155: method has this type:
156: .Pp
157: .Bd -literal -compact -offset 3n
158: typedef int structs_equal_t(const struct structs_type *type,
159: const void *data1, const void *data2);
160: .Ed
161: .Pp
162: .Fa data1
163: and
164: .Fa data2
165: point to initialized instances of the type
166: .Fa type .
167: .Fn equal
168: should return 1 if the two instances are equal, or 0 if not.
169: If an error occurs,
170: .Fn equal
171: returns -1 and sets
172: .Va errno
173: appropriately.
174: .Pp
175: The
176: .Fn ascify
177: method has this type:
178: .Pp
179: .Bd -literal -compact -offset 3n
180: typedef char *structs_ascify_t(const struct structs_type *type,
181: const char *mtype, const void *data);
182: .Ed
183: .Pp
184: .Fa data
185: points to an initialized instance of the type
186: .Fa type .
187: .Fn ascify
188: should convert this instance into an ASCII string terminated with '\\0' and
189: stored in a buffer allocated with
190: .Xr typed_mem 3
191: type
192: .Fa mtype .
193: The ASCII string must be unique, in the sense that it can be used as input
194: to the
195: .Fn binify
196: method to create an instance equal to the original
197: .Fa data .
198: If successful,
199: .Fn ascify
200: returns the ASCII string buffer; otherwise it returns
201: .Dv NULL
202: and sets
203: .Va errno
204: appropriately.
205: .Pp
206: The
207: .Fn binify
208: method has this type:
209: .Pp
210: .Bd -literal -compact -offset 3n
211: typedef int structs_binify_t(const struct structs_type *type,
212: const char *ascii, void *data,
213: char *ebuf, size_t emax);
214: .Ed
215: .Pp
216: .Fa data
217: points to an uninitialized region of memory large enough to hold an
218: instance of the type
219: .Fa type .
220: .Fn binify
221: should convert the ASCII string pointed to by
222: .Fa ascii
223: into an instance stored at
224: .Fa data ,
225: thus initializing the memory, and return zero.
226: If an error occurs,
227: .Fa data
228: should remain uninitialized and
229: .Fn binify
230: should return -1;
231: it may also optionally write an explanatory error message,
232: including '\\0' byte, into the character buffer having length
233: .Fa emax
234: and pointed to by
235: .Fa ebuf
236: (see
237: .Xr snprintf 3) .
238: .Fn binify
239: must successfully convert any ASCII string returned by
240: .Fn ascify .
241: However,
242: .Fa ascii
243: is by no means guaranteed to be valid;
244: .Fn binify
245: must gracefully handle any invalid input string by
246: returning an error instead of crashing.
247: .Pp
248: The
249: .Fn encode
250: method has this type:
251: .Pp
252: .Bd -literal -compact -offset 3n
253: typedef int structs_encode_t(const struct structs_type *type,
254: const char *mtype, struct structs_data *code,
255: const void *data);
256: .Ed
257: .Pp
258: .Fa data
259: points to an initialized instance of the type
260: .Fa type .
261: .Fn encode
262: should encode the instance into a byte-order independent, self-delimiting
263: sequence of bytes.
264: The sequence should be stored in a buffer allocated with
265: .Xr typed_mem 3
266: type
267: .Fa mtype .
268: The
269: .Fa code
270: structure, shown below, should be filled in with the buffer start and length:
271: .Pp
272: .Bd -literal -compact -offset 3n
273: struct structs_data {
274: u_int length; /* number of bytes */
275: u_char *data; /* byte sequence */
276: };
277: .Ed
278: .Pp
279: The binary sequence must be unique, in the sense that it can be used as
280: input to the
281: .Fn decode
282: method to create an instance equal to the original
283: .Fa data .
284: .Fn encode
285: returns 0 if successful; otherwise it returns -1 and sets
286: .Va errno
287: appropriately and does not allocate any memory.
288: .Pp
289: The
290: .Fn decode
291: method has this type:
292: .Pp
293: .Bd -literal -compact -offset 3n
294: typedef int structs_decode_t(const struct structs_type *type,
295: const u_char *code, size_t cmax, void *data,
296: char *ebuf, size_t emax);
297: .Ed
298: .Pp
299: .Fa data
300: points to an uninitialized region of memory large enough to hold an
301: instance of the type
302: .Fa type .
303: .Fn decode
304: should convert the binary sequence pointed to by
305: .Fa code
306: into an instance stored at
307: .Fa data ,
308: thus initializing the memory.
309: .Fn decode
310: should return the number of bytes consumed, of the
311: .Fa cmax
312: total bytes available.
313: Note that
314: .Fa cmax
315: bytes may include additional bytes beyond those necessary for decoding
316: one instance of
317: .Fa type ;
318: this is why encodings generated by
319: .Fn encode
320: must be self-delimiting.
321: If an error occurs,
322: .Fa data
323: should remain uninitialized and
324: .Fn decode
325: should return -1;
326: it may also optionally write an explanatory error message,
327: including '\\0' byte, into the character buffer having length
328: .Fa emax
329: and pointed to by
330: .Fa ebuf
331: (see
332: .Xr snprintf 3) .
333: .Fn decode
334: must successfully convert any byte sequence generated by
335: .Fn encode .
336: However, the sequence defined by
337: .Fa code
338: and
339: .Fa cmax
340: is by no means guaranteed to be valid, have any particular length, etc.
341: .Fn decode
342: must gracefully handle any invalid input sequence by
343: returning an error instead of crashing.
344: .Pp
345: The
346: .Fn uninit
347: method has this type:
348: .Pp
349: .Bd -literal -compact -offset 3n
350: typedef void structs_uninit_t(const struct structs_type *type,
351: void *data);
352: .Ed
353: .Pp
354: .Fa data
355: points to an initialized instance of the type
356: .Fa type .
357: .Fn uninit
358: should free any resources allocated on behalf of the instance,
359: returning the memory region to an uninitialized state.
360: .Pp
361: The
362: .Fa args
363: array is useful for when the same functions are used to implement
364: several distinct but related types.
365: .Ss "Predefined Methods"
366: The following
367: .Nm "structs type"
368: methods are defined in the
369: .Xr structs 3
370: library:
371: .Pp
372: .Bl -tag -width "abcde"
373: .It Li "structs_region_init()"
374: .Fn init
375: method that fills in the region of memory with zeros.
376: .It Li "structs_region_copy()"
377: .Fn copy
378: method that copies the instance using
379: .Xr memcpy 3 .
380: .It Li "structs_region_equal()"
381: .Fn equal
382: method that compares two instances using
383: .Xr memcmp 3 .
384: .It Li "structs_region_encode()"
385: .Fn encode
386: method that encodes an instance by directly copying the bytes.
387: Note: this method is incorrect for host-order dependent data.
388: .It Li "structs_region_decode()"
389: Decodes data encoded by
390: .Li "structs_region_encode()" .
391: .It Li "structs_region_encode_netorder()"
392: .Fn encode
393: method that encodes an instance by copying it, after arranging the bytes
394: in network order.
395: Only valid for data types that have size 16 bytes or less.
396: .It Li "structs_region_decode_netorder()"
397: Decodes data encoded by
398: .Li "structs_region_encode_netorder()" .
399: .It Li "structs_nothing_free()"
400: .Fn free
401: method that does nothing.
402: .It Li "structs_ascii_copy()"
403: .Fn copy
404: method that copies an instance by converting it to ASCII and back.
405: This should work for any primitive type.
406: .It Li "structs_string_encode()"
407: .It Li "structs_string_decode()"
408: .Fn encode
409: and
410: .Fn decode
411: methods that encode an instance by converting it to a NUL-terminated
412: ASCII string.
413: These methods should work for any primitive type.
414: .It Li "structs_notsupp_init()"
415: .Fn encode
416: method that always returns -1 with
417: .Va errno
418: set to
419: .Er ENOTSUPP .
420: .It Li "structs_notsupp_copy()"
421: .Fn copy
422: method that always returns -1 with
423: .Va errno
424: set to
425: .Er ENOTSUPP .
426: .It Li "structs_notsupp_equal()"
427: .Fn equal
428: method that always returns -1 with
429: .Va errno
430: set to
431: .Er ENOTSUPP .
432: .It Li "structs_notsupp_ascify()"
433: .Fn ascify
434: method that always returns -1 with
435: .Va errno
436: set to
437: .Er ENOTSUPP .
438: .It Li "structs_notsupp_binify()"
439: .Fn binify
440: method that always returns -1 with
441: .Va errno
442: set to
443: .Er ENOTSUPP .
444: .It Li "structs_notsupp_encode()"
445: .Fn encode
446: method that always returns -1 with
447: .Va errno
448: set to
449: .Er ENOTSUPP .
450: .It Li "structs_notsupp_decode()"
451: .Fn decode
452: method that always returns -1 with
453: .Va errno
454: set to
455: .Er ENOTSUPP .
456: .El
457: .Pp
458: .Sh RETURN VALUES
459: All of the above functions indicate an error condition by returning
460: either -1 or
461: .Dv NULL
462: and setting
463: .Va errno
464: to an appropriate value.
465: .Pp
466: Whenever there is an error, no partial work is done: the state of
467: the parameters has not changed, and nothing has been allocated or freed.
468: .Sh SEE ALSO
469: .Xr libpdel 3 ,
470: .Xr snprintf 3 ,
471: .Xr structs 3 ,
472: .Xr structs_type_array 3 ,
473: .Xr structs_type_boolean 3 ,
474: .Xr structs_type_bpf 3 ,
475: .Xr structs_type_data 3 ,
476: .Xr structs_type_dnsname 3 ,
477: .Xr structs_type_ether 3 ,
478: .Xr structs_type_float 3 ,
479: .Xr structs_type_id 3 ,
480: .Xr structs_type_int 3 ,
481: .Xr structs_type_ip4 3 ,
482: .Xr structs_type_ip6 3 ,
483: .Xr structs_type_null 3 ,
484: .Xr structs_type_pointer 3 ,
485: .Xr structs_type_regex 3 ,
486: .Xr structs_type_string 3 ,
487: .Xr structs_type_struct 3 ,
488: .Xr structs_type_time 3 ,
489: .Xr structs_type_union 3 ,
490: .Xr typed_mem 3
491: .Sh HISTORY
492: The PDEL library was developed at Packet Design, LLC.
493: .Dv "http://www.packetdesign.com/"
494: .Sh AUTHORS
495: .An Archie Cobbs Aq archie@freebsd.org
496: .Sh BUGS
497: Instead of the
498: .Fa tclass
499: field, each type should provide its own method for accessing sub-elements
500: as appropriate.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to structs_type.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