prtypes.h (19246B)
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 /* 7 ** File: prtypes.h 8 ** Description: Definitions of NSPR's basic types 9 ** 10 ** Prototypes and macros used to make up for deficiencies that we have found 11 ** in ANSI environments. 12 ** 13 ** Since we do not wrap <stdlib.h> and all the other standard headers, authors 14 ** of portable code will not know in general that they need these definitions. 15 ** Instead of requiring these authors to find the dependent uses in their code 16 ** and take the following steps only in those C files, we take steps once here 17 ** for all C files. 18 **/ 19 20 #ifndef prtypes_h___ 21 #define prtypes_h___ 22 23 #ifdef MDCPUCFG 24 #include MDCPUCFG 25 #else 26 #include "prcpucfg.h" 27 #endif 28 29 #include <stddef.h> 30 31 /*********************************************************************** 32 ** MACROS: PR_EXTERN 33 ** PR_IMPLEMENT 34 ** DESCRIPTION: 35 ** These are only for externally visible routines and globals. For 36 ** internal routines, just use "extern" for type checking and that 37 ** will not export internal cross-file or forward-declared symbols. 38 ** Define a macro for declaring procedures return types. We use this to 39 ** deal with windoze specific type hackery for DLL definitions. Use 40 ** PR_EXTERN when the prototype for the method is declared. Use 41 ** PR_IMPLEMENT for the implementation of the method. 42 ** 43 ** Example: 44 ** in dowhim.h 45 ** PR_EXTERN( void ) DoWhatIMean( void ); 46 ** in dowhim.c 47 ** PR_IMPLEMENT( void ) DoWhatIMean( void ) { return; } 48 ** 49 ** 50 ***********************************************************************/ 51 #if defined(WIN32) 52 53 #define PR_EXPORT(__type) extern __declspec(dllexport) __type 54 #define PR_EXPORT_DATA(__type) extern __declspec(dllexport) __type 55 #define PR_IMPORT(__type) __declspec(dllimport) __type 56 #define PR_IMPORT_DATA(__type) __declspec(dllimport) __type 57 58 #define PR_EXTERN(__type) extern __declspec(dllexport) __type 59 #define PR_IMPLEMENT(__type) __declspec(dllexport) __type 60 #define PR_EXTERN_DATA(__type) extern __declspec(dllexport) __type 61 #define PR_IMPLEMENT_DATA(__type) __declspec(dllexport) __type 62 63 #define PR_CALLBACK 64 #define PR_CALLBACK_DECL 65 #define PR_STATIC_CALLBACK(__x) static __x 66 67 #elif defined(__declspec) 68 69 #define PR_EXPORT(__type) extern __declspec(dllexport) __type 70 #define PR_EXPORT_DATA(__type) extern __declspec(dllexport) __type 71 #define PR_IMPORT(__type) extern __declspec(dllimport) __type 72 #define PR_IMPORT_DATA(__type) extern __declspec(dllimport) __type 73 74 #define PR_EXTERN(__type) extern __declspec(dllexport) __type 75 #define PR_IMPLEMENT(__type) __declspec(dllexport) __type 76 #define PR_EXTERN_DATA(__type) extern __declspec(dllexport) __type 77 #define PR_IMPLEMENT_DATA(__type) __declspec(dllexport) __type 78 79 #define PR_CALLBACK 80 #define PR_CALLBACK_DECL 81 #define PR_STATIC_CALLBACK(__x) static __x 82 83 #else /* Unix */ 84 85 /* GCC 3.3 and later support the visibility attribute. */ 86 #if (__GNUC__ >= 4) || \ 87 (__GNUC__ == 3 && __GNUC_MINOR__ >= 3) 88 #define PR_VISIBILITY_DEFAULT __attribute__((visibility("default"))) 89 #else 90 #define PR_VISIBILITY_DEFAULT 91 #endif 92 93 #define PR_EXPORT(__type) extern PR_VISIBILITY_DEFAULT __type 94 #define PR_EXPORT_DATA(__type) extern PR_VISIBILITY_DEFAULT __type 95 #define PR_IMPORT(__type) extern PR_VISIBILITY_DEFAULT __type 96 #define PR_IMPORT_DATA(__type) extern PR_VISIBILITY_DEFAULT __type 97 98 #define PR_EXTERN(__type) extern PR_VISIBILITY_DEFAULT __type 99 #define PR_IMPLEMENT(__type) PR_VISIBILITY_DEFAULT __type 100 #define PR_EXTERN_DATA(__type) extern PR_VISIBILITY_DEFAULT __type 101 #define PR_IMPLEMENT_DATA(__type) PR_VISIBILITY_DEFAULT __type 102 #define PR_CALLBACK 103 #define PR_CALLBACK_DECL 104 #define PR_STATIC_CALLBACK(__x) static __x 105 106 #endif 107 108 #if defined(_NSPR_BUILD_) 109 #define NSPR_API(__type) PR_EXPORT(__type) 110 #define NSPR_DATA_API(__type) PR_EXPORT_DATA(__type) 111 #else 112 #define NSPR_API(__type) PR_IMPORT(__type) 113 #define NSPR_DATA_API(__type) PR_IMPORT_DATA(__type) 114 #endif 115 116 /*********************************************************************** 117 ** MACROS: PR_BEGIN_MACRO 118 ** PR_END_MACRO 119 ** DESCRIPTION: 120 ** Macro body brackets so that macros with compound statement definitions 121 ** behave syntactically more like functions when called. 122 ***********************************************************************/ 123 #define PR_BEGIN_MACRO do { 124 #define PR_END_MACRO } while (0) 125 126 /*********************************************************************** 127 ** MACROS: PR_BEGIN_EXTERN_C 128 ** PR_END_EXTERN_C 129 ** DESCRIPTION: 130 ** Macro shorthands for conditional C++ extern block delimiters. 131 ***********************************************************************/ 132 #ifdef __cplusplus 133 #define PR_BEGIN_EXTERN_C extern "C" { 134 #define PR_END_EXTERN_C } 135 #else 136 #define PR_BEGIN_EXTERN_C 137 #define PR_END_EXTERN_C 138 #endif 139 140 /*********************************************************************** 141 ** MACROS: PR_BIT 142 ** PR_BITMASK 143 ** DESCRIPTION: 144 ** Bit masking macros. XXX n must be <= 31 to be portable 145 ***********************************************************************/ 146 #define PR_BIT(n) ((PRUint32)1 << (n)) 147 #define PR_BITMASK(n) (PR_BIT(n) - 1) 148 149 /*********************************************************************** 150 ** MACROS: PR_ROUNDUP 151 ** PR_MIN 152 ** PR_MAX 153 ** PR_ABS 154 ** DESCRIPTION: 155 ** Commonly used macros for operations on compatible types. 156 ***********************************************************************/ 157 #define PR_ROUNDUP(x,y) ((((x)+((y)-1))/(y))*(y)) 158 #define PR_MIN(x,y) ((x)<(y)?(x):(y)) 159 #define PR_MAX(x,y) ((x)>(y)?(x):(y)) 160 #define PR_ABS(x) ((x)<0?-(x):(x)) 161 162 /*********************************************************************** 163 ** MACROS: PR_ARRAY_SIZE 164 ** DESCRIPTION: 165 ** The number of elements in an array. 166 ***********************************************************************/ 167 #define PR_ARRAY_SIZE(a) (sizeof(a)/sizeof((a)[0])) 168 169 PR_BEGIN_EXTERN_C 170 171 /* 172 ** Starting in NSPR 4.9.5, NSPR's exact-width integer types should match 173 ** the exact-width integer types defined in <stdint.h>. This allows sloppy 174 ** code to use PRInt{N} and int{N}_t interchangeably. 175 ** 176 ** The 8-bit and 16-bit integer types can only be defined using char and 177 ** short. All platforms define the 32-bit integer types using int. So only 178 ** the 64-bit integer types could be defined differently. 179 ** 180 ** NSPR's original strategy was to use the "shortest" 64-bit integer type: 181 ** if long is 64-bit, then prefer it over long long. This strategy is also 182 ** used by Linux/glibc, FreeBSD, and NetBSD. 183 ** 184 ** Other platforms use a different strategy: simply define the 64-bit 185 ** integer types using long long. We define the PR_ALTERNATE_INT64_TYPEDEF 186 ** macro on these platforms. Note that PR_ALTERNATE_INT64_TYPEDEF is for 187 ** internal use by NSPR headers only. Do not define or test this macro in 188 ** your code. 189 ** 190 ** NOTE: NSPR can't use <stdint.h> because C99 requires C++ code to define 191 ** __STDC_LIMIT_MACROS and __STDC_CONSTANT_MACROS to make all the macros 192 ** defined in <stdint.h> available. This strange requirement is gone in 193 ** C11. When most platforms ignore this C99 requirement, NSPR will be able 194 ** to use <stdint.h>. A patch to do that is in NSPR bug 634793. 195 */ 196 197 #if defined(__APPLE__) || defined(__OpenBSD__) 198 #define PR_ALTERNATE_INT64_TYPEDEF 199 #endif 200 201 /************************************************************************ 202 ** TYPES: PRUint8 203 ** PRInt8 204 ** DESCRIPTION: 205 ** The int8 types are known to be 8 bits each. There is no type that 206 ** is equivalent to a plain "char". 207 ************************************************************************/ 208 #if PR_BYTES_PER_BYTE == 1 209 typedef unsigned char PRUint8; 210 /* 211 ** Mozilla C++ code expects the PRInt{N} and int{N}_t types to match (see bug 212 ** 634793). If a platform defines int8_t as 'char', but NSPR defines it as 213 ** 'signed char', it results in a type mismatch. 214 ** On such platforms we define PRInt8 as 'char' to avoid the mismatch. 215 */ 216 #if defined(__sun) && defined(__cplusplus) 217 typedef char PRInt8; 218 #else 219 typedef signed char PRInt8; 220 #endif 221 #else 222 #error No suitable type for PRInt8/PRUint8 223 #endif 224 225 /************************************************************************ 226 * MACROS: PR_INT8_MAX 227 * PR_INT8_MIN 228 * PR_UINT8_MAX 229 * DESCRIPTION: 230 * The maximum and minimum values of a PRInt8 or PRUint8. 231 ************************************************************************/ 232 233 #define PR_INT8_MAX 127 234 #define PR_INT8_MIN (-128) 235 #define PR_UINT8_MAX 255U 236 237 /************************************************************************ 238 ** TYPES: PRUint16 239 ** PRInt16 240 ** DESCRIPTION: 241 ** The int16 types are known to be 16 bits each. 242 ************************************************************************/ 243 #if PR_BYTES_PER_SHORT == 2 244 typedef unsigned short PRUint16; 245 typedef short PRInt16; 246 #else 247 #error No suitable type for PRInt16/PRUint16 248 #endif 249 250 /************************************************************************ 251 * MACROS: PR_INT16_MAX 252 * PR_INT16_MIN 253 * PR_UINT16_MAX 254 * DESCRIPTION: 255 * The maximum and minimum values of a PRInt16 or PRUint16. 256 ************************************************************************/ 257 258 #define PR_INT16_MAX 32767 259 #define PR_INT16_MIN (-32768) 260 #define PR_UINT16_MAX 65535U 261 262 /************************************************************************ 263 ** TYPES: PRUint32 264 ** PRInt32 265 ** DESCRIPTION: 266 ** The int32 types are known to be 32 bits each. 267 ************************************************************************/ 268 #if PR_BYTES_PER_INT == 4 269 typedef unsigned int PRUint32; 270 typedef int PRInt32; 271 #define PR_INT32(x) x 272 #define PR_UINT32(x) x ## U 273 #elif PR_BYTES_PER_LONG == 4 274 typedef unsigned long PRUint32; 275 typedef long PRInt32; 276 #define PR_INT32(x) x ## L 277 #define PR_UINT32(x) x ## UL 278 #else 279 #error No suitable type for PRInt32/PRUint32 280 #endif 281 282 /************************************************************************ 283 * MACROS: PR_INT32_MAX 284 * PR_INT32_MIN 285 * PR_UINT32_MAX 286 * DESCRIPTION: 287 * The maximum and minimum values of a PRInt32 or PRUint32. 288 ************************************************************************/ 289 290 #define PR_INT32_MAX PR_INT32(2147483647) 291 #define PR_INT32_MIN (-PR_INT32_MAX - 1) 292 #define PR_UINT32_MAX PR_UINT32(4294967295) 293 294 /************************************************************************ 295 ** TYPES: PRUint64 296 ** PRInt64 297 ** DESCRIPTION: 298 ** The int64 types are known to be 64 bits each. Care must be used when 299 ** declaring variables of type PRUint64 or PRInt64. Different hardware 300 ** architectures and even different compilers have varying support for 301 ** 64 bit values. The only guaranteed portability requires the use of 302 ** the LL_ macros (see prlong.h). 303 ** 304 ** MACROS: PR_INT64 305 ** PR_UINT64 306 ** DESCRIPTION: 307 ** The PR_INT64 and PR_UINT64 macros provide a portable way for 308 ** specifying 64-bit integer constants. They can only be used if 309 ** PRInt64 and PRUint64 are defined as compiler-supported 64-bit 310 ** integer types (i.e., if HAVE_LONG_LONG is defined, which is true 311 ** for all the supported compilers topday). If PRInt64 and PRUint64 312 ** are defined as structs, the LL_INIT macro defined in prlong.h has 313 ** to be used. 314 ** 315 ** MACROS: PR_INT64_MAX 316 ** PR_INT64_MIN 317 ** PR_UINT64_MAX 318 ** DESCRIPTION: 319 ** The maximum and minimum values of a PRInt64 or PRUint64. 320 ************************************************************************/ 321 #ifdef HAVE_LONG_LONG 322 /* Keep this in sync with prlong.h. */ 323 #if PR_BYTES_PER_LONG == 8 && !defined(PR_ALTERNATE_INT64_TYPEDEF) 324 typedef long PRInt64; 325 typedef unsigned long PRUint64; 326 #define PR_INT64(x) x ## L 327 #define PR_UINT64(x) x ## UL 328 #elif defined(WIN32) && !defined(__GNUC__) 329 typedef __int64 PRInt64; 330 typedef unsigned __int64 PRUint64; 331 #define PR_INT64(x) x ## i64 332 #define PR_UINT64(x) x ## ui64 333 #else 334 typedef long long PRInt64; 335 typedef unsigned long long PRUint64; 336 #define PR_INT64(x) x ## LL 337 #define PR_UINT64(x) x ## ULL 338 #endif /* PR_BYTES_PER_LONG == 8 */ 339 340 #define PR_INT64_MAX PR_INT64(0x7fffffffffffffff) 341 #define PR_INT64_MIN (-PR_INT64_MAX - 1) 342 #define PR_UINT64_MAX PR_UINT64(-1) 343 #else /* !HAVE_LONG_LONG */ 344 typedef struct { 345 #ifdef IS_LITTLE_ENDIAN 346 PRUint32 lo, hi; 347 #else 348 PRUint32 hi, lo; 349 #endif 350 } PRInt64; 351 typedef PRInt64 PRUint64; 352 353 #define PR_INT64_MAX (PRInt64){0x7fffffff, 0xffffffff} 354 #define PR_INT64_MIN (PRInt64){0xffffffff, 0xffffffff} 355 #define PR_UINT64_MAX (PRUint64){0xffffffff, 0xffffffff} 356 357 #endif /* !HAVE_LONG_LONG */ 358 359 /************************************************************************ 360 ** TYPES: PRUintn 361 ** PRIntn 362 ** DESCRIPTION: 363 ** The PRIntn types are most appropriate for automatic variables. They are 364 ** guaranteed to be at least 16 bits, though various architectures may 365 ** define them to be wider (e.g., 32 or even 64 bits). These types are 366 ** never valid for fields of a structure. 367 ************************************************************************/ 368 #if PR_BYTES_PER_INT >= 2 369 typedef int PRIntn; 370 typedef unsigned int PRUintn; 371 #else 372 #error 'sizeof(int)' not sufficient for platform use 373 #endif 374 375 /************************************************************************ 376 ** TYPES: PRFloat64 377 ** DESCRIPTION: 378 ** NSPR's floating point type is always 64 bits. 379 ************************************************************************/ 380 typedef double PRFloat64; 381 382 /************************************************************************ 383 ** TYPES: PRSize 384 ** DESCRIPTION: 385 ** A type for representing the size of objects. 386 ************************************************************************/ 387 typedef size_t PRSize; 388 389 390 /************************************************************************ 391 ** TYPES: PROffset32, PROffset64 392 ** DESCRIPTION: 393 ** A type for representing byte offsets from some location. 394 ************************************************************************/ 395 typedef PRInt32 PROffset32; 396 typedef PRInt64 PROffset64; 397 398 /************************************************************************ 399 ** TYPES: PRPtrDiff 400 ** DESCRIPTION: 401 ** A type for pointer difference. Variables of this type are suitable 402 ** for storing a pointer or pointer subtraction. 403 ************************************************************************/ 404 typedef ptrdiff_t PRPtrdiff; 405 406 /************************************************************************ 407 ** TYPES: PRUptrdiff 408 ** DESCRIPTION: 409 ** A type for pointer difference. Variables of this type are suitable 410 ** for storing a pointer or pointer sutraction. 411 ************************************************************************/ 412 #ifdef _WIN64 413 typedef PRUint64 PRUptrdiff; 414 #else 415 typedef unsigned long PRUptrdiff; 416 #endif 417 418 /************************************************************************ 419 ** TYPES: PRBool 420 ** DESCRIPTION: 421 ** Use PRBool for variables and parameter types. Use PR_FALSE and PR_TRUE 422 ** for clarity of target type in assignments and actual arguments. Use 423 ** 'if (bool)', 'while (!bool)', '(bool) ? x : y' etc., to test booleans 424 ** just as you would C int-valued conditions. 425 ************************************************************************/ 426 typedef PRIntn PRBool; 427 #define PR_TRUE 1 428 #define PR_FALSE 0 429 430 /************************************************************************ 431 ** TYPES: PRPackedBool 432 ** DESCRIPTION: 433 ** Use PRPackedBool within structs where bitfields are not desirable 434 ** but minimum and consistant overhead matters. 435 ************************************************************************/ 436 typedef PRUint8 PRPackedBool; 437 438 /* 439 ** Status code used by some routines that have a single point of failure or 440 ** special status return. 441 */ 442 typedef enum { PR_FAILURE = -1, PR_SUCCESS = 0 } PRStatus; 443 444 #ifndef __PRUNICHAR__ 445 #define __PRUNICHAR__ 446 #ifdef WIN32 447 typedef wchar_t PRUnichar; 448 #else 449 typedef PRUint16 PRUnichar; 450 #endif 451 #endif 452 453 /* 454 ** WARNING: The undocumented data types PRWord and PRUword are 455 ** only used in the garbage collection and arena code. Do not 456 ** use PRWord and PRUword in new code. 457 ** 458 ** A PRWord is an integer that is the same size as a void*. 459 ** It implements the notion of a "word" in the Java Virtual 460 ** Machine. (See Sec. 3.4 "Words", The Java Virtual Machine 461 ** Specification, Addison-Wesley, September 1996. 462 ** http://java.sun.com/docs/books/vmspec/index.html.) 463 */ 464 #ifdef _WIN64 465 typedef PRInt64 PRWord; 466 typedef PRUint64 PRUword; 467 #else 468 typedef long PRWord; 469 typedef unsigned long PRUword; 470 #endif 471 472 /* 473 * PR_PRETEND_NORETURN, specified at the end of a function declaration, 474 * indicates that for the purposes of static analysis, this function does not 475 * return. (The function definition does not need to be annotated.) 476 * 477 * void PR_Assert(const char *s, const char *file, PRIntn ln) 478 * PR_PRETEND_NORETURN; 479 * 480 * Some static analyzers, like scan-build from clang, can use this information 481 * to eliminate false positives. From the upstream documentation of 482 * scan-build: 483 * This attribute is useful for annotating assertion handlers that actually 484 * can return, but for the purpose of using the analyzer we want to pretend 485 * that such functions do not return. 486 */ 487 #ifdef __clang_analyzer__ 488 #if __has_extension(attribute_analyzer_noreturn) 489 #define PR_PRETEND_NORETURN __attribute__((analyzer_noreturn)) 490 #endif 491 #endif 492 493 #ifndef PR_PRETEND_NORETURN 494 #define PR_PRETEND_NORETURN /* no support */ 495 #endif 496 497 #if defined(NO_NSPR_10_SUPPORT) 498 #else 499 /********* ???????????????? FIX ME ??????????????????????????? *****/ 500 /********************** Some old definitions until pr=>ds transition is done ***/ 501 /********************** Also, we are still using NSPR 1.0. GC ******************/ 502 /* 503 ** Fundamental NSPR macros, used nearly everywhere. 504 */ 505 506 #define PR_PUBLIC_API PR_IMPLEMENT 507 508 /* 509 ** Macro body brackets so that macros with compound statement definitions 510 ** behave syntactically more like functions when called. 511 */ 512 #define NSPR_BEGIN_MACRO do { 513 #define NSPR_END_MACRO } while (0) 514 515 /* 516 ** Macro shorthands for conditional C++ extern block delimiters. 517 */ 518 #ifdef NSPR_BEGIN_EXTERN_C 519 #undef NSPR_BEGIN_EXTERN_C 520 #endif 521 #ifdef NSPR_END_EXTERN_C 522 #undef NSPR_END_EXTERN_C 523 #endif 524 525 #ifdef __cplusplus 526 #define NSPR_BEGIN_EXTERN_C extern "C" { 527 #define NSPR_END_EXTERN_C } 528 #else 529 #define NSPR_BEGIN_EXTERN_C 530 #define NSPR_END_EXTERN_C 531 #endif 532 533 #include "obsolete/protypes.h" 534 535 /********* ????????????? End Fix me ?????????????????????????????? *****/ 536 #endif /* NO_NSPR_10_SUPPORT */ 537 538 /* 539 ** Compile-time assert. "condition" must be a constant expression. 540 ** The macro can be used only in places where an "extern" declaration is 541 ** allowed. 542 */ 543 #define PR_STATIC_ASSERT(condition) \ 544 extern void pr_static_assert(int arg[(condition) ? 1 : -1]) 545 546 PR_END_EXTERN_C 547 548 #endif /* prtypes_h___ */