Annotation of embedaddon/libpdel/structs/structs_type.3, revision 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