The GCC low-level runtime library
*********************************

GCC provides a low-level runtime library, libgcc.a or libgcc_s.so.1 on some platforms.  GCC generates calls to routines in this library automatically, whenever it needs to perform some operation that is too complicated to emit inline code for.

Most of the routines in libgcc handle arithmetic operations that the target processor cannot perform directly.  This includes integer multiply and divide on some machines, and all floating-point operations on other machines.  libgcc also includes routines for exception handling, and a handful of miscellaneous operations.

Some of these routines can be defined in mostly machine-independent C. Others must be hand-written in assembly language for each processor that needs them.

GCC will also generate calls to C library routines, such as memcpy and memset, in some cases.  The set of routines that GCC may possibly use is documented in Other Builtins (Using the GNU Compiler Collection (GCC)).

These routines take arguments and return values of a specific machine mode, not a specific C type.  See Machine Modes, for an explanation of this concept.  For illustrative purposes, in this chapter the floating point type float is assumed to correspond to SFmode; double to DFmode; and long double to both TFmode and XFmode.  Similarly, the integer types int and unsigned int correspond to SImode; long and unsigned long to DImode; and long long and unsigned long long to TImode.

Routines for integer arithmetic
===============================

The integer arithmetic routines are used on platforms that don't provide hardware support for arithmetic operations on some modes.

Arithmetic functions
--------------------

 -- Runtime Function: int __ashlsi3 (int A, int B)
 -- Runtime Function: long __ashldi3 (long A, int B)
 -- Runtime Function: long long __ashlti3 (long long A, int B)
     These functions return the result of shifting A left by B bits.

 -- Runtime Function: int __ashrsi3 (int A, int B)
 -- Runtime Function: long __ashrdi3 (long A, int B)
 -- Runtime Function: long long __ashrti3 (long long A, int B)
     These functions return the result of arithmetically shifting A right by B bits.

 -- Runtime Function: int __divsi3 (int A, int B)
 -- Runtime Function: long __divdi3 (long A, long B)
 -- Runtime Function: long long __divti3 (long long A, long long B)
     These functions return the quotient of the signed division of A and B.

 -- Runtime Function: int __lshrsi3 (int A, int B)
 -- Runtime Function: long __lshrdi3 (long A, int B)
 -- Runtime Function: long long __lshrti3 (long long A, int B)
     These functions return the result of logically shifting A right by B bits.

 -- Runtime Function: int __modsi3 (int A, int B)
 -- Runtime Function: long __moddi3 (long A, long B)
 -- Runtime Function: long long __modti3 (long long A, long long B)
     These functions return the remainder of the signed division of A and B.

 -- Runtime Function: int __mulsi3 (int A, int B)
 -- Runtime Function: long __muldi3 (long A, long B)
 -- Runtime Function: long long __multi3 (long long A, long long B)
     These functions return the product of A and B.

 -- Runtime Function: long __negdi2 (long A)
 -- Runtime Function: long long __negti2 (long long A)
     These functions return the negation of A.

 -- Runtime Function: unsigned int __udivsi3 (unsigned int A, unsigned int B)
 -- Runtime Function: unsigned long __udivdi3 (unsigned long A, unsigned long B)
 -- Runtime Function: unsigned long long __udivti3 (unsigned long long A, unsigned long long B)
     These functions return the quotient of the unsigned division of A and B.

 -- Runtime Function: unsigned long __udivmoddi3 (unsigned long A, unsigned long B, unsigned long *C)
 -- Runtime Function: unsigned long long __udivti3 (unsigned long long A, unsigned long long B, unsigned long long *C)
     These functions calculate both the quotient and remainder of the unsigned division of A and B.  The return value is the quotient, and the remainder is placed in variable pointed to by C.

 -- Runtime Function: unsigned int __umodsi3 (unsigned int A, unsigned int B)
 -- Runtime Function: unsigned long __umoddi3 (unsigned long A, unsigned long B)
 -- Runtime Function: unsigned long long __umodti3 (unsigned long long A, unsigned long long B)
     These functions return the remainder of the unsigned division of A and B.

Comparison functions
--------------------

