1 /* 2 * Copyright (C) 1997-2004, Michael Jennings 3 * 4 * Permission is hereby granted, free of charge, to any person obtaining a copy 5 * of this software and associated documentation files (the "Software"), to 6 * deal in the Software without restriction, including without limitation the 7 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 8 * sell copies of the Software, and to permit persons to whom the Software is 9 * furnished to do so, subject to the following conditions: 10 * 11 * The above copyright notice and this permission notice shall be included in 12 * all copies of the Software, its documentation and marketing & publicity 13 * materials, and acknowledgment shall be given in the documentation, materials 14 * and software packages that this Software was used. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 19 * THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 20 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 22 */ 23 24 /** 25 * @file types.h 26 * LibAST Portable Data Types 27 * 28 * This file contains a collection of well-defined data types and the 29 * tools for manipulating them. 30 * 31 * @author Michael Jennings <mej@eterm.org> 32 * $Revision: 1.8 $ 33 * $Date: 2003/06/17 00:44:08 $ 34 */ 35 36 #ifndef _LIBAST_TYPES_H_ 37 #define _LIBAST_TYPES_H_ 38 39 40 /** 41 * @defgroup DOXGRP_TYPES LibAST Portable Data Types 42 * 43 * A collection of well-defined data types and the tools for 44 * manipulating them. 45 * 46 * As any C programmer who cares about portability knows, dealing with 47 * different types on different platforms can be a problem. On some 48 * platforms, int is 16-bit and long is 32-bit; on others, both int 49 * and long are 32-bit and there is no long long; others have long 50 * long as a 64-bit integer; and then there are the native 64-bit 51 * platforms where long can also be 64-bit. Not to mention the 52 * presence/absence of boolean types/defines, signed vs. unsigned 53 * char, and so forth. 54 * 55 * LibAST solves this problem by defining data types for specific 56 * integer sizes that are guaranteed to be defined on any system with 57 * LibAST. Also, the basic data types are given their own new data 58 * types which make signedness vs. unsignedness specifically stated, 59 * preventing bad assumptions. 60 * 61 * Also included are macros for building LibAST type names from their 62 * basenames, allocating LibAST objects, typecasting, generating 63 * type-specific NULL comparisons, stringizing NULL values, taking the 64 * size of a LibAST object type, and more. 65 * 66 * There are a few potential gotchas here, so please read the 67 * following documentation carefully for each part you wish to use. 68 */ 69 70 /*@{*/ 71 /** 72 * @name Type Name Composition Macros 73 * --- 74 * 75 * These macros convert basenames like "obj" into actual typenames 76 * like "spif_obj_t." This is primarily intended for use by other 77 * macros and in places where the basename of the type should be 78 * emphasized. 79 * 80 * @note LibAST's use of the term "const type" does @em NOT match the 81 * traditional C definition of the term @c const. When you declare a 82 * variable of a type like @c spif_obj_t or @c SPIF_TYPE(obj), you are 83 * actually defining a pointer variable which will point to an object 84 * of that type. Why a pointer? Because they're the closest thing C 85 * has to references. However, in places where the actual structure 86 * is needed as opposed to to a pointer (like when using sizeof()), 87 * the @c CONST version of the macro should be used instead. 88 * 89 * @ingroup DOXGRP_TYPES 90 */ 91 92 /** 93 * Create a complete type name from its basename. 94 * 95 * This macro converts a basename (such as "obj" or "charptr" or 96 * "uint8") into a namespace-safe full type name. 97 * 98 * @param type The type basename. 99 * @return The full type name. 100 * 101 * @see @link DOXGRP_TYPES Portable Data Types @endlink 102 */ 103 #define SPIF_TYPE(type) spif_ ## type ## _t 104 105 /** 106 * Create a complete const type name from its basename. 107 * 108 * This macro converts a basename (such as "obj" or "charptr" or 109 * "uint8") into a namespace-safe const type name. 110 * 111 * @param type The type basename. 112 * @return The full const type name. 113 * 114 * @see @link DOXGRP_TYPES Portable Data Types @endlink 115 */ 116 #define SPIF_CONST_TYPE(type) spif_const_ ## type ## _t 117 118 /** 119 * Obtain the size of a type from its basename. 120 * 121 * This macro returns the size of the given type basename (such as 122 * "obj" or "str"). This is only used for objects and other 123 * structures whose types are actually struct pointers. 124 * 125 * @param type The type basename. 126 * @return The size of objects/structures of that type. 127 * 128 * @see @link DOXGRP_TYPES Portable Data Types @endlink 129 */ 130 #define SPIF_SIZEOF_TYPE(type) (sizeof(SPIF_CONST_TYPE(type))) 131 132 /** 133 * Define a type and its corresponding const type. 134 * 135 * This macro creates a typedef which maps the const type @a t to the 136 * type specified by @a u and a typedef which maps the type @a t to a 137 * pointer to its const type. Again, this is used for structures. 138 * 139 * @param t The type basename. 140 * @param u The actual type it's being mapped to. 141 * 142 * @see @link DOXGRP_TYPES Portable Data Types @endlink 143 */ 144 #define SPIF_DECL_TYPE(t, u) typedef u SPIF_CONST_TYPE(t); typedef SPIF_CONST_TYPE(t) * SPIF_TYPE(t) 145 /*@}*/ 146 147 /*@{*/ 148 /** 149 * @name Object-Specific Macros 150 * --- 151 * 152 * These macros are intended for use specifically with objects. 153 * 154 * @see @link DOXGRP_OBJ LibAST Object Infrastructure @endlink 155 * @ingroup DOXGRP_TYPES 156 */ 157 158 /** 159 * Allocate an object (or other structured type) by its basename. 160 * 161 * This macro is used primarily in object constructors. It allocates 162 * and returns the specified type. 163 * 164 * @param type The type basename. 165 * @return An allocated object of the specified type. 166 * 167 * @see @link DOXGRP_TYPES Portable Data Types @endlink 168 */ 169 #define SPIF_ALLOC(type) SPIF_CAST(type) MALLOC(SPIF_SIZEOF_TYPE(type)) 170 171 /** 172 * Deallocate an object (or other structured type). 173 * 174 * This macro is used primarily in object destructors. It frees the 175 * memory associated with the specified object and invalidates it. 176 * 177 * @param obj The object to be freed. 178 * 179 * @see @link DOXGRP_TYPES Portable Data Types @endlink 180 */ 181 #define SPIF_DEALLOC(obj) FREE(obj) 182 183 /** 184 * Builds the classname variable for a particular base type. 185 * 186 * This macro converts a basename into the classname for that type. 187 * It is primarily used in initialization of class objects. 188 * 189 * @param type The type basename. 190 * @return A string representing the classname for that type. 191 * 192 * @see @link DOXGRP_TYPES Portable Data Types @endlink 193 */ 194 #define SPIF_DECL_CLASSNAME(type) SPIF_CAST(charptr) "!spif_" #type "_t!" 195 /*@}*/ 196 197 /*@{*/ 198 /** 199 * @name Typecast Macros 200 * --- 201 * 202 * These macros provide typecasting by basename for LibAST types. 203 * Cast macros are also provided for native C types to provide 204 * consistency of casting method. 205 * 206 * @ingroup DOXGRP_TYPES 207 */ 208 209 /** 210 * Typecast to a native C type. 211 * 212 * This macro is identical to traditional C typecasting and is 213 * supplied primarily for consistency. 214 * 215 * @see @link DOXGRP_TYPES Portable Data Types @endlink 216 */ 217 #define SPIF_CAST_C(type) (type) 218 219 /** 220 * Typecast to a const native C type. 221 * 222 * This macro is identical to traditional C typecasting, except that 223 * the @c const keyword is added to the typecast. It is supplied 224 * primarily for consistency. 225 * 226 * @see @link DOXGRP_TYPES Portable Data Types @endlink 227 */ 228 #define SPIF_CONST_CAST_C(type) (const type) 229 230 /** 231 * Typecast to a LibAST type by basename. 232 * 233 * This macro typecasts a value to a particular LibAST type by its 234 * basename. It is usually employed where emphasis on the basename is 235 * desired, particularly with objects. 236 * 237 * @see @link DOXGRP_TYPES Portable Data Types @endlink, SPIF_TYPE() 238 */ 239 #define SPIF_CAST(type) (SPIF_TYPE(type)) 240 241 /** 242 * Typecast to a const LibAST type by basename. 243 * 244 * This macro is identical to SPIF_CAST(), except that the @c const 245 * keyword is added to the typecast. 246 * 247 * @note DO NOT confuse this typecast with the "const type" 248 * terminology. This typecast applies const-ness (i.e., immutability) 249 * to an object or other value. 250 * 251 * @see @link DOXGRP_TYPES Portable Data Types @endlink, SPIF_TYPE(), SPIF_CAST() 252 */ 253 #define SPIF_CONST_CAST(type) (const SPIF_TYPE(type)) 254 255 /** 256 * Typecast to a pointer to a LibAST type by basename. 257 * 258 * This macro typecasts a value to a pointer to a particular LibAST 259 * type by its basename. It is usually employed where emphasis on the 260 * basename is desired, particularly with objects. 261 * 262 * @see @link DOXGRP_TYPES Portable Data Types @endlink, SPIF_TYPE() 263 */ 264 #define SPIF_CAST_PTR(type) (SPIF_TYPE(type) *) 265 266 /** 267 * Typecast to a pointer to a const LibAST type by basename. 268 * 269 * This macro is identical to SPIF_CAST_PTR(), except that the @c 270 * const keyword is added to the typecast. 271 * 272 * @note DO NOT confuse this typecast with the "const type" 273 * terminology. This typecast applies const-ness (i.e., immutability) 274 * to the object or other value referenced by the pointer. 275 * 276 * @see @link DOXGRP_TYPES Portable Data Types @endlink, SPIF_TYPE(), SPIF_CAST_PTR() 277 */ 278 #define SPIF_CONST_CAST_PTR(type) (const SPIF_TYPE(type) *) 279 /*@}*/ 280 281 /*@{*/ 282 /** 283 * @name NULL Handling Macros 284 * --- 285 * 286 * These macros handle typecasting the NULL pointer to a specific 287 * basename/type and printing out values which are set to NULL of a 288 * specific basename/type. 289 * 290 * @ingroup DOXGRP_TYPES 291 */ 292 293 /** 294 * Returns a NULL object of the specified base type. 295 * 296 * This macro returns a NULL object of the type specified by the given 297 * basename. It is generally used for initializing object member 298 * variables and for returning correctly-typed NULL objects. 299 * 300 * @param type The type basename. 301 * @return A NULL object of the specified type. 302 * 303 * @see @link DOXGRP_TYPES Portable Data Types @endlink, SPIF_CAST() 304 */ 305 #define SPIF_NULL_TYPE(type) (SPIF_CAST(type) (NULL)) 306 307 /** 308 * Returns a NULL object of the specified native C type. 309 * 310 * This macro returns a NULL object of the specified C type. It is 311 * included primarily for consistency. 312 * 313 * @param type The native C type. 314 * @return A NULL value of the specified type. 315 * 316 * @see @link DOXGRP_TYPES Portable Data Types @endlink, SPIF_CAST_C() 317 */ 318 #define SPIF_NULL_TYPE_C(type) (SPIF_CAST_C(type) (NULL)) 319 320 /** 321 * Returns a NULL pointer to an object of the specified base type. 322 * 323 * This macro returns a NULL pointer to an object of the type 324 * specified by the given basename. It is generally used for 325 * initializing object member variables and for returning 326 * correctly-typed NULL objects. 327 * 328 * @param type The type basename. 329 * @return A NULL pointer to an object of the specified type. 330 * 331 * @see @link DOXGRP_TYPES Portable Data Types @endlink, SPIF_CAST() 332 */ 333 #define SPIF_NULL_TYPE_PTR(type) (SPIF_CAST_PTR(type) (NULL)) 334 335 /** 336 * Returns a string representing a NULL value of the specified base 337 * type. 338 * 339 * This macro returns a string which shows the NULL value typecast to 340 * the specified type. This is a convenience macro used primarily by 341 * the "show" method of various objects. 342 * 343 * @param type The type basename. 344 * @return A string representation of a NULL object of the 345 * specified type. 346 * 347 * @see @link DOXGRP_TYPES Portable Data Types @endlink 348 */ 349 #define SPIF_NULLSTR_TYPE(type) "{ ((spif_" #type "_t) NULL) }" 350 351 /** 352 * Returns a string representing a NULL value of the specified native 353 * C type. 354 * 355 * This macro returns a string which shows the NULL value typecast to 356 * the specified type. This is a convenience macro used primarily by 357 * the "show" method of various objects. 358 * 359 * @param type The type basename. 360 * @return A string representation of a NULL value of the 361 * specified C type. 362 * 363 * @see @link DOXGRP_TYPES Portable Data Types @endlink 364 */ 365 #define SPIF_NULLSTR_TYPE_C(type) "{ ((" #type ") NULL) }" 366 367 /** 368 * Returns a string representing a NULL value of a pointer to the 369 * specified base type. 370 * 371 * This macro returns a string which shows the NULL value typecast to 372 * a pointer to the specified type. This is a convenience macro used 373 * primarily by the "show" method of various objects. 374 * 375 * @param type The type basename. 376 * @return A string representation of a NULL pointer to an object 377 * of the specified type. 378 * 379 * @see @link DOXGRP_TYPES Portable Data Types @endlink 380 */ 381 #define SPIF_NULLSTR_TYPE_PTR(type) "{ ((spif_" #type "_t *) NULL) }" 382 383 /** 384 * Returns whether or not a generic pointer is NULL. 385 * 386 * This macro returns whether or not a generic pointer is NULL. 387 * 388 * @param p The pointer to test. 389 * @return #TRUE if NULL, #FALSE otherwise. 390 * 391 * @see @link DOXGRP_TYPES Portable Data Types @endlink, SPIF_CAST() 392 */ 393 #define SPIF_PTR_ISNULL(p) ((SPIF_CAST(ptr) (p) == SPIF_NULL_TYPE(ptr)) ? (TRUE) : (FALSE)) 394 /*@}*/ 395 396 /*@{*/ 397 /** 398 * @name Sized Integer Data Types 399 * --- 400 * 401 * These type definitions provide integer types which are guaranteed 402 * portable, guaranteed to be of a specific size, and guaranteed to be 403 * signed or unsigned, according to the name of each type. 404 * 405 * @note Platforms not supporting an integer type of a given size 406 * default to @c long 407 * 408 * @note The definitions shown here in the documentation correspond to 409 * the platform on which the docs were generated and do not 410 * necessarily reflect the actual mappings on your platform. 411 * 412 * @ingroup DOXGRP_TYPES 413 */ 414 415 /** 416 * An 8-bit signed integer. 417 * 418 * An 8-bit signed integer. 419 * 420 * @see @link DOXGRP_TYPES Portable Data Types @endlink 421 */ 422 typedef signed char spif_int8_t; 423 424 /** 425 * An 8-bit unsigned integer. 426 * 427 * An 8-bit unsigned integer. 428 * 429 * @see @link DOXGRP_TYPES Portable Data Types @endlink 430 */ 431 typedef unsigned char spif_uint8_t; 432 433 /** 434 * A 16-bit signed integer. 435 * 436 * A 16-bit signed integer. 437 * 438 * @see @link DOXGRP_TYPES Portable Data Types @endlink 439 */ 440 typedef signed short spif_int16_t; 441 442 /** 443 * A 16-bit unsigned integer. 444 * 445 * A 16-bit unsigned integer. 446 * 447 * @see @link DOXGRP_TYPES Portable Data Types @endlink 448 */ 449 typedef unsigned short spif_uint16_t; 450 451 /** 452 * A 32-bit signed integer. 453 * 454 * A 32-bit signed integer. 455 * 456 * @see @link DOXGRP_TYPES Portable Data Types @endlink 457 */ 458 typedef signed int spif_int32_t; 459 460 /** 461 * A 32-bit unsigned integer. 462 * 463 * A 32-bit unsigned integer. 464 * 465 * @see @link DOXGRP_TYPES Portable Data Types @endlink 466 */ 467 typedef unsigned int spif_uint32_t; 468 469 /** 470 * A 64-bit signed integer. 471 * 472 * A 64-bit signed integer. 473 * 474 * @see @link DOXGRP_TYPES Portable Data Types @endlink 475 */ 476 typedef signed long long spif_int64_t; 477 478 /** 479 * A 64-bit unsigned integer. 480 * 481 * A 64-bit unsigned integer. 482 * 483 * @see @link DOXGRP_TYPES Portable Data Types @endlink 484 */ 485 typedef unsigned long long spif_uint64_t; 486 /*@}*/ 487 488 /*@{*/ 489 /** 490 * @name Portable C-Mapped Data Types 491 * --- 492 * 493 * These type definitions provide versions of the native C types which 494 * are specifically signed or unsigned. Also included are an 495 * explicitly-signed char pointer type, a generic pointer type, and a 496 * generic function pointer type. 497 * 498 * @ingroup DOXGRP_TYPES 499 */ 500 501 /** 502 * A signed char. 503 * 504 * A signed char. 505 * 506 * @see @link DOXGRP_TYPES Portable Data Types @endlink 507 */ 508 typedef signed char spif_char_t; 509 510 /** 511 * A signed short. 512 * 513 * A signed short. 514 * 515 * @see @link DOXGRP_TYPES Portable Data Types @endlink 516 */ 517 typedef signed short spif_short_t; 518 519 /** 520 * A signed int. 521 * 522 * A signed int. 523 * 524 * @see @link DOXGRP_TYPES Portable Data Types @endlink 525 */ 526 typedef signed int spif_int_t; 527 528 /** 529 * A signed long. 530 * 531 * A signed long. 532 * 533 * @see @link DOXGRP_TYPES Portable Data Types @endlink 534 */ 535 typedef signed long spif_long_t; 536 537 /** 538 * An unsigned char. 539 * 540 * An unsigned char. 541 * 542 * @see @link DOXGRP_TYPES Portable Data Types @endlink 543 */ 544 typedef unsigned char spif_uchar_t; 545 546 /** 547 * An unsigned short. 548 * 549 * An unsigned short. 550 * 551 * @see @link DOXGRP_TYPES Portable Data Types @endlink 552 */ 553 typedef unsigned short spif_ushort_t; 554 555 /** 556 * An unsigned int. 557 * 558 * An unsigned int. 559 * 560 * @see @link DOXGRP_TYPES Portable Data Types @endlink 561 */ 562 typedef unsigned int spif_uint_t; 563 564 /** 565 * An unsigned long. 566 * 567 * An unsigned long. 568 * 569 * @see @link DOXGRP_TYPES Portable Data Types @endlink 570 */ 571 typedef unsigned long spif_ulong_t; 572 573 /** 574 * A pointer to a signed char. 575 * 576 * A pointer to a signed char. 577 * 578 * @see @link DOXGRP_TYPES Portable Data Types @endlink 579 */ 580 typedef spif_char_t *spif_charptr_t; 581 582 /** 583 * A pointer to a byte of data. 584 * 585 * A pointer to a byte of data. 586 * 587 * @see @link DOXGRP_TYPES Portable Data Types @endlink 588 */ 589 typedef spif_uint8_t *spif_byteptr_t; 590 591 /** 592 * A generic, untyped pointer. 593 * 594 * A generic, untyped pointer. 595 * 596 * @see @link DOXGRP_TYPES Portable Data Types @endlink 597 */ 598 typedef void *spif_ptr_t; 599 600 /** 601 * A generic function pointer. 602 * 603 * A generic function pointer. 604 * 605 * @see @link DOXGRP_TYPES Portable Data Types @endlink 606 */ 607 typedef void * (*spif_func_t)(); 608 609 /** 610 * A class name. 611 * 612 * This typedef abstracts the actual type of a classname variable. At 613 * this point I can't imagine it needing to be anything else, but one 614 * never knows.... 615 * 616 * @see @link DOXGRP_TYPES Portable Data Types @endlink 617 */ 618 typedef spif_charptr_t spif_classname_t; 619 620 /** 621 * Convenience macro for typecasting to spif_charptr_t. 622 * 623 * This macro typecasts a value to a spif_charptr_t. I got really 624 * tired of typing "SPIF_CAST(charptr)" all the time, especially for 625 * string constants. :-) 626 * 627 * @see @link DOXGRP_TYPES Portable Data Types @endlink, SPIF_CAST(), spif_charptr_t 628 */ 629 #define SPIF_CHARPTR(var) (SPIF_CAST(charptr) (var)) 630 631 /** 632 * Convenience macro for typecasting to C's default char * type. 633 * 634 * This macro typecasts a value to whatever "char *" is on the current 635 * system. This is used to typecast a spif_charptr_t back to the 636 * native C type for use in standard libc functions. 637 * 638 * @see @link DOXGRP_TYPES Portable Data Types @endlink, SPIF_CAST(), spif_charptr_t 639 */ 640 #define SPIF_CHARPTR_C(var) (SPIF_CAST_C(char *) (var)) 641 642 /*@}*/ 643 644 /*@{*/ 645 /** 646 * @name Portable Socket Types 647 * --- 648 * 649 * These types provide portability and name-mapping for the values 650 * and types used in socket code. These are used by the LibAST socket 651 * object and should not need to be used in end-user code. 652 * 653 * @bug FIXME: These mappings are currently hard-coded. 654 * 655 * @ingroup DOXGRP_TYPES 656 */ 657 658 /** 659 * A generic socket address. 660 * 661 * @internal 662 * This type references a generic socket address structure. It is 663 * used for typecasting the protocol-based pointers (see below) to a 664 * generic type suitable for use as a parameter to socket functions. 665 * 666 * @see @link DOXGRP_TYPES Portable Data Types @endlink 667 */ 668 SPIF_DECL_TYPE(sockaddr, struct sockaddr); 669 670 /** 671 * A socket address for the IPv4 protocol family. 672 * 673 * @internal 674 * This type references an IPv4 socket address structure. It is used 675 * to store IP addressing information for a given socket. 676 * 677 * @see @link DOXGRP_TYPES Portable Data Types @endlink 678 */ 679 SPIF_DECL_TYPE(ipsockaddr, struct sockaddr_in); 680 681 /** 682 * A socket address for the UNIX protocol family. 683 * 684 * @internal 685 * This type references a UNIX socket address structure. It is used 686 * to store addressing information for a given UNIX socket. 687 * 688 * @see @link DOXGRP_TYPES Portable Data Types @endlink 689 */ 690 SPIF_DECL_TYPE(unixsockaddr, struct sockaddr_un); 691 692 /** 693 * An IPv4 address. 694 * 695 * @internal 696 * This type references an IPv4 address in native host format. 697 * 698 * @see @link DOXGRP_TYPES Portable Data Types @endlink 699 */ 700 SPIF_DECL_TYPE(ipaddr, struct in_addr); 701 702 /** 703 * Host information. 704 * 705 * @internal 706 * This type references host information in native host format. 707 * 708 * @see @link DOXGRP_TYPES Portable Data Types @endlink 709 */ 710 SPIF_DECL_TYPE(hostinfo, struct hostent); 711 712 /** 713 * Protocol information. 714 * 715 * @internal 716 * This type references protocol information in native host format. 717 * 718 * @see @link DOXGRP_TYPES Portable Data Types @endlink 719 */ 720 SPIF_DECL_TYPE(protoinfo, struct protoent); 721 722 /** 723 * Service information. 724 * 725 * @internal 726 * This type references service information in native host format. 727 * 728 * @see @link DOXGRP_TYPES Portable Data Types @endlink 729 */ 730 SPIF_DECL_TYPE(servinfo, struct servent); 731 732 /** 733 * The file descriptor for a socket. 734 * 735 * This type encapsulates the actual type of the socket file 736 * descriptor. 737 * 738 * @see @link DOXGRP_TYPES Portable Data Types @endlink 739 */ 740 typedef int spif_sockfd_t; 741 742 /** 743 * The protocol family for a socket. 744 * 745 * This type encapsulates the actual representation of the protocol 746 * family. 747 * 748 * @see @link DOXGRP_TYPES Portable Data Types @endlink 749 */ 750 typedef int spif_sockfamily_t; 751 752 /** 753 * The type of a socket. 754 * 755 * This type encapsulates the actual representation of the socket 756 * type. 757 * 758 * @see @link DOXGRP_TYPES Portable Data Types @endlink 759 */ 760 typedef int spif_socktype_t; 761 762 /** 763 * A socket protocol. 764 * 765 * This type encapsulates the actual representation of a socket 766 * protocol. 767 * 768 * @see @link DOXGRP_TYPES Portable Data Types @endlink 769 */ 770 typedef int spif_sockproto_t; 771 772 /** 773 * A socket port. 774 * 775 * This type encapsulates the actual representation of a socket's 776 * port. 777 * 778 * @see @link DOXGRP_TYPES Portable Data Types @endlink 779 */ 780 typedef spif_uint16_t spif_sockport_t; 781 782 /** 783 * The length of a socket address structure. 784 * 785 * This type encapsulates the actual representation of the size of a 786 * socket address structure. 787 * 788 * @see @link DOXGRP_TYPES Portable Data Types @endlink 789 */ 790 typedef socklen_t spif_sockaddr_len_t; 791 /*@}*/ 792 793 /*@{*/ 794 /** 795 * @name Portable Enumerated Data Types 796 * --- 797 * 798 * These typedefs and macros provide portable, consistent 799 * implementations of arbitrary comparison functionality and boolean 800 * variables. 801 * 802 * @ingroup DOXGRP_TYPES 803 */ 804 805 /** 806 * An enumerated type for comparisons. 807 * 808 * The defacto standard for the return value of a function or 809 * operation which compares two things comes from the return value of 810 * the @c strcmp() family of functions: An integer less than, equal 811 * to, or greater than zero representing that the first value is less 812 * than, equal to, or greater than (respectively) the second value. 813 * This type makes such comparisons more readable and provides 814 * specific, defined values for each case. Macros are provided to 815 * improve readability and simplify conversion from other comparison 816 * functions. 817 * 818 * @see @link DOXGRP_TYPES Portable Data Types @endlink, SPIF_CMP_FROM_INT(), SPIF_CMP_IS_LESS(), 819 * SPIF_CMP_IS_EQUAL(), SPIF_CMP_IS_GREATER() 820 */ 821 typedef enum { 822 SPIF_CMP_LESS = -1, 823 SPIF_CMP_EQUAL = 0, 824 SPIF_CMP_GREATER = 1 825 } spif_cmp_t; 826 827 /** 828 * Convert a traditional integer comparison result to a spif_cmp_t 829 * value. 830 * 831 * This convenience macro accepts an integer value less than, equal 832 * to, or greater than zero (as traditionally supplied by comparison 833 * functions) and converts that value to SPIF_CMP_LESS, 834 * SPIF_CMP_EQUAL, or SPIF_CMP_GREATER, respectively. 835 * 836 * @note This macro evaluates its parameter twice, so beware of side 837 * effects. 838 * 839 * @param i A traditional integer comparison value. 840 * @return The corresponding spif_cmp_t value. 841 * 842 * @see @link DOXGRP_TYPES Portable Data Types @endlink, spif_cmp_t 843 */ 844 #define SPIF_CMP_FROM_INT(i) ((SPIF_CAST_C(int) (i) < 0) ? (SPIF_CMP_LESS) : ((SPIF_CAST_C(int) (i) > 0) ? (SPIF_CMP_GREATER) : (SPIF_CMP_EQUAL))) 845 846 /** 847 * Check if a comparison value is SPIF_CMP_LESS. 848 * 849 * This convenience macro determines if a given comparison expression 850 * or value evaluates to SPIF_CMP_LESS. The @a cmp expression is only 851 * evaluated once, so this macro can safely be used on comparison 852 * expressions like SPIF_CMP_FROM_INT(). 853 * 854 * @param cmp Comparison expression or value of type spif_cmp_t. 855 * @return True if the result is SPIF_CMP_LESS, false otherwise. 856 * 857 * @see @link DOXGRP_TYPES Portable Data Types @endlink, spif_cmp_t, SPIF_CMP_FROM_INT() 858 */ 859 #define SPIF_CMP_IS_LESS(cmp) ((cmp) == SPIF_CMP_LESS) 860 861 /** 862 * Check if a comparison value is SPIF_CMP_EQUAL. 863 * 864 * This convenience macro determines if a given comparison expression 865 * or value evaluates to SPIF_CMP_EQUAL. The @a cmp expression is 866 * only evaluated once, so this macro can safely be used on comparison 867 * expressions like SPIF_CMP_FROM_INT(). 868 * 869 * @param cmp Comparison expression or value of type spif_cmp_t. 870 * @return True if the result is SPIF_CMP_EQUAL, false otherwise. 871 * 872 * @see @link DOXGRP_TYPES Portable Data Types @endlink, spif_cmp_t, SPIF_CMP_FROM_INT() 873 */ 874 #define SPIF_CMP_IS_EQUAL(cmp) ((cmp) == SPIF_CMP_EQUAL) 875 876 /** 877 * Check if a comparison value is SPIF_CMP_GREATER. 878 * 879 * This convenience macro determines if a given comparison expression 880 * or value evaluates to SPIF_CMP_GREATER. The @a cmp expression is 881 * only evaluated once, so this macro can safely be used on comparison 882 * expressions like SPIF_CMP_FROM_INT(). 883 * 884 * @param cmp Comparison expression or value of type spif_cmp_t. 885 * @return True if the result is SPIF_CMP_GREATER, false otherwise. 886 * 887 * @see @link DOXGRP_TYPES Portable Data Types @endlink, spif_cmp_t, SPIF_CMP_FROM_INT() 888 */ 889 #define SPIF_CMP_IS_GREATER(cmp) ((cmp) == SPIF_CMP_GREATER) 890 891 /** 892 * Convenience macro for comparing possibly NULL values. 893 * 894 * This macro exists because I got tired of typing the same thing over 895 * and over again to handle comparisons of two pointers, either of 896 * which may be NULL. 897 * 898 * @param p1 The first pointer. 899 * @param p2 The second pointer. 900 * @return 901 * 902 * @see @link DOXGRP_STRINGS String Utility Routines @endlink, SPIF_PTR_ISNULL() 903 */ 904 #define SPIF_COMP_CHECK_NULL(p1, p2) do { \ 905 if (SPIF_PTR_ISNULL((p1)) && SPIF_PTR_ISNULL((p2))) { \ 906 return SPIF_CMP_EQUAL; \ 907 } else if (SPIF_PTR_ISNULL((p1))) { \ 908 return SPIF_CMP_LESS; \ 909 } else if (SPIF_PTR_ISNULL((p2))) { \ 910 return SPIF_CMP_GREATER; \ 911 } \ 912 } while (0) 913 914 #undef false 915 #undef False 916 #undef FALSE 917 #undef true 918 #undef True 919 #undef TRUE 920 921 /** 922 * An enumerated type for boolean values. 923 * 924 * Unlike C++, C does not have a native boolean type. Having one, 925 * while strictly not necessary, tends to make for more readable 926 * code. So LibAST defines a boolean type and maps the most common 927 * values into it (i.e., TRUE, True, and true along with FALSE, False, 928 * and false). 929 * 930 * @note Because "false" and "true" are C++ reserved words, compiling 931 * LibAST with a C++ compiler will disable these values as members of 932 * the spif_bool_t data type. For this and other reasons (namely 933 * readability), use of "TRUE" and "FALSE" is preferred. 934 * 935 * @see @link DOXGRP_TYPES Portable Data Types @endlink 936 */ 937 typedef enum { 938 #ifndef __cplusplus 939 false = 0, 940 #endif 941 False = 0, 942 FALSE = 0, 943 #ifndef __cplusplus 944 true = 1, 945 #endif 946 True = 1, 947 TRUE = 1 948 } spif_bool_t; 949 /*@}*/ 950 951 #endif /* _LIBAST_TYPES_H_ */ 952