nspr_types.rst (4515B)
1 This chapter describes the most common NSPR types. Other chapters 2 describe more specialized types when describing the functions that use 3 them. 4 5 - `Calling Convention Types <#Calling_Convention_Types>`__ are used for 6 externally visible functions and globals. 7 - `Algebraic Types <#Algebraic_Types>`__ of various lengths are used 8 for integer algebra. 9 - `Miscellaneous Types <#Miscellaneous_Types>`__ are used for 10 representing size, pointer difference, Boolean values, and return 11 values. 12 13 For information on naming conventions for NSPR types, functions, and 14 macros, see `NSPR Naming 15 Conventions <Introduction_to_NSPR#NSPR_Naming_Conventions>`__. 16 17 .. _Calling_Convention_Types: 18 19 Calling Convention Types 20 ------------------------ 21 22 These types are used to support cross-platform declarations of 23 prototypes and implementations: 24 25 - :ref:`PR_EXTERN` is used for declarations of external functions or 26 variables. 27 - :ref:`PR_IMPLEMENT` is used for definitions of external functions or 28 variables. 29 - :ref:`PR_CALLBACK` is used for definitions and declarations of functions 30 that are called via function pointers. A typical example is a 31 function implemented in an application but called from a shared 32 library. 33 34 Here are some simple examples of the use of these types: 35 36 .. container:: highlight 37 38 In dowhim.h: 39 40 .. code:: 41 42 PR_EXTERN( void ) DoWhatIMean( void ); 43 44 static void PR_CALLBACK RootFunction(void *arg); 45 46 .. container:: highlight 47 48 In dowhim.c: 49 50 .. code:: 51 52 PR_IMPLEMENT( void ) DoWhatIMean( void ) { return; }; 53 54 PRThread *thread = PR_CreateThread(..., RootFunction, ...); 55 56 .. _Algebraic_Types: 57 58 Algebraic Types 59 --------------- 60 61 NSPR provides the following type definitions with unambiguous bit widths 62 for algebraic operations: 63 64 - `8-, 16-, and 32-bit Integer 65 Types <#8-,_16-,_and_32-bit_Integer_Types>`__ 66 - `64-bit Integer Types <#64-bit_Integer_Types>`__ 67 - `Floating-Point Number Type <#Floating-Point_Number_Type>`__ 68 69 For convenience, NSPR also provides type definitions with 70 platform-dependent bit widths: 71 72 - `Native OS Integer Types <#Native_OS_Integer_Types>`__ 73 74 .. _8-.2C_16-.2C_and_32-bit_Integer_Types: 75 76 8-, 16-, and 32-bit Integer Types 77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 78 79 .. _Signed_Integers: 80 81 Signed Integers 82 ^^^^^^^^^^^^^^^ 83 84 - :ref:`PRInt8` 85 - :ref:`PRInt16` 86 - :ref:`PRInt32` 87 88 .. _Unsigned_Integers: 89 90 Unsigned Integers 91 ^^^^^^^^^^^^^^^^^ 92 93 - :ref:`PRUint8` 94 - :ref:`PRUint16` 95 - :ref:`PRUint32` 96 97 .. _64-bit_Integer_Types: 98 99 64-bit Integer Types 100 ~~~~~~~~~~~~~~~~~~~~ 101 102 Different platforms treat 64-bit numeric fields in different ways. Some 103 systems require emulation of 64-bit fields by using two 32-bit numeric 104 fields bound in a structure. Since the types (``long long`` versus 105 ``struct LONGLONG``) are not type compatible, NSPR defines macros to 106 manipulate 64-bit numeric fields. These macros are defined in 107 ``prlong.h``. Conscientious use of these macros ensures portability of 108 code to all the platforms supported by NSPR and still provides optimal 109 behavior on those systems that treat long long values directly. 110 111 - :ref:`PRInt64` 112 - :ref:`PRUint64` 113 114 .. _Floating-Point_Number_Type: 115 116 Floating-Point Number Type 117 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 118 119 The NSPR floating-point type is always 64 bits. 120 121 - :ref:`PRFloat64` 122 123 .. _Native_OS_Integer_Types: 124 125 Native OS Integer Types 126 ~~~~~~~~~~~~~~~~~~~~~~~ 127 128 These types are most appropriate for automatic variables. They are 129 guaranteed to be at least 16 bits, though various architectures may 130 define them to be wider (for example, 32 or even 64 bits). These types 131 are never valid for fields of a structure. 132 133 - :ref:`PRIntn` 134 - :ref:`PRUintn` 135 136 .. _Miscellaneous_Types: 137 138 Miscellaneous Types 139 ------------------- 140 141 - `Size Type <#Size_Type>`__ 142 - `Pointer Difference Types <#Pointer_Difference_Types>`__ 143 - `Boolean Types <#Boolean_Types>`__ 144 - `Status Type for Return Values <#Status_Type_for_Return_Values>`__ 145 146 .. _Size_Type: 147 148 Size Type 149 ~~~~~~~~~ 150 151 - :ref:`PRSize` 152 153 .. _Pointer_Difference_Types: 154 155 Pointer Difference Types 156 ~~~~~~~~~~~~~~~~~~~~~~~~ 157 158 Types for pointer difference. Variables of these types are suitable for 159 storing a pointer or pointer subtraction. These are the same as the 160 corresponding types in ``libc``. 161 162 - :ref:`PRPtrdiff` 163 - :ref:`PRUptrdiff` 164 165 .. _Boolean_Types: 166 167 Boolean Types 168 ~~~~~~~~~~~~~ 169 170 Type and constants for Boolean values. 171 172 - :ref:`PRBool` 173 - :ref:`PRPackedBool` 174 175 .. _Status_Type_for_Return_Values: 176 177 Status Type for Return Values 178 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 179 180 - :ref:`PRStatus`