The following functions implement integral comparisons.  These functions implement a low-level compare, upon which the higher level comparison operators (such as less than and greater than or equal to) can be constructed.  The returned values lie in the range zero to two, to allow the high-level operators to be implemented by testing the returned result using either signed or unsigned comparison.

 -- Runtime Function: int __cmpdi2 (long A, long B)
 -- Runtime Function: int __cmpti2 (long long A, long long B)
     These functions perform a signed comparison of A and B.  If A is less than B, they return 0; if A is greater than B, they return 2; and if A and B are equal they return 1.

 -- Runtime Function: int __ucmpdi2 (unsigned long A, unsigned long B)
 -- Runtime Function: int __ucmpti2 (unsigned long long A, unsigned long long B)
     These functions perform an unsigned comparison of A and B. If A is less than B, they return 0; if A is greater than B, they return 2; and if A and B are equal they return 1.

Trapping arithmetic functions
-----------------------------

The following functions implement trapping arithmetic.  These functions call the libc function abort upon signed arithmetic overflow.

 -- Runtime Function: int __absvsi2 (int A)
 -- Runtime Function: long __absvdi2 (long A)
     These functions return the absolute value of A.

 -- Runtime Function: int __addvsi3 (int A, int B)
 -- Runtime Function: long __addvdi3 (long A, long B)
     These functions return the sum of A and B; that is A + B.

 -- Runtime Function: int __mulvsi3 (int A, int B)
 -- Runtime Function: long __mulvdi3 (long A, long B)
     The functions return the product of A and B; that is A * B.

 -- Runtime Function: int __negvsi2 (int A)
 -- Runtime Function: long __negvdi2 (long A)
     These functions return the negation of A; that is -A.

 -- Runtime Function: int __subvsi3 (int A, int B)
 -- Runtime Function: long __subvdi3 (long A, long B)
     These functions return the difference between B and A; that is A - B.

Bit operations
--------------

 -- Runtime Function: int __clzsi2 (int A)
 -- Runtime Function: int __clzdi2 (long A)
 -- Runtime Function: int __clzti2 (long long A)
     These functions return the number of leading 0-bits in A, starting at the most significant bit position.  If A is zero, the result is undefined.

 -- Runtime Function: int __ctzsi2 (int A)
 -- Runtime Function: int __ctzdi2 (long A)
 -- Runtime Function: int __ctzti2 (long long A)
     These functions return the number of trailing 0-bits in A, starting at the least significant bit position.  If A is zero, the result is undefined.

 -- Runtime Function: int __ffsdi2 (long A)
 -- Runtime Function: int __ffsti2 (long long A)
     These functions return the index of the least significant 1-bit in A, or the value zero if A is zero.  The least significant bit is index one.

 -- Runtime Function: int __paritysi2 (int A)
 -- Runtime Function: int __paritydi2 (long A)
 -- Runtime Function: int __parityti2 (long long A)
     These functions return the value zero if the number of bits set in A is even, and the value one otherwise.

 -- Runtime Function: int __popcountsi2 (int A)
 -- Runtime Function: int __popcountdi2 (long A)
 -- Runtime Function: int __popcountti2 (long long A)
     These functions return the number of bits set in A.

Routines for floating point emulation
=====================================

The software floating point library is used on machines which do not have hardware support for floating point.  It is also used whenever -msoft-float is used to disable generation of floating point instructions.  (Not all targets support this switch.)

For compatibility with other compilers, the floating point emulation routines can be renamed with the DECLARE_LIBRARY_RENAMES macro (see Library Calls).  In this section, the default names are used.

Presently the library does not support XFmode, which is used for long double on some architectures.

Arithmetic functions
--------------------

 -- Runtime Function: float __addsf3 (float A, float B)
 -- Runtime Function: double __adddf3 (double A, double B)
 -- Runtime Function: long double __addtf3 (long double A, long double B)
 -- Runtime Function: long double __addxf3 (long double A, long double B)
     These functions return the sum of A and B.

 -- Runtime Function: float __subsf3 (float A, float B)
 -- Runtime Function: double __subdf3 (double A, double B)
 -- Runtime Function: long double __subtf3 (long double A, long double B)
 -- Runtime Function: long double __subxf3 (long double A, long double B)
     These functions return the difference between B and A; that is, A - B.

 -- Runtime Function: float __mulsf3 (float A, float B)
 -- Runtime Function: double __muldf3 (double A, double B)
 -- Runtime Function: long double __multf3 (long double A, long double B)
 -- Runtime Function: long double __mulxf3 (long double A, long double B)
     These functions return the product of A and B.

 -- Runtime Function: float __divsf3 (float A, float B)
 -- Runtime Function: double __divdf3 (double A, double B)
 -- Runtime Function: long double __divtf3 (long double A, long double B)
 -- Runtime Function: long double __divxf3 (long double A, long double B)
     These functions return the quotient of A and B; that is, A / B.

 -- Runtime Function: float __negsf2 (float A)
 -- Runtime Function: double __negdf2 (double A)
 -- Runtime Function: long double __negtf2 (long double A)
 -- Runtime Function: long double __negxf2 (long double A)
     These functions return the negation of A.  They simply flip the sign bit, so they can produce negative zero and negative NaN.

