OSDN Git Service

* printf/quadmath-printf.c: Also check __GLIBC__ when checking
[pf3gnuchains/gcc-fork.git] / libquadmath / libquadmath.texi
1 \input texinfo @c -*-texinfo-*-
2
3 @c %**start of header
4 @setfilename libquadmath.info
5 @settitle GCC libquadmath
6 @c %**end of header
7
8 @copying
9 Copyright @copyright{} 2010 Free Software Foundation, Inc.
10
11 @quotation
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.2 or
14 any later version published by the Free Software Foundation; with no
15 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
16 and with the Back-Cover Texts as in (a) below.  A copy of the
17 license is included in the section entitled ``GNU Free Documentation
18 License.''
19
20 (a) The FSF's Back-Cover Text is: ``You have the freedom to
21 copy and modify this GNU manual.
22 @end quotation
23 @end copying
24
25 @ifinfo
26 @dircategory GNU Libraries
27 @direntry
28 * libquadmath: (libquadmath).                  GCC Quad-Precision Math Library
29 @end direntry
30
31 This manual documents the GCC Quad-Precision Math Library API.
32
33 Published by the Free Software Foundation
34 51 Franklin Street, Fifth Floor
35 Boston, MA 02110-1301 USA
36
37 @insertcopying
38 @end ifinfo
39
40
41 @setchapternewpage odd
42
43 @titlepage
44 @title The GCC Quad-Precision Math Library
45 @page
46 @vskip 0pt plus 1filll
47 @comment For the @value{version-GCC} Version*
48 @sp 1
49 Published by the Free Software Foundation @*
50 51 Franklin Street, Fifth Floor@*
51 Boston, MA 02110-1301, USA@*
52 @sp 1
53 @insertcopying
54 @end titlepage
55
56 @summarycontents
57 @contents
58 @page
59
60
61 @node Top
62 @top Introduction
63 @cindex Introduction
64
65 This manual documents the usage of libquadmath, the GCC Quad-Precision
66 Math Library Application Programming Interface (API).
67
68
69 @comment
70 @comment  When you add a new menu item, please keep the right hand
71 @comment  aligned to the same column.  Do not use tabs.  This provides
72 @comment  better formatting.
73 @comment
74 @menu
75 * Typedef and constants::      Defined data types and constants
76 * Math Library Routines::      The Libquadmath math runtime application
77                                programming interface.
78 * I/O Library Routines::       The Libquadmath I/O runtime application
79                                programming interface.
80 * GNU Free Documentation License::
81                                How you can copy and share this manual.
82 * Reporting Bugs::             How to report bugs in GCC Libquadmath.
83 @c * Index::                      Index of this documentation.
84 @end menu
85
86
87 @c ---------------------------------------------------------------------
88 @c Defined macros
89 @c ---------------------------------------------------------------------
90
91 @node Typedef and constants
92 @chapter Typedef and constants
93
94 The following data type has been defined via @code{typedef}.
95
96 @table @asis
97 @item @code{__complex128}: @code{__float128}-based complex number
98 @end table
99
100 The following macros are defined, which give the numeric limits of the
101 @code{__float128} data type.
102
103 @table @asis
104 @item @code{FLT128_MAX}: largest finite number
105 @item @code{FLT128_MIN}: smallest positive number with full precision
106 @item @code{FLT128_EPSILON}: difference between 1 and the next larger
107                              representable number
108 @item @code{FLT128_DENORM_MIN}: smallest positive denormalized number
109 @item @code{FLT128_MANT_DIG}: number of digits in the mantissa (bit precision)
110 @item @code{FLT128_MIN_EXP}: maximal negative exponent
111 @item @code{FLT128_MAX_EXP}: maximal positive exponent
112 @end table
113
114 The following mathematical constants of type @code{__float128} are defined.
115
116 @table @asis
117 @item @code{M_Eq}: the constant e (Euler's number)
118 @item @code{M_LOG2Eq}: binary logarithm of 2
119 @item @code{M_LOG10Eq}: common, decimal logarithm of 2
120 @item @code{M_LN2q}: natural logarithm of 2
121 @item @code{M_LN10q}: natural logarithm of 10
122 @item @code{M_PIq}: pi
123 @item @code{M_PI_2q}: two pi
124 @item @code{M_PI_4q}: four pi
125 @item @code{M_1_PIq}: one over pi
126 @item @code{M_2_PIq}: one over two pi
127 @item @code{M_2_SQRTPIq}: two over square root of pi
128 @item @code{M_SQRT2q}: square root of 2
129 @item @code{M_SQRT1_2q}: one over square root of 2
130 @end table
131
132
133 @c ---------------------------------------------------------------------
134 @c Math routines
135 @c ---------------------------------------------------------------------
136
137 @node Math Library Routines
138 @chapter Math Library Routines
139
140 The following mathematical functions are available:
141
142 @table @asis
143 @item @code{acosq}: arc cosine function
144 @item @code{acoshq}: inverse hyperbolic cosine function
145 @item @code{asinq}: arc sine function
146 @item @code{asinhq}: inverse hyperbolic sine function
147 @item @code{atanq}: arc tangent function
148 @item @code{atanhq}: inverse hyperbolic tangent function
149 @item @code{atan2q}: arc tangent function
150 @item @code{cbrtq}: cube root function
151 @item @code{ceilq}: ceiling value function
152 @item @code{copysignq}: copy sign of a number
153 @item @code{coshq}: hyperbolic cosine function
154 @item @code{cosq}: cosine function
155 @item @code{erfq}: error function
156 @item @code{erfcq}: complementary error function
157 @item @code{expq}: exponential function
158 @item @code{expm1q}: exponential minus 1 function
159 @need 800
160 @item @code{fabsq}: absolute value function
161 @item @code{fdimq}: positive difference function
162 @item @code{finiteq}: check finiteness of value
163 @item @code{floorq}: floor value function
164 @item @code{fmaq}: fused multiply and add
165 @item @code{fmaxq}: determine maximum of two values
166 @item @code{fminq}: determine minimum of two values
167 @item @code{fmodq}: remainder value function
168 @item @code{frexpq}: extract mantissa and exponent
169 @item @code{hypotq}: Eucledian distance function
170 @item @code{ilogbq}: get exponent of the value
171 @item @code{isinfq}: check for infinity
172 @item @code{isnanq}: check for not a number
173 @item @code{j0q}: Bessel function of the first kind, first order
174 @item @code{j1q}: Bessel function of the first kind, second order
175 @item @code{jnq}: Bessel function of the first kind, @var{n}-th order
176 @item @code{ldexpq}: load exponent of the value
177 @item @code{lgammaq}: logarithmic gamma function
178 @item @code{llrintq}: round to nearest integer value
179 @item @code{llroundq}: round to nearest integer value away from zero
180 @item @code{logq}: natural logarithm function
181 @item @code{log10q}: base 10 logarithm function
182 @item @code{log1pq}: compute natural logarithm of the value plus one
183 @item @code{log2q}: base 2 logarithm function
184 @need 800
185 @item @code{lrintq}: round to nearest integer value
186 @item @code{lroundq}: round to nearest integer value away from zero
187 @item @code{modfq}: decompose the floating-point number
188 @item @code{nanq}: return quiet NaN
189 @item @code{nearbyintq}: round to nearest integer
190 @item @code{nextafterq}: next representable floating-point number
191 @item @code{powq}: power function
192 @item @code{remainderq}: remainder function
193 @item @code{remquoq}: remainder and part of quotient
194 @item @code{rintq}: round-to-nearest integral value
195 @item @code{roundq}: round-to-nearest integral value, return @code{__float128}
196 @item @code{scalblnq}: compute exponent using @code{FLT_RADIX}
197 @item @code{scalbnq}: compute exponent using @code{FLT_RADIX}
198 @item @code{signbitq}: return sign bit
199 @item @code{sincosq}: calculate sine and cosine simulataneously
200 @item @code{sinhq}: hyperbolic sine function
201 @item @code{sinq}: sine function
202 @item @code{sqrtq}: square root function
203 @item @code{tanq}: tangent function
204 @item @code{tanhq}: hyperbolic tangent function
205 @need 800
206 @item @code{tgammaq}: true gamma function
207 @item @code{truncq}: round to integer, towards zero
208 @item @code{y0q}: Bessel function of the second kind, first order
209 @item @code{y1q}: Bessel function of the second kind, second order
210 @item @code{ynq}: Bessel function of the second kind, @var{n}-th order
211 @item @code{cabsq} complex absolute value function
212 @item @code{cargq}: calculate the argument
213 @item @code{cimagq} imaginary part of complex number
214 @item @code{crealq}: real part of complex number
215 @item @code{cacoshq}: complex arc hyperbolic cosine function
216 @item @code{cacosq}: complex arc cosine function
217 @item @code{casinhq}: complex arc hyperbolic sine function
218 @item @code{casinq}: complex arc sine function
219 @item @code{catanhq}: complex arc hyperbolic tangent function
220 @item @code{catanq}: complex arc tangent function
221 @item @code{ccosq} complex cosine function:
222 @item @code{ccoshq}: complex hyperbolic cosine function
223 @item @code{cexpq}: complex exponential function
224 @need 800
225 @item @code{cexpiq}: computes the exponential function of ``i'' times a
226                      real value
227 @item @code{clogq}: complex natural logarithm
228 @item @code{clog10q}: complex base 10 logarithm
229 @item @code{conjq}: complex conjugate function
230 @item @code{cpowq}: complex power function
231 @item @code{cprojq}: project into Riemann Sphere
232 @item @code{csinq}: complex sine function
233 @item @code{csinhq}: complex hyperbolic sine function
234 @item @code{csqrtq}: complex square root
235 @item @code{ctanq}: complex tangent function
236 @item @code{ctanhq}: complex hyperbolic tangent function
237 @end table
238
239
240 @c ---------------------------------------------------------------------
241 @c I/O routines
242 @c ---------------------------------------------------------------------
243
244 @node I/O Library Routines
245 @chapter I/O Library Routines
246
247 @menu
248 * @code{strtoflt128}:          strtoflt128,          Convert from string
249 * @code{quadmath_snprintf}:    quadmath_snprintf,    Convert to string
250 @end menu
251
252
253 @node strtoflt128
254 @section @code{strtoflt128} --- Convert from string
255
256 The function @code{dmath_strtopQ} converts a string into a
257 @code{__float128} number.
258
259 @table @asis
260 @item Syntax
261 @code{__float128 strtoflt128 (const char *s, char **sp)}
262
263 @c The return values are defined in gdtoa/gdtoa.h STRTOG_*
264 @c However, the values are currently not exported - thus we
265 @c do not define them here, either.
266
267 @item @emph{Arguments}:
268 @multitable @columnfractions .15 .70
269 @item @var{s}  @tab input string
270 @item @var{sp} @tab the address of the next character in the string
271 @end multitable
272
273 The argument @var{sp} contains, if not @code{NULL}, the address of the
274 next character following the parts of the string, which have been read.
275
276 @item Example
277 @smallexample
278 #include <quadmath.h>
279
280 int main ()
281 @{
282   __float128 r;
283
284   r = strtoflt128 ("1.2345678", NULL);
285
286   return 0;
287 @}
288 @end smallexample
289 @end table
290
291
292 @node quadmath_snprintf
293 @section @code{quadmath_snprintf} --- Convert to string
294
295 The function @code{quadmath_snprintf} converts a @code{__float128} floating-point
296 number into a string.  It is a specialized alternative to @code{snprintf}, where
297 the format string is restricted to a single conversion specifier with @code{Q}
298 modifier and conversion specifier @code{e}, @code{E}, @code{f}, @code{F}, @code{g},
299 @code{G}, @code{a} or @code{A}, with no extra characters before or after the
300 conversion specifier.  The @code{%m$} or @code{*m$} style must not be used in
301 the format.
302
303 @table @asis
304 @item Syntax
305 @code{int quadmath_snprintf (char *s, size_t size, const char *format, ...)}
306
307 @item @emph{Arguments}:
308 @multitable @columnfractions .15 .70
309 @item @var{s}    @tab output string
310 @item @var{size} @tab byte size of the string, including tailing NUL
311 @item @var{format} @tab conversion specifier string
312 @end multitable
313
314 @item Example
315 @smallexample
316 #include <quadmath.h>
317 #include <stdlib.h>
318 #include <stdio.h>
319
320 int main ()
321 @{
322   __float128 r;
323   int prec = 20;
324   int width = 46;
325   char buf[128];
326
327   r = 2.0q;
328   r = sqrtq (r);
329   int n = quadmath_snprintf (buf, sizeof buf, "%+-#*.20Qe", width, r);
330   if ((size_t) n < sizeof buf)
331     printf ("%s\n", buf);
332     /* Prints: +1.41421356237309504880e+00 */
333   quadmath_snprintf (buf, sizeof buf, "%Qa", r);
334   if ((size_t) n < sizeof buf)
335     printf ("%s\n", buf);
336     /* Prints: 0x1.6a09e667f3bcc908b2fb1366ea96p+0 */
337   n = quadmath_snprintf (NULL, 0, "%+-#46.*Qe", prec, r);
338   if (n > -1)
339     @{
340       char *str = malloc (n + 1);
341       if (str)
342         @{
343           quadmath_snprintf (str, n + 1, "%+-#46.*Qe", prec, r);
344           printf ("%s\n", str);
345           /* Prints: +1.41421356237309504880e+00 */
346         @}
347       free (str);
348     @}
349   return 0;
350 @}
351 @end smallexample
352
353 @end table
354
355 On some targets when supported by the C library hooks are installed
356 for @code{printf} family of functions, so that @code{printf ("%Qe", 1.2Q);}
357 etc.@: works too.
358
359
360 @c ---------------------------------------------------------------------
361 @c GNU Free Documentation License
362 @c ---------------------------------------------------------------------
363
364 @include fdl.texi
365
366 @c ---------------------------------------------------------------------
367 @c Reporting Bugs
368 @c ---------------------------------------------------------------------
369
370 @c For BUGURL
371 @include libquadmath-vers.texi
372
373 @node Reporting Bugs
374 @chapter Reporting Bugs
375
376 Bugs in the GCC Quad-Precision Math Library implementation should be
377 reported via @value{BUGURL}.
378
379
380 @c ---------------------------------------------------------------------
381 @c Index
382 @c ---------------------------------------------------------------------
383
384 @c @node Index
385 @c @unnumbered Index
386 @c 
387 @c @printindex cp
388
389 @bye