libgcc.texi revision 169690
11590Srgrimes@c Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc. 21590Srgrimes@c This is part of the GCC manual. 31590Srgrimes@c For copying conditions, see the file gcc.texi. 41590Srgrimes@c Contributed by Aldy Hernandez <aldy@quesejoda.com> 51590Srgrimes 61590Srgrimes@node Libgcc 71590Srgrimes@chapter The GCC low-level runtime library 81590Srgrimes 91590SrgrimesGCC provides a low-level runtime library, @file{libgcc.a} or 101590Srgrimes@file{libgcc_s.so.1} on some platforms. GCC generates calls to 111590Srgrimesroutines in this library automatically, whenever it needs to perform 121590Srgrimessome operation that is too complicated to emit inline code for. 131590Srgrimes 141590SrgrimesMost of the routines in @code{libgcc} handle arithmetic operations 151590Srgrimesthat the target processor cannot perform directly. This includes 161590Srgrimesinteger multiply and divide on some machines, and all floating-point 171590Srgrimesoperations on other machines. @code{libgcc} also includes routines 181590Srgrimesfor exception handling, and a handful of miscellaneous operations. 191590Srgrimes 201590SrgrimesSome of these routines can be defined in mostly machine-independent C@. 211590SrgrimesOthers must be hand-written in assembly language for each processor 221590Srgrimesthat needs them. 231590Srgrimes 241590SrgrimesGCC will also generate calls to C library routines, such as 251590Srgrimes@code{memcpy} and @code{memset}, in some cases. The set of routines 261590Srgrimesthat GCC may possibly use is documented in @ref{Other 271590SrgrimesBuiltins,,,gcc, Using the GNU Compiler Collection (GCC)}. 281590Srgrimes 291590SrgrimesThese routines take arguments and return values of a specific machine 3087628Sdwmalonemode, not a specific C type. @xref{Machine Modes}, for an explanation 3187628Sdwmaloneof this concept. For illustrative purposes, in this chapter the 3287628Sdwmalonefloating point type @code{float} is assumed to correspond to @code{SFmode}; 3387628Sdwmalone@code{double} to @code{DFmode}; and @code{@w{long double}} to both 3487628Sdwmalone@code{TFmode} and @code{XFmode}. Similarly, the integer types @code{int} 3587628Sdwmaloneand @code{@w{unsigned int}} correspond to @code{SImode}; @code{long} and 3687249Smarkm@code{@w{unsigned long}} to @code{DImode}; and @code{@w{long long}} and 3787249Smarkm@code{@w{unsigned long long}} to @code{TImode}. 3887249Smarkm 391590Srgrimes@menu 401590Srgrimes* Integer library routines:: 411590Srgrimes* Soft float library routines:: 421590Srgrimes* Decimal float library routines:: 431590Srgrimes* Exception handling routines:: 441590Srgrimes* Miscellaneous routines:: 451590Srgrimes@end menu 461590Srgrimes 471590Srgrimes@node Integer library routines 481590Srgrimes@section Routines for integer arithmetic 491590Srgrimes 50100822SdwmaloneThe integer arithmetic routines are used on platforms that don't provide 511590Srgrimeshardware support for arithmetic operations on some modes. 521590Srgrimes 531590Srgrimes@subsection Arithmetic functions 541590Srgrimes 551590Srgrimes@deftypefn {Runtime Function} int __ashlsi3 (int @var{a}, int @var{b}) 561590Srgrimes@deftypefnx {Runtime Function} long __ashldi3 (long @var{a}, int @var{b}) 571590Srgrimes@deftypefnx {Runtime Function} {long long} __ashlti3 (long long @var{a}, int @var{b}) 581590SrgrimesThese functions return the result of shifting @var{a} left by @var{b} bits. 591590Srgrimes@end deftypefn 601590Srgrimes 611590Srgrimes@deftypefn {Runtime Function} int __ashrsi3 (int @var{a}, int @var{b}) 621590Srgrimes@deftypefnx {Runtime Function} long __ashrdi3 (long @var{a}, int @var{b}) 631590Srgrimes@deftypefnx {Runtime Function} {long long} __ashrti3 (long long @var{a}, int @var{b}) 641590SrgrimesThese functions return the result of arithmetically shifting @var{a} right 651590Srgrimesby @var{b} bits. 661590Srgrimes@end deftypefn 671590Srgrimes 681590Srgrimes@deftypefn {Runtime Function} int __divsi3 (int @var{a}, int @var{b}) 691590Srgrimes@deftypefnx {Runtime Function} long __divdi3 (long @var{a}, long @var{b}) 701590Srgrimes@deftypefnx {Runtime Function} {long long} __divti3 (long long @var{a}, long long @var{b}) 711590SrgrimesThese functions return the quotient of the signed division of @var{a} and 721590Srgrimes@var{b}. 731590Srgrimes@end deftypefn 741590Srgrimes 751590Srgrimes@deftypefn {Runtime Function} int __lshrsi3 (int @var{a}, int @var{b}) 761590Srgrimes@deftypefnx {Runtime Function} long __lshrdi3 (long @var{a}, int @var{b}) 771590Srgrimes@deftypefnx {Runtime Function} {long long} __lshrti3 (long long @var{a}, int @var{b}) 781590SrgrimesThese functions return the result of logically shifting @var{a} right by 791590Srgrimes@var{b} bits. 801590Srgrimes@end deftypefn 811590Srgrimes 821590Srgrimes@deftypefn {Runtime Function} int __modsi3 (int @var{a}, int @var{b}) 831590Srgrimes@deftypefnx {Runtime Function} long __moddi3 (long @var{a}, long @var{b}) 8491189Sgshapiro@deftypefnx {Runtime Function} {long long} __modti3 (long long @var{a}, long long @var{b}) 8591189SgshapiroThese functions return the remainder of the signed division of @var{a} 861590Srgrimesand @var{b}. 871590Srgrimes@end deftypefn 881590Srgrimes 891590Srgrimes@deftypefn {Runtime Function} int __mulsi3 (int @var{a}, int @var{b}) 901590Srgrimes@deftypefnx {Runtime Function} long __muldi3 (long @var{a}, long @var{b}) 911590Srgrimes@deftypefnx {Runtime Function} {long long} __multi3 (long long @var{a}, long long @var{b}) 921590SrgrimesThese functions return the product of @var{a} and @var{b}. 931590Srgrimes@end deftypefn 9432069Salex 951590Srgrimes@deftypefn {Runtime Function} long __negdi2 (long @var{a}) 961590Srgrimes@deftypefnx {Runtime Function} {long long} __negti2 (long long @var{a}) 971590SrgrimesThese functions return the negation of @var{a}. 981590Srgrimes@end deftypefn 991590Srgrimes 1001590Srgrimes@deftypefn {Runtime Function} {unsigned int} __udivsi3 (unsigned int @var{a}, unsigned int @var{b}) 1011590Srgrimes@deftypefnx {Runtime Function} {unsigned long} __udivdi3 (unsigned long @var{a}, unsigned long @var{b}) 1021590Srgrimes@deftypefnx {Runtime Function} {unsigned long long} __udivti3 (unsigned long long @var{a}, unsigned long long @var{b}) 1031590SrgrimesThese functions return the quotient of the unsigned division of @var{a} 1041590Srgrimesand @var{b}. 1051590Srgrimes@end deftypefn 1061590Srgrimes 1071590Srgrimes@deftypefn {Runtime Function} {unsigned long} __udivmoddi3 (unsigned long @var{a}, unsigned long @var{b}, unsigned long *@var{c}) 1081590Srgrimes@deftypefnx {Runtime Function} {unsigned long long} __udivti3 (unsigned long long @var{a}, unsigned long long @var{b}, unsigned long long *@var{c}) 1091590SrgrimesThese functions calculate both the quotient and remainder of the unsigned 1101590Srgrimesdivision of @var{a} and @var{b}. The return value is the quotient, and 1111590Srgrimesthe remainder is placed in variable pointed to by @var{c}. 1121590Srgrimes@end deftypefn 1131590Srgrimes 1141590Srgrimes@deftypefn {Runtime Function} {unsigned int} __umodsi3 (unsigned int @var{a}, unsigned int @var{b}) 1151590Srgrimes@deftypefnx {Runtime Function} {unsigned long} __umoddi3 (unsigned long @var{a}, unsigned long @var{b}) 1161590Srgrimes@deftypefnx {Runtime Function} {unsigned long long} __umodti3 (unsigned long long @var{a}, unsigned long long @var{b}) 1171590SrgrimesThese functions return the remainder of the unsigned division of @var{a} 1181590Srgrimesand @var{b}. 1191590Srgrimes@end deftypefn 1201590Srgrimes 1211590Srgrimes@subsection Comparison functions 122100822Sdwmalone 1231590SrgrimesThe following functions implement integral comparisons. These functions 1241590Srgrimesimplement a low-level compare, upon which the higher level comparison 1251590Srgrimesoperators (such as less than and greater than or equal to) can be 1261590Srgrimesconstructed. The returned values lie in the range zero to two, to allow 1271590Srgrimesthe high-level operators to be implemented by testing the returned 1281590Srgrimesresult using either signed or unsigned comparison. 1291590Srgrimes 1301590Srgrimes@deftypefn {Runtime Function} int __cmpdi2 (long @var{a}, long @var{b}) 13187750Scharnier@deftypefnx {Runtime Function} int __cmpti2 (long long @var{a}, long long @var{b}) 1321590SrgrimesThese functions perform a signed comparison of @var{a} and @var{b}. If 1331590Srgrimes@var{a} is less than @var{b}, they return 0; if @var{a} is greater than 1341590Srgrimes@var{b}, they return 2; and if @var{a} and @var{b} are equal they return 1. 1351590Srgrimes@end deftypefn 1361590Srgrimes 1371590Srgrimes@deftypefn {Runtime Function} int __ucmpdi2 (unsigned long @var{a}, unsigned long @var{b}) 1381590Srgrimes@deftypefnx {Runtime Function} int __ucmpti2 (unsigned long long @var{a}, unsigned long long @var{b}) 1391590SrgrimesThese functions perform an unsigned comparison of @var{a} and @var{b}. 1401590SrgrimesIf @var{a} is less than @var{b}, they return 0; if @var{a} is greater than 1411590Srgrimes@var{b}, they return 2; and if @var{a} and @var{b} are equal they return 1. 1421590Srgrimes@end deftypefn 1431590Srgrimes 1441590Srgrimes@subsection Trapping arithmetic functions 1451590Srgrimes 1461590SrgrimesThe following functions implement trapping arithmetic. These functions 1471590Srgrimescall the libc function @code{abort} upon signed arithmetic overflow. 1481590Srgrimes 1491590Srgrimes@deftypefn {Runtime Function} int __absvsi2 (int @var{a}) 1501590Srgrimes@deftypefnx {Runtime Function} long __absvdi2 (long @var{a}) 1511590SrgrimesThese 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}) 156These 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}) 162The 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}) 168These 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}) 173These functions return the difference between @var{b} and @var{a}; 174that 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}) 182These functions return the number of leading 0-bits in @var{a}, starting 183at the most significant bit position. If @var{a} is zero, the result is 184undefined. 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}) 190These functions return the number of trailing 0-bits in @var{a}, starting 191at the least significant bit position. If @var{a} is zero, the result is 192undefined. 193@end deftypefn 194 195@deftypefn {Runtime Function} int __ffsdi2 (long @var{a}) 196@deftypefnx {Runtime Function} int __ffsti2 (long long @var{a}) 197These functions return the index of the least significant 1-bit in @var{a}, 198or the value zero if @var{a} is zero. The least significant bit is index 199one. 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}) 205These 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}) 212These 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 222The software floating point library is used on machines which do not 223have hardware support for floating point. It is also used whenever 224@option{-msoft-float} is used to disable generation of floating point 225instructions. (Not all targets support this switch.) 226 227For compatibility with other compilers, the floating point emulation 228routines can be renamed with the @code{DECLARE_LIBRARY_RENAMES} macro 229(@pxref{Library Calls}). In this section, the default names are used. 230 231Presently the library does not support @code{XFmode}, which is used 232for @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}) 240These 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}) 247These functions return the difference between @var{b} and @var{a}; 248that 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}) 255These 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}) 262These 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}) 270These functions return the negation of @var{a}. They simply flip the 271sign 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}) 281These functions extend @var{a} to the wider mode of their return 282type. 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}) 290These functions truncate @var{a} to the narrower mode of their return 291type, 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}) 298These 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}) 305These 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}) 312These 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}) 319These functions convert @var{a} to an unsigned integer, rounding 320toward 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}) 327These functions convert @var{a} to an unsigned long, rounding 328toward 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}) 335These functions convert @var{a} to an unsigned long long, rounding 336toward 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}) 343These 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}) 350These 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}) 357These 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}) 364These 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}) 371These 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}) 378These functions convert @var{i}, an unsigned long long, to floating point. 379@end deftypefn 380 381@subsection Comparison functions 382 383There 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}) 388These functions calculate @math{a <=> b}. That is, if @var{a} is less 389than @var{b}, they return @minus{}1; if @var{a} is greater than @var{b}, they 390return 1; and if @var{a} and @var{b} are equal they return 0. If 391either argument is NaN they return 1, but you should not rely on this; 392if NaN is a possibility, use one of the higher-level comparison 393functions. 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}) 399These functions return a nonzero value if either argument is NaN, otherwise 0. 400@end deftypefn 401 402There is also a complete group of higher level functions which 403correspond directly to comparison operators. They implement the ISO C 404semantics for floating-point comparisons, taking NaN into account. 405Pay careful attention to the return values defined for each set. 406Under 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 415where @var{E} is a constant chosen to give the proper behavior for 416NaN@. Thus, the meaning of the return value is different for each set. 417Do not rely on this implementation; only the semantics documented 418below 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}) 423These 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}) 430These functions return a nonzero value if either argument is NaN, or 431if @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}) 437These functions return a value greater than or equal to zero if 438neither 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}) 445These functions return a value less than zero if neither argument is 446NaN, 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}) 452These functions return a value less than or equal to zero if neither 453argument 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}) 459These functions return a value greater than zero if neither argument 460is 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}) 469These 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}) 476These 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}) 484These 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 494The software decimal floating point library implements IEEE 754R 495decimal floating point arithmetic and is only activated on selected 496targets. 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}) 503These 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}) 509These functions return the difference between @var{b} and @var{a}; 510that 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}) 516These 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}) 522These 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}) 529These functions return the negation of @var{a}. They simply flip the 530sign 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}) 549These 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}) 566These functions truncate @var{a} to the narrower mode of their return 567type. 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}) 573These 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}) 579These 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}) 585These 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}) 591These functions convert @var{a} to an unsigned long. Negative values 592all 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}) 598These 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}) 604These 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}) 610These 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}) 616These 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}) 624These functions return a nonzero value if either argument is NaN, otherwise 0. 625@end deftypefn 626 627There is also a complete group of higher level functions which 628correspond directly to comparison operators. They implement the ISO C 629semantics for floating-point comparisons, taking NaN into account. 630Pay careful attention to the return values defined for each set. 631Under 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 640where @var{E} is a constant chosen to give the proper behavior for 641NaN@. Thus, the meaning of the return value is different for each set. 642Do not rely on this implementation; only the semantics documented 643below 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}) 648These 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}) 655These functions return a nonzero value if either argument is NaN, or 656if @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}) 662These functions return a value greater than or equal to zero if 663neither 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}) 670These functions return a value less than zero if neither argument is 671NaN, 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}) 677These functions return a value less than or equal to zero if neither 678argument 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}) 684These functions return a value greater than zero if neither argument 685is 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 691document 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}) 729This function clears the instruction cache between @var{beg} and @var{end}. 730@end deftypefn 731 732