Conversion functions
--------------------

 -- Runtime Function: double __extendsfdf2 (float A)
 -- Runtime Function: long double __extendsftf2 (float A)
 -- Runtime Function: long double __extendsfxf2 (float A)
 -- Runtime Function: long double __extenddftf2 (double A)
 -- Runtime Function: long double __extenddfxf2 (double A)
     These functions extend A to the wider mode of their return type.

 -- Runtime Function: double __truncxfdf2 (long double A)
 -- Runtime Function: double __trunctfdf2 (long double A)
 -- Runtime Function: float __truncxfsf2 (long double A)
 -- Runtime Function: float __trunctfsf2 (long double A)
 -- Runtime Function: float __truncdfsf2 (double A)
     These functions truncate A to the narrower mode of their return type, rounding toward zero.

 -- Runtime Function: int __fixsfsi (float A)
 -- Runtime Function: int __fixdfsi (double A)
 -- Runtime Function: int __fixtfsi (long double A)
 -- Runtime Function: int __fixxfsi (long double A)
     These functions convert A to a signed integer, rounding toward zero.

 -- Runtime Function: long __fixsfdi (float A)
 -- Runtime Function: long __fixdfdi (double A)
 -- Runtime Function: long __fixtfdi (long double A)
 -- Runtime Function: long __fixxfdi (long double A)
     These functions convert A to a signed long, rounding toward zero.

 -- Runtime Function: long long __fixsfti (float A)
 -- Runtime Function: long long __fixdfti (double A)
 -- Runtime Function: long long __fixtfti (long double A)
 -- Runtime Function: long long __fixxfti (long double A)
     These functions convert A to a signed long long, rounding toward zero.

 -- Runtime Function: unsigned int __fixunssfsi (float A)
 -- Runtime Function: unsigned int __fixunsdfsi (double A)
 -- Runtime Function: unsigned int __fixunstfsi (long double A)
 -- Runtime Function: unsigned int __fixunsxfsi (long double A)
     These functions convert A to an unsigned integer, rounding toward zero.  Negative values all become zero.

 -- Runtime Function: unsigned long __fixunssfdi (float A)
 -- Runtime Function: unsigned long __fixunsdfdi (double A)
 -- Runtime Function: unsigned long __fixunstfdi (long double A)
 -- Runtime Function: unsigned long __fixunsxfdi (long double A)
     These functions convert A to an unsigned long, rounding toward zero.  Negative values all become zero.

 -- Runtime Function: unsigned long long __fixunssfti (float A)
 -- Runtime Function: unsigned long long __fixunsdfti (double A)
 -- Runtime Function: unsigned long long __fixunstfti (long double A)
 -- Runtime Function: unsigned long long __fixunsxfti (long double A)
     These functions convert A to an unsigned long long, rounding toward zero.  Negative values all become zero.

 -- Runtime Function: float __floatsisf (int I)
 -- Runtime Function: double __floatsidf (int I)
 -- Runtime Function: long double __floatsitf (int I)
 -- Runtime Function: long double __floatsixf (int I)
     These functions convert I, a signed integer, to floating point.

 -- Runtime Function: float __floatdisf (long I)
 -- Runtime Function: double __floatdidf (long I)
 -- Runtime Function: long double __floatditf (long I)
 -- Runtime Function: long double __floatdixf (long I)
     These functions convert I, a signed long, to floating point.

 -- Runtime Function: float __floattisf (long long I)
 -- Runtime Function: double __floattidf (long long I)
 -- Runtime Function: long double __floattitf (long long I)
 -- Runtime Function: long double __floattixf (long long I)
     These functions convert I, a signed long long, to floating point.

