1/* 2 * Copyright 2007-2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Niels Sascha Reedijk, niels.reedijk@gmail.com 7 * John Scipione, jscipione@gmail.com 8 * 9 * Corresponds to: 10 * headers/os/support/SupportDefs.h rev 35018 11 */ 12 13 14/*! 15 \file SupportDefs.h 16 \ingroup support 17 \ingroup libbe 18 \brief Defines basic types and definitions for the Haiku API. 19*/ 20 21 22/*! 23 \name Fixed-Size Integer Types 24*/ 25 26 27//! @{ 28 29 30/*! 31 \typedef typedef __haiku_int8 int8 32*/ 33 34 35/*! 36 \typedef typedef __haiku_uint8 uint8 37*/ 38 39 40/*! 41 \typedef typedef __haiku_int16 int16 42*/ 43 44 45/*! 46 \typedef typedef __haiku_uint16 uint16 47*/ 48 49 50/*! 51 \typedef typedef __haiku_int32 int32 52*/ 53 54 55/*! 56 \typedef typedef __haiku_uint32 uint32 57*/ 58 59 60/*! 61 \typedef typedef __haiku_int64 int64 62*/ 63 64 65/*! 66 \typedef typedef __haiku_uint64 uint64 67*/ 68 69 70//! @} 71 72 73/*! 74 \name Fixed-size Volatile Types 75*/ 76 77 78//! @{ 79 80 81/*! 82 \typedef typedef volatile int8 vint8 83*/ 84 85 86/*! 87 \typedef typedef volatile uint8 vuint8 88*/ 89 90 91/*! 92 \typedef typedef volatile int16 vint16 93*/ 94 95 96/*! 97 \typedef typedef volatile uint16 vuint16 98*/ 99 100 101/*! 102 \typedef typedef volatile int32 vint32 103*/ 104 105 106/*! 107 \typedef typedef volatile uint32 vuint32 108*/ 109 110 111/*! 112 \typedef typedef volatile int64 vint64 113*/ 114 115 116/*! 117 \typedef typedef volatile uint64 vuint64 118*/ 119 120 121//! @} 122 123 124/*! 125 \name Short-hand Volatile Type Names 126*/ 127 128 129//! @{ 130 131 132/*! 133 \typedef typedef volatile long vlong 134*/ 135 136 137/*! 138 \typedef typedef volatile int vint 139*/ 140 141 142/*! 143 \typedef typedef volatile short vshort 144*/ 145 146 147/*! 148 \typedef typedef volatile char vchar 149*/ 150 151 152/*! 153 \typedef typedef volatile unsigned long vulong 154*/ 155 156 157/*! 158 \typedef typedef volatile unsigned int vuint 159*/ 160 161 162/*! 163 \typedef typedef volatile unsigned short vushort 164*/ 165 166 167/*! 168 \typedef typedef volatile unsigned char vuchar 169*/ 170 171 172//! @} 173 174 175/*! 176 \name Character Type Formats 177*/ 178 179 180//! @{ 181 182 183/*! 184 \typedef typedef unsigned char uchar 185*/ 186 187 188/*! 189 \typedef typedef unsigned short unichar 190*/ 191 192 193//! @} 194 195 196/*! 197 \name Descriptive Type Formats 198*/ 199 200 201//! @{ 202 203 204/*! 205 \typedef typedef int32 status_t 206 \brief Represents one of the status codes defined in Error.h. 207 208 \since BeOS R3 209*/ 210 211 212/*! 213 \typedef typedef int64 bigtime_t 214 \brief Represents time. The unit depends on the context of the function. 215 216 \since BeOS R3 217*/ 218 219 220/*! 221 \typedef typedef int64 nanotime_t 222 \brief Represents time in nanoseconds. 223*/ 224 225 226/*! 227 \typedef typedef uint32 type_code 228 \brief Represents a certain type of data. See TypeConstants.h for 229 possible values. 230 231 \since Haiku R1 232*/ 233 234 235/*! 236 \typedef typedef uint32 perform_code 237 \brief Defined to support 'hidden' commands or extensions to classes. 238 239 The Haiku API has none of these. 240 241 \since Haiku R1 242*/ 243 244 245//! @} 246 247 248/*! 249 \name Format strings for printf() and scanf() 250*/ 251 252 253//! @{ 254 255 256/*! 257 \def B_PRId8 258*/ 259 260 261/*! 262 \def B_PRIi8 263*/ 264 265 266/*! 267 \def B_PRId16 268*/ 269 270 271/*! 272 \def B_PRIi16 273*/ 274 275 276/*! 277 \def B_PRId32 278*/ 279 280 281/*! 282 \def B_PRIi32 283*/ 284 285 286/*! 287 \def B_PRId64 288*/ 289 290 291/*! 292 \def B_PRIi64 293*/ 294 295 296/*! 297 \def B_PRIu8 298*/ 299 300 301/*! 302 \def B_PRIo8 303*/ 304 305 306/*! 307 \def B_PRIx8 308*/ 309 310 311/*! 312 \def B_PRIX8 313*/ 314 315 316/*! 317 \def B_PRIu16 318*/ 319 320 321/*! 322 \def B_PRIo16 323*/ 324 325 326/*! 327 \def B_PRIx16 328*/ 329 330 331/*! 332 \def B_PRIX16 333*/ 334 335 336/*! 337 \def B_PRIu32 338*/ 339 340 341/*! 342 \def B_PRIo32 343*/ 344 345 346/*! 347 \def B_PRIx32 348*/ 349 350 351/*! 352 \def B_PRIX32 353*/ 354 355 356/*! 357 \def B_PRIu64 358*/ 359 360 361/*! 362 \def B_PRIo64 363*/ 364 365 366/*! 367 \def B_PRIx64 368*/ 369 370 371/*! 372 \def B_PRIX64 373*/ 374 375 376/*! 377 \def B_SCNd8 378*/ 379 380 381/*! 382 \def B_SCNi8 383*/ 384 385 386/*! 387 \def B_SCNd16 388*/ 389 390 391/*! 392 \def B_SCNi16 393*/ 394 395 396/*! 397 \def B_SCNd32 398*/ 399 400 401/*! 402 \def B_SCNi32 403*/ 404 405 406/*! 407 \def B_SCNd64 408*/ 409 410 411/*! 412 \def B_SCNi64 413*/ 414 415 416/*! 417 \def B_SCNu8 418*/ 419 420 421/*! 422 \def B_SCNo8 423*/ 424 425 426/*! 427 \def B_SCNx8 428*/ 429 430 431/*! 432 \def B_SCNu16 433*/ 434 435 436/*! 437 \def B_SCNo16 438*/ 439 440 441/*! 442 \def B_SCNx16 443*/ 444 445 446/*! 447 \def B_SCNu32 448*/ 449 450 451/*! 452 \def B_SCNo32 453*/ 454 455 456/*! 457 \def B_SCNx32 458*/ 459 460 461/*! 462 \def B_SCNu64 463*/ 464 465 466/*! 467 \def B_SCNo64 468*/ 469 470 471/*! 472 \def B_SCNx64 473*/ 474 475 476//! @} 477 478 479/*! 480 \name Format strings for several standard types 481*/ 482 483 484//! @{ 485 486 487/*! 488 \def B_PRIuSIZE 489 \brief size_t 490*/ 491 492 493/*! 494 \def B_PRIoSIZE 495 \brief size_t 496*/ 497 498 499/*! 500 \def B_PRIxSIZE 501 \brief size_t 502*/ 503 504 505/*! 506 \def B_PRIXSIZE 507 \brief size_t 508*/ 509 510 511/*! 512 \def B_PRIdSSIZE 513 \brief ssize_t 514*/ 515 516 517/*! 518 \def B_PRIiSSIZE 519 \brief ssize_t 520*/ 521 522 523/*! 524 \def B_PRIuADDR 525 \brief addr_t 526*/ 527 528 529/*! 530 \def B_PRIoADDR 531 \brief addr_t 532*/ 533 534 535/*! 536 \def B_PRIxADDR 537 \brief addr_t 538*/ 539 540 541/*! 542 \def B_PRIXADDR 543 \brief addr_t 544*/ 545 546 547/*! 548 \def B_PRIdOFF 549 \brief off_t 550*/ 551 552 553/*! 554 \def B_PRIiOFF 555 \brief off_t 556*/ 557 558 559/*! 560 \def B_PRIdDEV 561 \brief dev_t 562*/ 563 564 565/*! 566 \def B_PRIiDEV 567 \brief dev_t 568*/ 569 570 571/*! 572 \def B_PRIdINO 573 \brief ino_t 574*/ 575 576 577/*! 578 \def B_PRIiINO 579 \brief ino_t 580*/ 581 582 583/*! 584 \def B_PRIdTIME 585 \brief time_t 586*/ 587 588 589/*! 590 \def B_PRIiTIME 591 \brief time_t 592*/ 593 594 595//! @} 596 597 598//////////////// Odds and ends 599 600 601/*! 602 \var const char* B_EMPTY_STRING 603 \brief Defines an empty string. Currently defined as the string "". 604 605 \since BeOS R3 606*/ 607 608 609/*! 610 \def min_c(a,b) 611 \brief Returns the minimum of the values a and b. 612 613 \note When including this header in a C file, use the C equivalent called 614 \c min(a,b). 615 616 \since Haiku R1 617*/ 618 619 620/*! 621 \def max_c(a,b) 622 \brief Returns the maximum of values a and b. 623 624 \note When including this header in a C file, use the C equivalent called 625 \c max(a,b). 626 627 \since Haiku R1 628*/ 629 630 631/*! 632 \def NULL 633 \brief Defines the constant \c NULL if it hasn't already been defined. 634 635 \since BeOS R3 636*/ 637 638 639/*! 640 \addtogroup support_globals 641*/ 642 643 644//! @{ 645 646 647/*! 648 \fn void atomic_set(int32* value, int32 newValue) 649 \brief Atomically set the variable \a value to \a newvalue. 650 651 This is a thread-safe way of performing the \c *value \c = \c newValue 652 operation. You should use these function when two or more threads might 653 access the variable simultaneously. You don't have to use a semaphore or a 654 mutex in this case. The variable must be naturally aligned. 655 656 \sa atomic_set64() for a version that works on \c long \c long. 657 \sa atomic_test_and_set() 658 \sa atomic_add() 659 \sa atomic_and() 660 \sa atomic_or(), 661 \sa atomic_get() 662 663 \since Haiku R1 664*/ 665 666 667/*! \fn int32 atomic_get_and_set(int32* value, int32 newValue) 668 \brief Atomically set the variable \a value to \a newvalue and return the 669 old value. 670 671 This is a thread-safe way of performing the \c *value \c = \c newValue 672 operation. You should use these function when two or more threads might 673 access the variable simultaneously. You don't have to use a semaphore or a 674 mutex in this case. 675 676 \return The original value of \c value. 677 678 \sa atomic_get_and_set64() for a version that works on \c long \c long. 679 \sa atomic_set() 680 \sa atomic_test_and_set() 681 \sa atomic_add() 682 \sa atomic_and() 683 \sa atomic_or(), 684 \sa atomic_get() 685 686 \since Haiku R1 687*/ 688 689 690/*! \fn int32 atomic_test_and_set(int32* value, int32 newValue, 691 int32 testAgainst) 692 \brief Atomically set the variable \a value to \a newValue if the current 693 value is \a testAgainst. 694 695 This is a thread-safe way of conditionally performing the \c *value \c += 696 \c newValue operation. You should use these function when two or more 697 threads might access the variable simultaneously. You don't have to use 698 a semaphore or a mutex in this case. 699 700 \return The original value of \c value. 701 702 \sa atomic_test_and_set64() for a version that works on \c long \c long. 703 \sa atomic_get_and_set() 704 \sa atomic_set() 705 \sa atomic_add() 706 \sa atomic_and() 707 \sa atomic_or() 708 \sa atomic_get() 709 710 \since Haiku R1 711*/ 712 713 714/*! 715 \fn int32 atomic_add(int32* value, int32 addValue) 716 \brief Atomically add the value of \a addValue to \a value. 717 718 This is a thread-safe way of performing the \c *value \c += \c addValue 719 operation. You should use these function when two or more threads might 720 access the variable simultaneously. You don't have to use a semaphore or a 721 mutex in this case. 722 723 \return The original value of \c value. 724 725 \sa atomic_add64() for a version that works on \c long \c long. 726 \sa atomic_get_and_set() 727 \sa atomic_set() 728 \sa atomic_test_and_set() 729 \sa atomic_and() 730 \sa atomic_or() 731 \sa atomic_get() 732 733 \since BeOS R3 734*/ 735 736 737/*! \fn int32 atomic_and(int32* value, int32 andValue) 738 \brief Atomically perform a bitwise AND operation of \a andValue to the 739 variable \a andValue. 740 741 This is a thread-safe way of performing the \c *value \c &= \c andValue 742 operation. You should use these function when two or more threads might 743 access the variable simultaneously. You don't have to use a semaphore or a 744 mutex in this case. 745 746 \return The original value of \c value. 747 748 \sa atomic_and64() for a version that works on \c long \c long. 749 \sa atomic_get_and_set() 750 \sa atomic_set() 751 \sa atomic_test_and_set() 752 \sa atomic_add() 753 \sa atomic_or() 754 \sa atomic_get() 755 756 \since BeOS R3 757*/ 758 759 760/*! 761 \fn int32 atomic_or(int32* value, int32 orValue) 762 \brief Atomically perform a bitwise OR operation of \a orValue to the 763 variable \a andValue. 764 765 This is a thread-safe way of performing the \c *value \c |= \c orValue 766 operation. You should use these function when two or more threads might 767 access the variable simultaneously. You don't have to use a semaphore or a 768 mutex in this case. 769 770 \return The original value of \c value. 771 772 \sa atomic_or64() for a version that works on \c long \c long. 773 \sa atomic_get_and_set() 774 \sa atomic_set() 775 \sa atomic_test_and_set() 776 \sa atomic_add() 777 \sa atomic_and() 778 \sa atomic_get() 779 780 \since BeOS R3 781*/ 782 783 784/*! 785 \fn int32 atomic_get(int32* value) 786 \brief Atomically return the value of \c value. 787 788 This is a thread-safe way of reading the contents of the \c value 789 operation. You should use these function when two or more threads might 790 access the variable simultaneously. You don't have to use a semaphore or a 791 mutex in this case. The variable must be naturally aligned. 792 793 \return The original value of \c value. 794 795 \sa atomic_get64() for a version that works on \c long \c long. 796 \sa atomic_get_and_set() 797 \sa atomic_set() 798 \sa atomic_test_and_set() 799 \sa atomic_add() 800 \sa atomic_and() 801 \sa atomic_or() 802 803 \since Haiku R1 804*/ 805 806 807/*! 808 \fn void atomic_set64(int64* value, int64 newValue) 809 \brief Atomically set the variable \a value to \a newvalue. 810 811 This is a thread-safe way of performing the \c *value \c = \c newValue 812 operation. You should use these function when two or more threads might 813 access the variable simultaneously. You don't have to use a semaphore or a 814 mutex in this case. The variable must be naturally aligned. 815 816 \sa atomic_set() for a version that works on an \c int32. 817 \sa atomic_get_and_set64() 818 \sa atomic_test_and_set64() 819 \sa atomic_add64() 820 \sa atomic_and64() 821 \sa atomic_or64() 822 \sa atomic_get64() 823 824 \since Haiku R1 825*/ 826 827 828/*! 829 \fn int64 atomic_get_and_set64(int64* value, int64 newValue) 830 \brief Atomically set the variable \a value to \a newvalue and return 831 the old value. 832 833 This is a thread-safe way of performing the \c *value \c = \c newValue 834 operation. You should use these function when two or more threads might 835 access the variable simultaneously. You don't have to use a semaphore or a 836 mutex in this case. 837 838 \return The original value of \c value. 839 840 \sa atomic_get_and_set() for a version that works on an \c int32. 841 \sa atomic_set64() 842 \sa atomic_test_and_set64() 843 \sa atomic_add64() 844 \sa atomic_and64() 845 \sa atomic_or64() 846 \sa atomic_get64() 847 848 \since Haiku R1 849*/ 850 851 852/*! 853 \fn int64 atomic_test_and_set64(int64* value, int64 newValue, 854 int64 testAgainst) 855 \brief Atomically set the variable \a value to \a newValue if the current 856 value is \a testAgainst. 857 858 This is a thread-safe way of conditionally performing the \c *value 859 \c += \c newValue operation. You should use these function when two 860 or more threads might access the variable simultaneously. You don't 861 have to use a semaphore or a mutex in this case. 862 863 \return The original value of \c value. 864 865 \sa atomic_test_and_set() for a version that works on an \c int32. 866 \sa atomic_get_and_set64() 867 \sa atomic_set64() 868 \sa atomic_add64() 869 \sa atomic_and64() 870 \sa atomic_or64() 871 \sa atomic_get64() 872 873 \since Haiku R1 874*/ 875 876 877/*! 878 \fn int64 atomic_add64(int64* value, int64 addValue) 879 \brief Atomically add the value of \a addValue to \a value. 880 881 This is a thread-safe way of performing the \c *value \c += \c addValue 882 operation. You should use these function when two or more threads might 883 access the variable simultaneously. You don't have to use a semaphore or a 884 mutex in this case. 885 886 \return The original value of \c value. 887 888 \sa atomic_add() for a version that works on an \c int32. 889 \sa atomic_get_and_set64() 890 \sa atomic_set64() 891 \sa atomic_test_and_set64() 892 \sa atomic_and64() 893 \sa atomic_or64() 894 \sa atomic_get64() 895 896 \since Haiku R1 897*/ 898 899 900/*! 901 \fn int64 atomic_and64(int64* value, int64 andValue) 902 \brief Atomically perform a bitwise AND operation of \a andValue to the 903 variable \a andValue. 904 905 This is a thread-safe way of performing the \c *value \c &= \c andValue 906 operation. You should use these function when two or more threads might 907 access the variable simultaneously. You don't have to use a semaphore or a 908 mutex in this case. 909 910 \return The original value of \c value. 911 912 \sa atomic_and() for a version that works on an \c int32. 913 \sa atomic_get_and_set64() 914 \sa atomic_set64() 915 \sa atomic_test_and_set64() 916 \sa atomic_add64() 917 \sa atomic_or64() 918 \sa atomic_get64() 919 920 \since Haiku R1 921*/ 922 923 924/*! 925 \fn int64 atomic_or64(int64* value, int64 orValue) 926 \brief Atomically perform a bitwise OR operation of \a orValue to the 927 variable \a andValue. 928 929 This is a thread-safe way of performing the \c *value \c |= \c orValue 930 operation. You should use these function when two or more threads might 931 access the variable simultaneously. You don't have to use a semaphore or a 932 mutex in this case. 933 934 \return The original value of \c value. 935 936 \sa atomic_or() for a version that works on an \c int32. 937 \sa atomic_get_and_set64() 938 \sa atomic_set64() 939 \sa atomic_test_and_set64() 940 \sa atomic_add64() 941 \sa atomic_and64() 942 \sa atomic_get64() 943 944 \since Haiku R1 945*/ 946 947 948/*! 949 \fn int64 atomic_get64(int64* value) 950 \brief Atomically return the value of \c value. 951 952 This is a thread-safe way of reading the contents of the \c value 953 operation. You should use these function when two or more threads might 954 access the variable simultaneously. You don't have to use a semaphore or a 955 mutex in this case. The variable must be naturally aligned. 956 957 \return The original value of \c value. 958 959 \sa atomic_get() for a version that works on an \c int32. 960 \sa atomic_get_and_set64() 961 \sa atomic_set64() 962 \sa atomic_test_and_set64() 963 \sa atomic_add64() 964 \sa atomic_and64() 965 \sa atomic_or64() 966 967 \since Haiku R1 968*/ 969 970 971//! @} 972 973 974/*! 975 \fn void* get_stack_frame(void) 976 \brief Internal function. 977 \internal 978*/ 979 980 981/*! 982 \name Deprecated defines 983*/ 984 985 986//! @{ 987 988 989/*! 990 \def FALSE 991 \brief Obsolete. Use \c false. 992 993 \since BeOS R3 994*/ 995 996 997/*! 998 \def TRUE 999 \brief Obsolete. Use \c true. 1000 1001 \since BeOS R3 1002*/ 1003 1004 1005//! @} 1006