contrib/gcc/doc/libgcc.texi

   1 @c Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc.
   2 @c This is part of the GCC manual.
   3 @c For copying conditions, see the file gcc.texi.
   4 @c Contributed by Aldy Hernandez <aldy@quesejoda.com>
   5
   6 @node Libgcc
   7 @chapter The GCC low-level runtime library
   8
   9 GCC provides a low-level runtime library, @file{libgcc.a} or
  10 @file{libgcc_s.so.1} on some platforms.  GCC generates calls to
  11 routines in this library automatically, whenever it needs to perform
  12 some operation that is too complicated to emit inline code for.
  13
  14 Most of the routines in @code{libgcc} handle arithmetic operations
  15 that the target processor cannot perform directly.  This includes
  16 integer multiply and divide on some machines, and all floating-point
  17 operations on other machines.  @code{libgcc} also includes routines
  18 for exception handling, and a handful of miscellaneous operations.
  19
  20 Some of these routines can be defined in mostly machine-independent C@.
  21 Others must be hand-written in assembly language for each processor
  22 that needs them.
  23
  24 GCC will also generate calls to C library routines, such as
  25 @code{memcpy} and @code{memset}, in some cases.  The set of routines
  26 that GCC may possibly use is documented in @ref{Other
  27 Builtins,,,gcc, Using the GNU Compiler Collection (GCC)}.
  28
  29 These routines take arguments and return values of a specific machine
  30 mode, not a specific C type.  @xref{Machine Modes}, for an explanation
  31 of this concept.  For illustrative purposes, in this chapter the
  32 floating point type @code{float} is assumed to correspond to @code{SFmode};
  33 @code{double} to @code{DFmode}; and @code{@w{long double}} to both
  34 @code{TFmode} and @code{XFmode}.  Similarly, the integer types @code{int}
  35 and @code{@w{unsigned int}} correspond to @code{SImode}; @code{long} and
  36 @code{@w{unsigned long}} to @code{DImode}; and @code{@w{long long}} and
  37 @code{@w{unsigned long long}} to @code{TImode}.
  38
  39 @menu
  40 * Integer library routines::
  41 * Soft float library routines::
  42 * Decimal float library routines::
  43 * Exception handling routines::
  44 * Miscellaneous routines::
  45 @end menu
  46
  47 @node Integer library routines
  48 @section Routines for integer arithmetic
  49
  50 The integer arithmetic routines are used on platforms that don't provide
  51 hardware support for arithmetic operations on some modes.
  52
  53 @subsection Arithmetic functions
  54
  55 @deftypefn {Runtime Function} int __ashlsi3 (int @var{a}, int @var{b})
  56 @deftypefnx {Runtime Function} long __ashldi3 (long @var{a}, int @var{b})
  57 @deftypefnx {Runtime Function} {long long} __ashlti3 (long long @var{a}, int @var{b})
  58 These functions return the result of shifting @var{a} left by @var{b} bits.
  59 @end deftypefn
  60
  61 @deftypefn {Runtime Function} int __ashrsi3 (int @var{a}, int @var{b})
  62 @deftypefnx {Runtime Function} long __ashrdi3 (long @var{a}, int @var{b})
  63 @deftypefnx {Runtime Function} {long long} __ashrti3 (long long @var{a}, int @var{b})
  64 These functions return the result of arithmetically shifting @var{a} right
  65 by @var{b} bits.
  66 @end deftypefn
  67
  68 @deftypefn {Runtime Function} int __divsi3 (int @var{a}, int @var{b})
  69 @deftypefnx {Runtime Function} long __divdi3 (long @var{a}, long @var{b})
  70 @deftypefnx {Runtime Function} {long long} __divti3 (long long @var{a}, long long @var{b})
  71 These functions return the quotient of the signed division of @var{a} and
  72 @var{b}.
  73 @end deftypefn
  74
  75 @deftypefn {Runtime Function} int __lshrsi3 (int @var{a}, int @var{b})
  76 @deftypefnx {Runtime Function} long __lshrdi3 (long @var{a}, int @var{b})
  77 @deftypefnx {Runtime Function} {long long} __lshrti3 (long long @var{a}, int @var{b})
  78 These functions return the result of logically shifting @var{a} right by
  79 @var{b} bits.
  80 @end deftypefn
  81
  82 @deftypefn {Runtime Function} int __modsi3 (int @var{a}, int @var{b})
  83 @deftypefnx {Runtime Function} long __moddi3 (long @var{a}, long @var{b})
  84 @deftypefnx {Runtime Function} {long long} __modti3 (long long @var{a}, long long @var{b})
  85 These functions return the remainder of the signed division of @var{a}
  86 and @var{b}.
  87 @end deftypefn
  88
  89 @deftypefn {Runtime Function} int __mulsi3 (int @var{a}, int @var{b})
  90 @deftypefnx {Runtime Function} long __muldi3 (long @var{a}, long @var{b})
  91 @deftypefnx {Runtime Function} {long long} __multi3 (long long @var{a}, long long @var{b})
  92 These functions return the product of @var{a} and @var{b}.
  93 @end deftypefn
  94
  95 @deftypefn {Runtime Function} long __negdi2 (long @var{a})
  96 @deftypefnx {Runtime Function} {long long} __negti2 (long long @var{a})
  97 These functions return the negation of @var{a}.
  98 @end deftypefn
  99
 100 @deftypefn {Runtime Function} {unsigned int} __udivsi3 (unsigned int @var{a}, unsigned int @var{b})
 101 @deftypefnx {Runtime Function} {unsigned long} __udivdi3 (unsigned long @var{a}, unsigned long @var{b})
 102 @deftypefnx {Runtime Function} {unsigned long long} __udivti3 (unsigned long long @var{a}, unsigned long long @var{b})
 103 These functions return the quotient of the unsigned division of @var{a}
 104 and @var{b}.
 105 @end deftypefn
 106
 107 @deftypefn {Runtime Function} {unsigned long} __udivmoddi3 (unsigned long @var{a}, unsigned long @var{b}, unsigned long *@var{c})
 108 @deftypefnx {Runtime Function} {unsigned long long} __udivti3 (unsigned long long @var{a}, unsigned long long @var{b}, unsigned long long *@var{c})
 109 These functions calculate both the quotient and remainder of the unsigned
 110 division of @var{a} and @var{b}.  The return value is the quotient, and
 111 the remainder is placed in variable pointed to by @var{c}.
 112 @end deftypefn
 113
 114 @deftypefn {Runtime Function} {unsigned int} __umodsi3 (unsigned int @var{a}, unsigned int @var{b})
 115 @deftypefnx {Runtime Function} {unsigned long} __umoddi3 (unsigned long @var{a}, unsigned long @var{b})
 116 @deftypefnx {Runtime Function} {unsigned long long} __umodti3 (unsigned long long @var{a}, unsigned long long @var{b})
 117 These functions return the remainder of the unsigned division of @var{a}
 118 and @var{b}.
 119 @end deftypefn
 120
 121 @subsection Comparison functions
 122
 123 The following functions implement integral comparisons.  These functions
 124 implement a low-level compare, upon which the higher level comparison
 125 operators (such as less than and greater than or equal to) can be
 126 constructed.  The returned values lie in the range zero to two, to allow
 127 the high-level operators to be implemented by testing the returned
 128 result using either signed or unsigned comparison.
 129
 130 @deftypefn {Runtime Function} int __cmpdi2 (long @var{a}, long @var{b})
 131 @deftypefnx {Runtime Function} int __cmpti2 (long long @var{a}, long long @var{b})
 132 These functions perform a signed comparison of @var{a} and @var{b}.  If
 133 @var{a} is less than @var{b}, they return 0; if @var{a} is greater than
 134 @var{b}, they return 2; and if @var{a} and @var{b} are equal they return 1.
 135 @end deftypefn
 136
 137 @deftypefn {Runtime Function} int __ucmpdi2 (unsigned long @var{a}, unsigned long @var{b})
 138 @deftypefnx {Runtime Function} int __ucmpti2 (unsigned long long @var{a}, unsigned long long @var{b})
 139 These functions perform an unsigned comparison of @var{a} and @var{b}.
 140 If @var{a} is less than @var{b}, they return 0; if @var{a} is greater than
 141 @var{b}, they return 2; and if @var{a} and @var{b} are equal they return 1.
 142 @end deftypefn
 143
 144 @subsection Trapping arithmetic functions
 145
 146 The following functions implement trapping arithmetic.  These functions
 147 call the libc function @code{abort} upon signed arithmetic overflow.
 148
 149 @deftypefn {Runtime Function} int __absvsi2 (int @var{a})
 150 @deftypefnx {Runtime Function} long __absvdi2 (long @var{a})
 151 These functions return the absolute value of @var{a}.
 152 @end deftypefn
 153
 154 @deftypefn {Runtime Function} int __addvsi3 (int @var{a}, int @var{b})
 155 @deftypefnx {Runtime Function} long __addvdi3 (long @var{a}, long @var{b})
 156 These functions return the sum of @var{a} and @var{b}; that is
 157 @code{@var{a} + @var{b}}.
 158 @end deftypefn
 159
 160 @deftypefn {Runtime Function} int __mulvsi3 (int @var{a}, int @var{b})
 161 @deftypefnx {Runtime Function} long __mulvdi3 (long @var{a}, long @var{b})
 162 The functions return the product of @var{a} and @var{b}; that is
 163 @code{@var{a} * @var{b}}.
 164 @end deftypefn
 165
 166 @deftypefn {Runtime Function} int __negvsi2 (int @var{a})
 167 @deftypefnx {Runtime Function} long __negvdi2 (long @var{a})
 168 These functions return the negation of @var{a}; that is @code{-@var{a}}.
 169 @end deftypefn
 170
 171 @deftypefn {Runtime Function} int __subvsi3 (int @var{a}, int @var{b})
 172 @deftypefnx {Runtime Function} long __subvdi3 (long @var{a}, long @var{b})
 173 These functions return the difference between @var{b} and @var{a};
 174 that is @code{@var{a} - @var{b}}.
 175 @end deftypefn
 176
 177 @subsection Bit operations
 178
 179 @deftypefn {Runtime Function} int __clzsi2 (int @var{a})
 180 @deftypefnx {Runtime Function} int __clzdi2 (long @var{a})
 181 @deftypefnx {Runtime Function} int __clzti2 (long long @var{a})
 182 These functions return the number of leading 0-bits in @var{a}, starting
 183 at the most significant bit position.  If @var{a} is zero, the result is
 184 undefined.
 185 @end deftypefn
 186
 187 @deftypefn {Runtime Function} int __ctzsi2 (int @var{a})
 188 @deftypefnx {Runtime Function} int __ctzdi2 (long @var{a})
 189 @deftypefnx {Runtime Function} int __ctzti2 (long long @var{a})
 190 These functions return the number of trailing 0-bits in @var{a}, starting
 191 at the least significant bit position.  If @var{a} is zero, the result is
 192 undefined.
 193 @end deftypefn
 194
 195 @deftypefn {Runtime Function} int __ffsdi2 (long @var{a})
 196 @deftypefnx {Runtime Function} int __ffsti2 (long long @var{a})
 197 These functions return the index of the least significant 1-bit in @var{a},
 198 or the value zero if @var{a} is zero.  The least significant bit is index
 199 one.
 200 @end deftypefn
 201
 202 @deftypefn {Runtime Function} int __paritysi2 (int @var{a})
 203 @deftypefnx {Runtime Function} int __paritydi2 (long @var{a})
 204 @deftypefnx {Runtime Function} int __parityti2 (long long @var{a})
 205 These functions return the value zero if the number of bits set in
 206 @var{a} is even, and the value one otherwise.
 207 @end deftypefn
 208
 209 @deftypefn {Runtime Function} int __popcountsi2 (int @var{a})
 210 @deftypefnx {Runtime Function} int __popcountdi2 (long @var{a})
 211 @deftypefnx {Runtime Function} int __popcountti2 (long long @var{a})
 212 These functions return the number of bits set in @var{a}.
 213 @end deftypefn
 214
 215 @node Soft float library routines
 216 @section Routines for floating point emulation
 217 @cindex soft float library
 218 @cindex arithmetic library
 219 @cindex math library
 220 @opindex msoft-float
 221
 222 The software floating point library is used on machines which do not
 223 have hardware support for floating point.  It is also used whenever
 224 @option{-msoft-float} is used to disable generation of floating point
 225 instructions.  (Not all targets support this switch.)
 226
 227 For compatibility with other compilers, the floating point emulation
 228 routines can be renamed with the @code{DECLARE_LIBRARY_RENAMES} macro
 229 (@pxref{Library Calls}).  In this section, the default names are used.
 230
 231 Presently the library does not support @code{XFmode}, which is used
 232 for @code{long double} on some architectures.
 233
 234 @subsection Arithmetic functions
 235
 236 @deftypefn {Runtime Function} float __addsf3 (float @var{a}, float @var{b})
 237 @deftypefnx {Runtime Function} double __adddf3 (double @var{a}, double @var{b})
 238 @deftypefnx {Runtime Function} {long double} __addtf3 (long double @var{a}, long double @var{b})
 239 @deftypefnx {Runtime Function} {long double} __addxf3 (long double @var{a}, long double @var{b})
 240 These functions return the sum of @var{a} and @var{b}.
 241 @end deftypefn
 242
 243 @deftypefn {Runtime Function} float __subsf3 (float @var{a}, float @var{b})
 244 @deftypefnx {Runtime Function} double __subdf3 (double @var{a}, double @var{b})
 245 @deftypefnx {Runtime Function} {long double} __subtf3 (long double @var{a}, long double @var{b})
 246 @deftypefnx {Runtime Function} {long double} __subxf3 (long double @var{a}, long double @var{b})
 247 These functions return the difference between @var{b} and @var{a};
 248 that is, @w{@math{@var{a} - @var{b}}}.
 249 @end deftypefn
 250
 251 @deftypefn {Runtime Function} float __mulsf3 (float @var{a}, float @var{b})
 252 @deftypefnx {Runtime Function} double __muldf3 (double @var{a}, double @var{b})
 253 @deftypefnx {Runtime Function} {long double} __multf3 (long double @var{a}, long double @var{b})
 254 @deftypefnx {Runtime Function} {long double} __mulxf3 (long double @var{a}, long double @var{b})
 255 These functions return the product of @var{a} and @var{b}.
 256 @end deftypefn
 257
 258 @deftypefn {Runtime Function} float __divsf3 (float @var{a}, float @var{b})
 259 @deftypefnx {Runtime Function} double __divdf3 (double @var{a}, double @var{b})
 260 @deftypefnx {Runtime Function} {long double} __divtf3 (long double @var{a}, long double @var{b})
 261 @deftypefnx {Runtime Function} {long double} __divxf3 (long double @var{a}, long double @var{b})
 262 These functions return the quotient of @var{a} and @var{b}; that is,
 263 @w{@math{@var{a} / @var{b}}}.
 264 @end deftypefn
 265
 266 @deftypefn {Runtime Function} float __negsf2 (float @var{a})
 267 @deftypefnx {Runtime Function} double __negdf2 (double @var{a})
 268 @deftypefnx {Runtime Function} {long double} __negtf2 (long double @var{a})
 269 @deftypefnx {Runtime Function} {long double} __negxf2 (long double @var{a})
 270 These functions return the negation of @var{a}.  They simply flip the
 271 sign bit, so they can produce negative zero and negative NaN@.
 272 @end deftypefn
 273
 274 @subsection Conversion functions
 275
 276 @deftypefn {Runtime Function} double __extendsfdf2 (float @var{a})
 277 @deftypefnx {Runtime Function} {long double} __extendsftf2 (float @var{a})
 278 @deftypefnx {Runtime Function} {long double} __extendsfxf2 (float @var{a})
 279 @deftypefnx {Runtime Function} {long double} __extenddftf2 (double @var{a})
 280 @deftypefnx {Runtime Function} {long double} __extenddfxf2 (double @var{a})
 281 These functions extend @var{a} to the wider mode of their return
 282 type.
 283 @end deftypefn
 284
 285 @deftypefn {Runtime Function} double __truncxfdf2 (long double @var{a})
 286 @deftypefnx {Runtime Function} double __trunctfdf2 (long double @var{a})
 287 @deftypefnx {Runtime Function} float __truncxfsf2 (long double @var{a})
 288 @deftypefnx {Runtime Function} float __trunctfsf2 (long double @var{a})
 289 @deftypefnx {Runtime Function} float __truncdfsf2 (double @var{a})
 290 These functions truncate @var{a} to the narrower mode of their return
 291 type, rounding toward zero.
 292 @end deftypefn
 293
 294 @deftypefn {Runtime Function} int __fixsfsi (float @var{a})
 295 @deftypefnx {Runtime Function} int __fixdfsi (double @var{a})
 296 @deftypefnx {Runtime Function} int __fixtfsi (long double @var{a})
 297 @deftypefnx {Runtime Function} int __fixxfsi (long double @var{a})
 298 These functions convert @var{a} to a signed integer, rounding toward zero.
 299 @end deftypefn
 300
 301 @deftypefn {Runtime Function} long __fixsfdi (float @var{a})
 302 @deftypefnx {Runtime Function} long __fixdfdi (double @var{a})
 303 @deftypefnx {Runtime Function} long __fixtfdi (long double @var{a})
 304 @deftypefnx {Runtime Function} long __fixxfdi (long double @var{a})
 305 These functions convert @var{a} to a signed long, rounding toward zero.
 306 @end deftypefn
 307
 308 @deftypefn {Runtime Function} {long long} __fixsfti (float @var{a})
 309 @deftypefnx {Runtime Function} {long long} __fixdfti (double @var{a})
 310 @deftypefnx {Runtime Function} {long long} __fixtfti (long double @var{a})
 311 @deftypefnx {Runtime Function} {long long} __fixxfti (long double @var{a})
 312 These functions convert @var{a} to a signed long long, rounding toward zero.
 313 @end deftypefn
 314
 315 @deftypefn {Runtime Function} {unsigned int} __fixunssfsi (float @var{a})
 316 @deftypefnx {Runtime Function} {unsigned int} __fixunsdfsi (double @var{a})
 317 @deftypefnx {Runtime Function} {unsigned int} __fixunstfsi (long double @var{a})
 318 @deftypefnx {Runtime Function} {unsigned int} __fixunsxfsi (long double @var{a})
 319 These functions convert @var{a} to an unsigned integer, rounding
 320 toward zero.  Negative values all become zero.
 321 @end deftypefn
 322
 323 @deftypefn {Runtime Function} {unsigned long} __fixunssfdi (float @var{a})
 324 @deftypefnx {Runtime Function} {unsigned long} __fixunsdfdi (double @var{a})
 325 @deftypefnx {Runtime Function} {unsigned long} __fixunstfdi (long double @var{a})
 326 @deftypefnx {Runtime Function} {unsigned long} __fixunsxfdi (long double @var{a})
 327 These functions convert @var{a} to an unsigned long, rounding
 328 toward zero.  Negative values all become zero.
 329 @end deftypefn
 330
 331 @deftypefn {Runtime Function} {unsigned long long} __fixunssfti (float @var{a})
 332 @deftypefnx {Runtime Function} {unsigned long long} __fixunsdfti (double @var{a})
 333 @deftypefnx {Runtime Function} {unsigned long long} __fixunstfti (long double @var{a})
 334 @deftypefnx {Runtime Function} {unsigned long long} __fixunsxfti (long double @var{a})
 335 These functions convert @var{a} to an unsigned long long, rounding
 336 toward zero.  Negative values all become zero.
 337 @end deftypefn
 338
 339 @deftypefn {Runtime Function} float __floatsisf (int @var{i})
 340 @deftypefnx {Runtime Function} double __floatsidf (int @var{i})
 341 @deftypefnx {Runtime Function} {long double} __floatsitf (int @var{i})
 342 @deftypefnx {Runtime Function} {long double} __floatsixf (int @var{i})
 343 These functions convert @var{i}, a signed integer, to floating point.
 344 @end deftypefn
 345
 346 @deftypefn {Runtime Function} float __floatdisf (long @var{i})
 347 @deftypefnx {Runtime Function} double __floatdidf (long @var{i})
 348 @deftypefnx {Runtime Function} {long double} __floatditf (long @var{i})
 349 @deftypefnx {Runtime Function} {long double} __floatdixf (long @var{i})
 350 These functions convert @var{i}, a signed long, to floating point.
 351 @end deftypefn
 352
 353 @deftypefn {Runtime Function} float __floattisf (long long @var{i})
 354 @deftypefnx {Runtime Function} double __floattidf (long long @var{i})
 355 @deftypefnx {Runtime Function} {long double} __floattitf (long long @var{i})
 356 @deftypefnx {Runtime Function} {long double} __floattixf (long long @var{i})
 357 These functions convert @var{i}, a signed long long, to floating point.
 358 @end deftypefn
 359
 360 @deftypefn {Runtime Function} float __floatunsisf (unsigned int @var{i})
 361 @deftypefnx {Runtime Function} double __floatunsidf (unsigned int @var{i})
 362 @deftypefnx {Runtime Function} {long double} __floatunsitf (unsigned int @var{i})
 363 @deftypefnx {Runtime Function} {long double} __floatunsixf (unsigned int @var{i})
 364 These functions convert @var{i}, an unsigned integer, to floating point.
 365 @end deftypefn
 366
 367 @deftypefn {Runtime Function} float __floatundisf (unsigned long @var{i})
 368 @deftypefnx {Runtime Function} double __floatundidf (unsigned long @var{i})
 369 @deftypefnx {Runtime Function} {long double} __floatunditf (unsigned long @var{i})
 370 @deftypefnx {Runtime Function} {long double} __floatundixf (unsigned long @var{i})
 371 These functions convert @var{i}, an unsigned long, to floating point.
 372 @end deftypefn
 373
 374 @deftypefn {Runtime Function} float __floatuntisf (unsigned long long @var{i})
 375 @deftypefnx {Runtime Function} double __floatuntidf (unsigned long long @var{i})
 376 @deftypefnx {Runtime Function} {long double} __floatuntitf (unsigned long long @var{i})
 377 @deftypefnx {Runtime Function} {long double} __floatuntixf (unsigned long long @var{i})
 378 These functions convert @var{i}, an unsigned long long, to floating point.
 379 @end deftypefn
 380
 381 @subsection Comparison functions
 382
 383 There are two sets of basic comparison functions.
 384
 385 @deftypefn {Runtime Function} int __cmpsf2 (float @var{a}, float @var{b})
 386 @deftypefnx {Runtime Function} int __cmpdf2 (double @var{a}, double @var{b})
 387 @deftypefnx {Runtime Function} int __cmptf2 (long double @var{a}, long double @var{b})
 388 These functions calculate @math{a <=> b}.  That is, if @var{a} is less
 389 than @var{b}, they return @minus{}1; if @var{a} is greater than @var{b}, they
 390 return 1; and if @var{a} and @var{b} are equal they return 0.  If
 391 either argument is NaN they return 1, but you should not rely on this;
 392 if NaN is a possibility, use one of the higher-level comparison
 393 functions.
 394 @end deftypefn
 395
 396 @deftypefn {Runtime Function} int __unordsf2 (float @var{a}, float @var{b})
 397 @deftypefnx {Runtime Function} int __unorddf2 (double @var{a}, double @var{b})
 398 @deftypefnx {Runtime Function} int __unordtf2 (long double @var{a}, long double @var{b})
 399 These functions return a nonzero value if either argument is NaN, otherwise 0.
 400 @end deftypefn
 401
 402 There is also a complete group of higher level functions which
 403 correspond directly to comparison operators.  They implement the ISO C
 404 semantics for floating-point comparisons, taking NaN into account.
 405 Pay careful attention to the return values defined for each set.
 406 Under the hood, all of these routines are implemented as
 407
 408 @smallexample
 409   if (__unord@var{X}f2 (a, b))
 410     return @var{E};
 411   return __cmp@var{X}f2 (a, b);
 412 @end smallexample
 413
 414 @noindent
 415 where @var{E} is a constant chosen to give the proper behavior for
 416 NaN@.  Thus, the meaning of the return value is different for each set.
 417 Do not rely on this implementation; only the semantics documented
 418 below are guaranteed.
 419
 420 @deftypefn {Runtime Function} int __eqsf2 (float @var{a}, float @var{b})
 421 @deftypefnx {Runtime Function} int __eqdf2 (double @var{a}, double @var{b})
 422 @deftypefnx {Runtime Function} int __eqtf2 (long double @var{a}, long double @var{b})
 423 These functions return zero if neither argument is NaN, and @var{a} and
 424 @var{b} are equal.
 425 @end deftypefn
 426
 427 @deftypefn {Runtime Function} int __nesf2 (float @var{a}, float @var{b})
 428 @deftypefnx {Runtime Function} int __nedf2 (double @var{a}, double @var{b})
 429 @deftypefnx {Runtime Function} int __netf2 (long double @var{a}, long double @var{b})
 430 These functions return a nonzero value if either argument is NaN, or
 431 if @var{a} and @var{b} are unequal.
 432 @end deftypefn
 433
 434 @deftypefn {Runtime Function} int __gesf2 (float @var{a}, float @var{b})
 435 @deftypefnx {Runtime Function} int __gedf2 (double @var{a}, double @var{b})
 436 @deftypefnx {Runtime Function} int __getf2 (long double @var{a}, long double @var{b})
 437 These functions return a value greater than or equal to zero if
 438 neither argument is NaN, and @var{a} is greater than or equal to
 439 @var{b}.
 440 @end deftypefn
 441
 442 @deftypefn {Runtime Function} int __ltsf2 (float @var{a}, float @var{b})
 443 @deftypefnx {Runtime Function} int __ltdf2 (double @var{a}, double @var{b})
 444 @deftypefnx {Runtime Function} int __lttf2 (long double @var{a}, long double @var{b})
 445 These functions return a value less than zero if neither argument is
 446 NaN, and @var{a} is strictly less than @var{b}.
 447 @end deftypefn
 448
 449 @deftypefn {Runtime Function} int __lesf2 (float @var{a}, float @var{b})
 450 @deftypefnx {Runtime Function} int __ledf2 (double @var{a}, double @var{b})
 451 @deftypefnx {Runtime Function} int __letf2 (long double @var{a}, long double @var{b})
 452 These functions return a value less than or equal to zero if neither
 453 argument is NaN, and @var{a} is less than or equal to @var{b}.
 454 @end deftypefn
 455
 456 @deftypefn {Runtime Function} int __gtsf2 (float @var{a}, float @var{b})
 457 @deftypefnx {Runtime Function} int __gtdf2 (double @var{a}, double @var{b})
 458 @deftypefnx {Runtime Function} int __gttf2 (long double @var{a}, long double @var{b})
 459 These functions return a value greater than zero if neither argument
 460 is NaN, and @var{a} is strictly greater than @var{b}.
 461 @end deftypefn
 462
 463 @subsection Other floating-point functions
 464
 465 @deftypefn {Runtime Function} float __powisf2 (float @var{a}, int @var{b})
 466 @deftypefnx {Runtime Function} double __powidf2 (double @var{a}, int @var{b})
 467 @deftypefnx {Runtime Function} {long double} __powitf2 (long double @var{a}, int @var{b})
 468 @deftypefnx {Runtime Function} {long double} __powixf2 (long double @var{a}, int @var{b})
 469 These functions convert raise @var{a} to the power @var{b}.
 470 @end deftypefn
 471
 472 @deftypefn {Runtime Function} {complex float} __mulsc3 (float @var{a}, float @var{b}, float @var{c}, float @var{d})
 473 @deftypefnx {Runtime Function} {complex double} __muldc3 (double @var{a}, double @var{b}, double @var{c}, double @var{d})
 474 @deftypefnx {Runtime Function} {complex long double} __multc3 (long double @var{a}, long double @var{b}, long double @var{c}, long double @var{d})
 475 @deftypefnx {Runtime Function} {complex long double} __mulxc3 (long double @var{a}, long double @var{b}, long double @var{c}, long double @var{d})
 476 These functions return the product of @math{@var{a} + i@var{b}} and
 477 @math{@var{c} + i@var{d}}, following the rules of C99 Annex G@.
 478 @end deftypefn
 479
 480 @deftypefn {Runtime Function} {complex float} __divsc3 (float @var{a}, float @var{b}, float @var{c}, float @var{d})
 481 @deftypefnx {Runtime Function} {complex double} __divdc3 (double @var{a}, double @var{b}, double @var{c}, double @var{d})
 482 @deftypefnx {Runtime Function} {complex long double} __divtc3 (long double @var{a}, long double @var{b}, long double @var{c}, long double @var{d})
 483 @deftypefnx {Runtime Function} {complex long double} __divxc3 (long double @var{a}, long double @var{b}, long double @var{c}, long double @var{d})
 484 These functions return the quotient of @math{@var{a} + i@var{b}} and
 485 @math{@var{c} + i@var{d}} (i.e., @math{(@var{a} + i@var{b}) / (@var{c}
 486 + i@var{d})}), following the rules of C99 Annex G@.
 487 @end deftypefn
 488
 489 @node Decimal float library routines
 490 @section Routines for decimal floating point emulation
 491 @cindex decimal float library
 492 @cindex IEEE-754R
 493
 494 The software decimal floating point library implements IEEE 754R
 495 decimal floating point arithmetic and is only activated on selected
 496 targets.
 497
 498 @subsection Arithmetic functions
 499
 500 @deftypefn {Runtime Function} _Decimal32 __addsd3 (_Decimal32 @var{a}, _Decimal32 @var{b})
 501 @deftypefnx {Runtime Function} _Decimal64 __adddd3 (_Decimal64 @var{a}, _Decimal64 @var{b})
 502 @deftypefnx {Runtime Function} _Decimal128 __addtd3 (_Decimal128 @var{a}, _Decimal128 @var{b})
 503 These functions return the sum of @var{a} and @var{b}.
 504 @end deftypefn
 505
 506 @deftypefn {Runtime Function} _Decimal32 __subsd3 (_Decimal32 @var{a}, _Decimal32 @var{b})
 507 @deftypefnx {Runtime Function} _Decimal64 __subdd3 (_Decimal64 @var{a}, _Decimal64 @var{b})
 508 @deftypefnx {Runtime Function} _Decimal128 __subtd3 (_Decimal128 @var{a}, _Decimal128 @var{b})
 509 These functions return the difference between @var{b} and @var{a};
 510 that is, @w{@math{@var{a} - @var{b}}}.
 511 @end deftypefn
 512
 513 @deftypefn {Runtime Function} _Decimal32 __mulsd3 (_Decimal32 @var{a}, _Decimal32 @var{b})
 514 @deftypefnx {Runtime Function} _Decimal64 __muldd3 (_Decimal64 @var{a}, _Decimal64 @var{b})
 515 @deftypefnx {Runtime Function} _Decimal128 __multd3 (_Decimal128 @var{a}, _Decimal128 @var{b})
 516 These functions return the product of @var{a} and @var{b}.
 517 @end deftypefn
 518
 519 @deftypefn {Runtime Function} _Decimal32 __divsd3 (_Decimal32 @var{a}, _Decimal32 @var{b})
 520 @deftypefnx {Runtime Function} _Decimal64 __divdd3 (_Decimal64 @var{a}, _Decimal64 @var{b})
 521 @deftypefnx {Runtime Function} _Decimal128 __divtd3 (_Decimal128 @var{a}, _Decimal128 @var{b})
 522 These functions return the quotient of @var{a} and @var{b}; that is,
 523 @w{@math{@var{a} / @var{b}}}.
 524 @end deftypefn
 525
 526 @deftypefn {Runtime Function} _Decimal32 __negsd2 (_Decimal32 @var{a})
 527 @deftypefnx {Runtime Function} _Decimal64 __negdd2 (_Decimal64 @var{a})
 528 @deftypefnx {Runtime Function} _Decimal128 __negtd2 (_Decimal128 @var{a})
 529 These functions return the negation of @var{a}.  They simply flip the
 530 sign bit, so they can produce negative zero and negative NaN@.
 531 @end deftypefn
 532
 533 @subsection Conversion functions
 534
 535 @c DFP/DFP conversions
 536 @deftypefn {Runtime Function} _Decimal64 __extendsddd2 (_Decimal32 @var{a})
 537 @deftypefnx {Runtime Function} _Decimal128 __extendsdtd2 (_Decimal32 @var{a})
 538 @deftypefnx {Runtime Function} _Decimal128 __extendddtd2 (_Decimal64 @var{a})
 539 @c DFP/binary FP conversions
 540 @deftypefnx {Runtime Function} _Decimal32 __extendsfsd (float @var{a})
 541 @deftypefnx {Runtime Function} double __extendsddf (_Decimal32 @var{a})
 542 @deftypefnx {Runtime Function} {long double} __extendsdxf (_Decimal32 @var{a})
 543 @deftypefnx {Runtime Function} _Decimal64 __extendsfdd (float @var{a})
 544 @deftypefnx {Runtime Function} _Decimal64 __extenddfdd (double @var{a})
 545 @deftypefnx {Runtime Function} {long double} __extendddxf (_Decimal64 @var{a})
 546 @deftypefnx {Runtime Function} _Decimal128 __extendsftd (float @var{a})
 547 @deftypefnx {Runtime Function} _Decimal128 __extenddftd (double @var{a})
 548 @deftypefnx {Runtime Function} _Decimal128 __extendxftd ({long double} @var{a})
 549 These functions extend @var{a} to the wider mode of their return type.
 550 @end deftypefn
 551
 552 @c DFP/DFP conversions
 553 @deftypefn {Runtime Function} _Decimal32 __truncddsd2 (_Decimal64 @var{a})
 554 @deftypefnx {Runtime Function} _Decimal32 __trunctdsd2 (_Decimal128 @var{a})
 555 @deftypefnx {Runtime Function} _Decimal64 __trunctddd2 (_Decimal128 @var{a})
 556 @c DFP/binary FP conversions
 557 @deftypefnx {Runtime Function} float __truncsdsf (_Decimal32 @var{a})
 558 @deftypefnx {Runtime Function} _Decimal32 __truncdfsd (double @var{a})
 559 @deftypefnx {Runtime Function} _Decimal32 __truncxfsd ({long double} @var{a})
 560 @deftypefnx {Runtime Function} float __truncddsf (_Decimal64 @var{a})
 561 @deftypefnx {Runtime Function} double __truncdddf (_Decimal64 @var{a})
 562 @deftypefnx {Runtime Function} _Decimal64 __truncxfdd ({long double} @var{a})
 563 @deftypefnx {Runtime Function} float __trunctdsf (_Decimal128 @var{a})
 564 @deftypefnx {Runtime Function} double __trunctddf (_Decimal128 @var{a})
 565 @deftypefnx {Runtime Function} {long double} __trunctdxf (_Decimal128 @var{a})
 566 These functions truncate @var{a} to the narrower mode of their return
 567 type.
 568 @end deftypefn
 569
 570 @deftypefn {Runtime Function} int __fixsdsi (_Decimal32 @var{a})
 571 @deftypefnx {Runtime Function} int __fixddsi (_Decimal64 @var{a})
 572 @deftypefnx {Runtime Function} int __fixtdsi (_Decimal128 @var{a})
 573 These functions convert @var{a} to a signed integer.
 574 @end deftypefn
 575
 576 @deftypefn {Runtime Function} long __fixsddi (_Decimal32 @var{a})
 577 @deftypefnx {Runtime Function} long __fixdddi (_Decimal64 @var{a})
 578 @deftypefnx {Runtime Function} long __fixtddi (_Decimal128 @var{a})
 579 These functions convert @var{a} to a signed long.
 580 @end deftypefn
 581
 582 @deftypefn {Runtime Function} {unsigned int} __fixunssdsi (_Decimal32 @var{a})
 583 @deftypefnx {Runtime Function} {unsigned int} __fixunsddsi (_Decimal64 @var{a})
 584 @deftypefnx {Runtime Function} {unsigned int} __fixunstdsi (_Decimal128 @var{a})
 585 These functions convert @var{a} to an unsigned integer.  Negative values all become zero.
 586 @end deftypefn
 587
 588 @deftypefn {Runtime Function} {unsigned long} __fixunssddi (_Decimal32 @var{a})
 589 @deftypefnx {Runtime Function} {unsigned long} __fixunsdddi (_Decimal64 @var{a})
 590 @deftypefnx {Runtime Function} {unsigned long} __fixunstddi (_Decimal128 @var{a})
 591 These functions convert @var{a} to an unsigned long.  Negative values
 592 all become zero.
 593 @end deftypefn
 594
 595 @deftypefn {Runtime Function} _Decimal32 __floatsisd (int @var{i})
 596 @deftypefnx {Runtime Function} _Decimal64 __floatsidd (int @var{i})
 597 @deftypefnx {Runtime Function} _Decimal128 __floatsitd (int @var{i})
 598 These functions convert @var{i}, a signed integer, to decimal floating point.
 599 @end deftypefn
 600
 601 @deftypefn {Runtime Function} _Decimal32 __floatdisd (long @var{i})
 602 @deftypefnx {Runtime Function} _Decimal64 __floatdidd (long @var{i})
 603 @deftypefnx {Runtime Function} _Decimal128 __floatditd (long @var{i})
 604 These functions convert @var{i}, a signed long, to decimal floating point.
 605 @end deftypefn
 606
 607 @deftypefn {Runtime Function} _Decimal32 __floatunssisd (unsigned int @var{i})
 608 @deftypefnx {Runtime Function} _Decimal64 __floatunssidd (unsigned int @var{i})
 609 @deftypefnx {Runtime Function} _Decimal128 __floatunssitd (unsigned int @var{i})
 610 These functions convert @var{i}, an unsigned integer, to decimal floating point.
 611 @end deftypefn
 612
 613 @deftypefn {Runtime Function} _Decimal32 __floatunsdisd (unsigned long @var{i})
 614 @deftypefnx {Runtime Function} _Decimal64 __floatunsdidd (unsigned long @var{i})
 615 @deftypefnx {Runtime Function} _Decimal128 __floatunsditd (unsigned long @var{i})
 616 These functions convert @var{i}, an unsigned long, to decimal floating point.
 617 @end deftypefn
 618
 619 @subsection Comparison functions
 620
 621 @deftypefn {Runtime Function} int __unordsd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
 622 @deftypefnx {Runtime Function} int __unorddd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
 623 @deftypefnx {Runtime Function} int __unordtd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
 624 These functions return a nonzero value if either argument is NaN, otherwise 0.
 625 @end deftypefn
 626
 627 There is also a complete group of higher level functions which
 628 correspond directly to comparison operators.  They implement the ISO C
 629 semantics for floating-point comparisons, taking NaN into account.
 630 Pay careful attention to the return values defined for each set.
 631 Under the hood, all of these routines are implemented as
 632
 633 @smallexample
 634   if (__unord@var{X}d2 (a, b))
 635     return @var{E};
 636   return __cmp@var{X}d2 (a, b);
 637 @end smallexample
 638
 639 @noindent
 640 where @var{E} is a constant chosen to give the proper behavior for
 641 NaN@.  Thus, the meaning of the return value is different for each set.
 642 Do not rely on this implementation; only the semantics documented
 643 below are guaranteed.
 644
 645 @deftypefn {Runtime Function} int __eqsd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
 646 @deftypefnx {Runtime Function} int __eqdd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
 647 @deftypefnx {Runtime Function} int __eqtd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
 648 These functions return zero if neither argument is NaN, and @var{a} and
 649 @var{b} are equal.
 650 @end deftypefn
 651
 652 @deftypefn {Runtime Function} int __nesd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
 653 @deftypefnx {Runtime Function} int __nedd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
 654 @deftypefnx {Runtime Function} int __netd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
 655 These functions return a nonzero value if either argument is NaN, or
 656 if @var{a} and @var{b} are unequal.
 657 @end deftypefn
 658
 659 @deftypefn {Runtime Function} int __gesd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
 660 @deftypefnx {Runtime Function} int __gedd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
 661 @deftypefnx {Runtime Function} int __getd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
 662 These functions return a value greater than or equal to zero if
 663 neither argument is NaN, and @var{a} is greater than or equal to
 664 @var{b}.
 665 @end deftypefn
 666
 667 @deftypefn {Runtime Function} int __ltsd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
 668 @deftypefnx {Runtime Function} int __ltdd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
 669 @deftypefnx {Runtime Function} int __lttd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
 670 These functions return a value less than zero if neither argument is
 671 NaN, and @var{a} is strictly less than @var{b}.
 672 @end deftypefn
 673
 674 @deftypefn {Runtime Function} int __lesd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
 675 @deftypefnx {Runtime Function} int __ledd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
 676 @deftypefnx {Runtime Function} int __letd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
 677 These functions return a value less than or equal to zero if neither
 678 argument is NaN, and @var{a} is less than or equal to @var{b}.
 679 @end deftypefn
 680
 681 @deftypefn {Runtime Function} int __gtsd2 (_Decimal32 @var{a}, _Decimal32 @var{b})
 682 @deftypefnx {Runtime Function} int __gtdd2 (_Decimal64 @var{a}, _Decimal64 @var{b})
 683 @deftypefnx {Runtime Function} int __gttd2 (_Decimal128 @var{a}, _Decimal128 @var{b})
 684 These functions return a value greater than zero if neither argument
 685 is NaN, and @var{a} is strictly greater than @var{b}.
 686 @end deftypefn
 687
 688 @node Exception handling routines
 689 @section Language-independent routines for exception handling
 690
 691 document me!
 692
 693 @smallexample
 694   _Unwind_DeleteException
 695   _Unwind_Find_FDE
 696   _Unwind_ForcedUnwind
 697   _Unwind_GetGR
 698   _Unwind_GetIP
 699   _Unwind_GetLanguageSpecificData
 700   _Unwind_GetRegionStart
 701   _Unwind_GetTextRelBase
 702   _Unwind_GetDataRelBase
 703   _Unwind_RaiseException
 704   _Unwind_Resume
 705   _Unwind_SetGR
 706   _Unwind_SetIP
 707   _Unwind_FindEnclosingFunction
 708   _Unwind_SjLj_Register
 709   _Unwind_SjLj_Unregister
 710   _Unwind_SjLj_RaiseException
 711   _Unwind_SjLj_ForcedUnwind
 712   _Unwind_SjLj_Resume
 713   __deregister_frame
 714   __deregister_frame_info
 715   __deregister_frame_info_bases
 716   __register_frame
 717   __register_frame_info
 718   __register_frame_info_bases
 719   __register_frame_info_table
 720   __register_frame_info_table_bases
 721   __register_frame_table
 722 @end smallexample
 723
 724 @node Miscellaneous routines
 725 @section Miscellaneous runtime library routines
 726
 727 @subsection Cache control functions
 728 @deftypefn {Runtime Function} void __clear_cache (char *@var{beg}, char *@var{end})
 729 This function clears the instruction cache between @var{beg} and @var{end}.
 730 @end deftypefn
 731