Comparison functions
--------------------

There are two sets of basic comparison functions.

 -- Runtime Function: int __cmpsf2 (float A, float B)
 -- Runtime Function: int __cmpdf2 (double A, double B)
 -- Runtime Function: int __cmptf2 (long double A, long double B)
     These functions calculate a <=> b.  That is, if A is less than B, they return -1; if A is greater than B, they return 1; and if A and B are equal they return 0.  If either argument is NaN they return 1, but you should not rely on this; if NaN is a possibility, use one of the higher-level comparison functions.

 -- Runtime Function: int __unordsf2 (float A, float B)
 -- Runtime Function: int __unorddf2 (double A, double B)
 -- Runtime Function: int __unordtf2 (long double A, long double B)
     These functions return a nonzero value if either argument is NaN, otherwise 0.

There is also a complete group of higher level functions which correspond directly to comparison operators.  They implement the ISO C semantics for floating-point comparisons, taking NaN into account. Pay careful attention to the return values defined for each set. Under the hood, all of these routines are implemented as

       if (__unordXf2 (a, b))
         return E;
       return __cmpXf2 (a, b);

where E is a constant chosen to give the proper behavior for NaN.  Thus, the meaning of the return value is different for each set. Do not rely on this implementation; only the semantics documented below are guaranteed.

 -- Runtime Function: int __eqsf2 (float A, float B)
 -- Runtime Function: int __eqdf2 (double A, double B)
 -- Runtime Function: int __eqtf2 (long double A, long double B)
     These functions return zero if neither argument is NaN, and A and B are equal.

 -- Runtime Function: int __nesf2 (float A, float B)
 -- Runtime Function: int __nedf2 (double A, double B)
 -- Runtime Function: int __netf2 (long double A, long double B)
     These functions return a nonzero value if either argument is NaN, or if A and B are unequal.

 -- Runtime Function: int __gesf2 (float A, float B)
 -- Runtime Function: int __gedf2 (double A, double B)
 -- Runtime Function: int __getf2 (long double A, long double B)
     These functions return a value greater than or equal to zero if neither argument is NaN, and A is greater than or equal to B.

 -- Runtime Function: int __ltsf2 (float A, float B)
 -- Runtime Function: int __ltdf2 (double A, double B)
 -- Runtime Function: int __lttf2 (long double A, long double B)
     These functions return a value less than zero if neither argument is NaN, and A is strictly less than B.

 -- Runtime Function: int __lesf2 (float A, float B)
 -- Runtime Function: int __ledf2 (double A, double B)
 -- Runtime Function: int __letf2 (long double A, long double B)
     These functions return a value less than or equal to zero if neither argument is NaN, and A is less than or equal to B.

 -- Runtime Function: int __gtsf2 (float A, float B)
 -- Runtime Function: int __gtdf2 (double A, double B)
 -- Runtime Function: int __gttf2 (long double A, long double B)
     These functions return a value greater than zero if neither argument is NaN, and A is strictly greater than B.

Language-independent routines for exception handling
====================================================

document me!

       _Unwind_DeleteException
       _Unwind_Find_FDE
       _Unwind_ForcedUnwind
       _Unwind_GetGR
       _Unwind_GetIP
       _Unwind_GetLanguageSpecificData
       _Unwind_GetRegionStart
       _Unwind_GetTextRelBase
       _Unwind_GetDataRelBase
       _Unwind_RaiseException
       _Unwind_Resume
       _Unwind_SetGR
       _Unwind_SetIP
       _Unwind_FindEnclosingFunction
       _Unwind_SjLj_Register
       _Unwind_SjLj_Unregister
       _Unwind_SjLj_RaiseException
       _Unwind_SjLj_ForcedUnwind
       _Unwind_SjLj_Resume
       __deregister_frame
       __deregister_frame_info
       __deregister_frame_info_bases
       __register_frame
       __register_frame_info
       __register_frame_info_bases
       __register_frame_info_table
       __register_frame_info_table_bases
       __register_frame_table

Miscellaneous runtime library routines
======================================

Cache control functions
-----------------------

 -- Runtime Function: void __clear_cache (char *BEG, char *END)
     This function clears the instruction cache between BEG and END.