1 @c Copyright (C) 2003 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>
7 @chapter The GCC low-level runtime library
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.
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.
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
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)}.
30 * Integer library routines::
31 * Soft float library routines::
32 * Exception handling routines::
33 * Miscellaneous routines::
36 @node Integer library routines
37 @section Routines for integer arithmetic
132 @node Soft float library routines
133 @section Routines for floating point emulation
134 @cindex soft float library
135 @cindex arithmetic library
139 The software floating point library is used on machines which do not
140 have hardware support for floating point. It is also used whenever
141 @option{-msoft-float} is used to disable generation of floating point
142 instructions. (Not all targets support this switch.)
144 For compatibility with other compilers, the floating point emulation
145 routines can be renamed with the @code{DECLARE_LIBRARY_RENAMES} macro
146 (@pxref{Library Calls}). In this section, the default names are used.
148 These routines take arguments and return values of a specific machine
149 mode, not a specific C type. @xref{Machine Modes}, for an explanation
150 of this concept. For illustrative purposes, in this section
151 @code{float} is assumed to correspond to @code{SFmode}; @code{double}
152 to @code{DFmode}; @code{@w{long double}} to @code{TFmode}; and
153 @code{int} to @code{SImode}. This is a common mapping, but not the
156 Presently the library does not support @code{XFmode}, which is used
157 for @code{long double} on some architectures.
159 @subsection Arithmetic functions
161 @deftypefn {Runtime Function} float __addsf3 (float @var{a}, float @var{b})
162 @deftypefnx {Runtime Function} double __adddf3 (double @var{a}, double @var{b})
163 @deftypefnx {Runtime Function} {long double} __addtf3 (long double @var{a}, long double @var{b})
164 These functions return the sum of @var{a} and @var{b}.
167 @deftypefn {Runtime Function} float __subsf3 (float @var{a}, float @var{b})
168 @deftypefnx {Runtime Function} double __subdf3 (double @var{a}, double @var{b})
169 @deftypefnx {Runtime Function} {long double} __subtf3 (long double @var{a}, long double @var{b})
170 These functions return the difference between @var{b} and @var{a};
171 that is, @w{@math{@var{a} - @var{b}}}.
174 @deftypefn {Runtime Function} float __mulsf3 (float @var{a}, float @var{b})
175 @deftypefnx {Runtime Function} double __muldf3 (double @var{a}, double @var{b})
176 @deftypefnx {Runtime Function} {long double} __multf3 (long double @var{a}, long double @var{b})
177 These functions return the product of @var{a} and @var{b}.
180 @deftypefn {Runtime Function} float __divsf3 (float @var{a}, float @var{b})
181 @deftypefnx {Runtime Function} double __divdf3 (double @var{a}, double @var{b})
182 @deftypefnx {Runtime Function} {long double} __divtf3 (long double @var{a}, long double @var{b})
183 These functions return the quotient of @var{a} and @var{b}; that is,
184 @w{@math{@var{a} / @var{b}}}.
187 @deftypefn {Runtime Function} float __negsf2 (float @var{a})
188 @deftypefnx {Runtime Function} double __negdf2 (double @var{a})
189 @deftypefnx {Runtime Function} {long double} __negtf2 (long double @var{a})
190 These functions return the negation of @var{a}. They simply flip the
191 sign bit, so they can produce negative zero and negative NaN.
194 @subsection Conversion functions
196 @deftypefn {Runtime Function} double __extendsfdf2 (float @var{a})
197 @deftypefnx {Runtime Function} {long double} __extendsftf2 (float @var{a})
198 @deftypefnx {Runtime Function} {long double} __extenddftf2 (double @var{a})
199 These functions extend @var{a} to the wider mode of their return
203 @deftypefn {Runtime Function} double __trunctfdf2 (long double @var{a})
204 @deftypefnx {Runtime Function} float __trunctfsf2 (long double @var{a})
205 @deftypefnx {Runtime Function} float __truncdfsf2 (double @var{a})
206 These functions truncate @var{a} to the narrower mode of their return
207 type, rounding toward zero.
210 @deftypefn {Runtime Function} int __fixsfsi (float @var{a})
211 @deftypefnx {Runtime Function} int __fixdfsi (double @var{a})
212 @deftypefnx {Runtime Function} int __fixtfsi (long double @var{a})
213 These functions convert @var{a} to a signed integer, rounding toward zero.
216 @deftypefn {Runtime Function} {unsigned int} __fixunssfsi (float @var{a})
217 @deftypefnx {Runtime Function} {unsigned int} __fixunsdfsi (double @var{a})
218 @deftypefnx {Runtime Function} {unsigned int} __fixunstfsi (long double @var{a})
219 These functions convert @var{a} to an unsigned integer, rounding
220 toward zero. Negative values all become zero.
223 @deftypefn {Runtime Function} float __floatsisf (int @var{i})
224 @deftypefnx {Runtime Function} double __floatsidf (int @var{i})
225 @deftypefnx {Runtime Function} {long double} __floatsitf (int @var{i})
226 These functions convert @var{i}, a signed integer, to floating point.
229 @deftypefn {Runtime Function} float __floatunsisf (unsigned int @var{n})
230 @deftypefnx {Runtime Function} double __floatunsidf (unsigned int @var{n})
231 @deftypefnx {Runtime Function} {long double} __floatunsitf (unsigned int @var{n})
232 These functions convert @var{n}, an unsigned integer, to floating point.
235 There are no functions to convert @code{DImode} integers to or from
236 floating point; this reflects the fact that such conversions are rare,
237 and processors with native 64-bit arithmetic tend to have hardware
238 floating point support. If such routines ever get added, they will be
239 named @code{__fixsfdi}, @code{__floatdisf}, and so on.
241 @subsection Comparison functions
243 There are two sets of basic comparison functions.
245 @deftypefn {Runtime Function} int __cmpsf2 (float @var{a}, float @var{b})
246 @deftypefnx {Runtime Function} int __cmpdf2 (double @var{a}, double @var{b})
247 @deftypefnx {Runtime Function} int __cmptf2 (long double @var{a}, long double @var{b})
248 These functions calculate @math{a <=> b}. That is, if @var{a} is less
249 than @var{b}, they return -1; if @var{a} is greater than @var{b}, they
250 return 1; and if @var{a} and @var{b} are equal they return 0. If
251 either argument is NaN they return 1, but you should not rely on this;
252 if NaN is a possibility, use one of the higher-level comparison
256 @deftypefn {Runtime Function} int __unordsf2 (float @var{a}, float @var{b})
257 @deftypefnx {Runtime Function} int __unorddf2 (double @var{a}, double @var{b})
258 @deftypefnx {Runtime Function} int __unordtf2 (long double @var{a}, long double @var{b})
259 These functions return a nonzero value if either argument is NaN, otherwise 0.
262 There is also a complete group of higher level functions which
263 correspond directly to comparison operators. They implement the ISO C
264 semantics for floating-point comparisons, taking NaN into account.
265 Pay careful attention to the return values defined for each set.
266 Under the hood, all of these routines are implemented as
269 if (__unord@var{X}f2 (a, b))
271 return __cmp@var{X}f2 (a, b);
275 where @var{E} is a constant chosen to give the proper behavior for
276 NaN. Thus, the meaning of the return value is different for each set.
277 Do not rely on this implementation; only the semantics documented
278 below are guaranteed.
280 @deftypefn {Runtime Function} int __eqsf2 (float @var{a}, float @var{b})
281 @deftypefnx {Runtime Function} int __eqdf2 (double @var{a}, double @var{b})
282 @deftypefnx {Runtime Function} int __eqtf2 (long double @var{a}, long double @var{b})
283 These functions return zero if neither argument is NaN, and @var{a} and
287 @deftypefn {Runtime Function} int __nesf2 (float @var{a}, float @var{b})
288 @deftypefnx {Runtime Function} int __nedf2 (double @var{a}, double @var{b})
289 @deftypefnx {Runtime Function} int __netf2 (long double @var{a}, long double @var{b})
290 These functions return a nonzero value if either argument is NaN, or
291 if @var{a} and @var{b} are unequal.
294 @deftypefn {Runtime Function} int __gesf2 (float @var{a}, float @var{b})
295 @deftypefnx {Runtime Function} int __gedf2 (double @var{a}, double @var{b})
296 @deftypefnx {Runtime Function} int __getf2 (long double @var{a}, long double @var{b})
297 These functions return a value greater than or equal to zero if
298 neither argument is NaN, and @var{a} is greater than or equal to
302 @deftypefn {Runtime Function} int __ltsf2 (float @var{a}, float @var{b})
303 @deftypefnx {Runtime Function} int __ltdf2 (double @var{a}, double @var{b})
304 @deftypefnx {Runtime Function} int __lttf2 (long double @var{a}, long double @var{b})
305 These functions return a value less than zero if neither argument is
306 NaN, and @var{a} is strictly less than @var{b}.
309 @deftypefn {Runtime Function} int __lesf2 (float @var{a}, float @var{b})
310 @deftypefnx {Runtime Function} int __ledf2 (double @var{a}, double @var{b})
311 @deftypefnx {Runtime Function} int __letf2 (long double @var{a}, long double @var{b})
312 These functions return a value less than or equal to zero if neither
313 argument is NaN, and @var{a} is less than or equal to @var{b}.
316 @deftypefn {Runtime Function} int __gtsf2 (float @var{a}, float @var{b})
317 @deftypefnx {Runtime Function} int __gtdf2 (double @var{a}, double @var{b})
318 @deftypefnx {Runtime Function} int __gttf2 (long double @var{a}, long double @var{b})
319 These functions return a value greater than zero if neither argument
320 is NaN, and @var{a} is strictly greater than @var{b}.
323 @node Exception handling routines
324 @section Language-independent routines for exception handling
329 _Unwind_DeleteException
334 _Unwind_GetLanguageSpecificData
335 _Unwind_GetRegionStart
336 _Unwind_GetTextRelBase
337 _Unwind_GetDataRelBase
338 _Unwind_RaiseException
342 _Unwind_FindEnclosingFunction
343 _Unwind_SjLj_Register
344 _Unwind_SjLj_Unregister
345 _Unwind_SjLj_RaiseException
346 _Unwind_SjLj_ForcedUnwind
349 __deregister_frame_info
350 __deregister_frame_info_bases
352 __register_frame_info
353 __register_frame_info_bases
354 __register_frame_info_table
355 __register_frame_info_table_bases
356 __register_frame_table
359 @node Miscellaneous routines
360 @section Miscellaneous runtime library routines