]>
Commit | Line | Data |
---|---|---|
55c14926 | 1 | @c We need some definitions here. |
7a68c94a | 2 | @ifclear mult |
55c14926 | 3 | @ifhtml |
7a68c94a UD |
4 | @set mult · |
5 | @set infty ∞ | |
6 | @set pie π | |
55c14926 | 7 | @end ifhtml |
ca34d7a7 | 8 | @iftex |
838e5ffe | 9 | @set mult @cdot |
7a68c94a | 10 | @set infty @infty |
ca34d7a7 | 11 | @end iftex |
838e5ffe | 12 | @ifclear mult |
7a68c94a UD |
13 | @set mult * |
14 | @set infty oo | |
15 | @set pie pi | |
838e5ffe | 16 | @end ifclear |
fe0ec73e | 17 | @macro mul |
838e5ffe | 18 | @value{mult} |
fe0ec73e | 19 | @end macro |
ca34d7a7 UD |
20 | @macro infinity |
21 | @value{infty} | |
22 | @end macro | |
7a68c94a UD |
23 | @ifnottex |
24 | @macro pi | |
25 | @value{pie} | |
26 | @end macro | |
27 | @end ifnottex | |
28 | @end ifclear | |
55c14926 | 29 | |
28f540f4 | 30 | @node Mathematics, Arithmetic, Low-Level Terminal Interface, Top |
7a68c94a | 31 | @c %MENU% Math functions, useful constants, random numbers |
28f540f4 RM |
32 | @chapter Mathematics |
33 | ||
34 | This chapter contains information about functions for performing | |
35 | mathematical computations, such as trigonometric functions. Most of | |
36 | these functions have prototypes declared in the header file | |
7a68c94a UD |
37 | @file{math.h}. The complex-valued functions are defined in |
38 | @file{complex.h}. | |
28f540f4 | 39 | @pindex math.h |
7a68c94a UD |
40 | @pindex complex.h |
41 | ||
42 | All mathematical functions which take a floating-point argument | |
43 | have three variants, one each for @code{double}, @code{float}, and | |
44 | @code{long double} arguments. The @code{double} versions are mostly | |
45 | defined in @w{ISO C 89}. The @code{float} and @code{long double} | |
46 | versions are from the numeric extensions to C included in @w{ISO C 9X}. | |
47 | ||
48 | Which of the three versions of a function should be used depends on the | |
49 | situation. For most calculations, the @code{float} functions are the | |
50 | fastest. On the other hand, the @code{long double} functions have the | |
51 | highest precision. @code{double} is somewhere in between. It is | |
04b9968b | 52 | usually wise to pick the narrowest type that can accommodate your data. |
7a68c94a UD |
53 | Not all machines have a distinct @code{long double} type; it may be the |
54 | same as @code{double}. | |
28f540f4 RM |
55 | |
56 | @menu | |
7a68c94a UD |
57 | * Mathematical Constants:: Precise numeric values for often-used |
58 | constants. | |
59 | * Trig Functions:: Sine, cosine, tangent, and friends. | |
60 | * Inverse Trig Functions:: Arcsine, arccosine, etc. | |
61 | * Exponents and Logarithms:: Also pow and sqrt. | |
62 | * Hyperbolic Functions:: sinh, cosh, tanh, etc. | |
63 | * Special Functions:: Bessel, gamma, erf. | |
64 | * Pseudo-Random Numbers:: Functions for generating pseudo-random | |
65 | numbers. | |
66 | * FP Function Optimizations:: Fast code or small code. | |
28f540f4 RM |
67 | @end menu |
68 | ||
55c14926 UD |
69 | @node Mathematical Constants |
70 | @section Predefined Mathematical Constants | |
71 | @cindex constants | |
72 | @cindex mathematical constants | |
73 | ||
7a68c94a UD |
74 | The header @file{math.h} defines several useful mathematical constants. |
75 | All values are defined as preprocessor macros starting with @code{M_}. | |
76 | The values provided are: | |
55c14926 UD |
77 | |
78 | @vtable @code | |
79 | @item M_E | |
7a68c94a | 80 | The base of natural logarithms. |
55c14926 | 81 | @item M_LOG2E |
7a68c94a | 82 | The logarithm to base @code{2} of @code{M_E}. |
55c14926 | 83 | @item M_LOG10E |
7a68c94a | 84 | The logarithm to base @code{10} of @code{M_E}. |
55c14926 | 85 | @item M_LN2 |
7a68c94a | 86 | The natural logarithm of @code{2}. |
55c14926 | 87 | @item M_LN10 |
7a68c94a | 88 | The natural logarithm of @code{10}. |
55c14926 | 89 | @item M_PI |
04b9968b | 90 | Pi, the ratio of a circle's circumference to its diameter. |
55c14926 | 91 | @item M_PI_2 |
7a68c94a | 92 | Pi divided by two. |
55c14926 | 93 | @item M_PI_4 |
7a68c94a | 94 | Pi divided by four. |
55c14926 | 95 | @item M_1_PI |
7a68c94a | 96 | The reciprocal of pi (1/pi) |
55c14926 | 97 | @item M_2_PI |
7a68c94a | 98 | Two times the reciprocal of pi. |
55c14926 | 99 | @item M_2_SQRTPI |
7a68c94a | 100 | Two times the reciprocal of the square root of pi. |
55c14926 | 101 | @item M_SQRT2 |
7a68c94a | 102 | The square root of two. |
55c14926 | 103 | @item M_SQRT1_2 |
7a68c94a | 104 | The reciprocal of the square root of two (also the square root of 1/2). |
55c14926 UD |
105 | @end vtable |
106 | ||
7a68c94a | 107 | These constants come from the Unix98 standard and were also available in |
04b9968b | 108 | 4.4BSD; therefore they are only defined if @code{_BSD_SOURCE} or |
7a68c94a UD |
109 | @code{_XOPEN_SOURCE=500}, or a more general feature select macro, is |
110 | defined. The default set of features includes these constants. | |
111 | @xref{Feature Test Macros}. | |
112 | ||
113 | All values are of type @code{double}. As an extension, the GNU C | |
114 | library also defines these constants with type @code{long double}. The | |
115 | @code{long double} macros have a lowercase @samp{l} appended to their | |
116 | names: @code{M_El}, @code{M_PIl}, and so forth. These are only | |
117 | available if @code{_GNU_SOURCE} is defined. | |
55c14926 UD |
118 | |
119 | @vindex PI | |
120 | @emph{Note:} Some programs use a constant named @code{PI} which has the | |
7a68c94a UD |
121 | same value as @code{M_PI}. This constant is not standard; it may have |
122 | appeared in some old AT&T headers, and is mentioned in Stroustrup's book | |
123 | on C++. It infringes on the user's name space, so the GNU C library | |
124 | does not define it. Fixing programs written to expect it is simple: | |
125 | replace @code{PI} with @code{M_PI} throughout, or put @samp{-DPI=M_PI} | |
126 | on the compiler command line. | |
61eb22d3 | 127 | |
28f540f4 RM |
128 | @node Trig Functions |
129 | @section Trigonometric Functions | |
130 | @cindex trigonometric functions | |
131 | ||
132 | These are the familiar @code{sin}, @code{cos}, and @code{tan} functions. | |
133 | The arguments to all of these functions are in units of radians; recall | |
134 | that pi radians equals 180 degrees. | |
135 | ||
136 | @cindex pi (trigonometric constant) | |
7a68c94a UD |
137 | The math library normally defines @code{M_PI} to a @code{double} |
138 | approximation of pi. If strict ISO and/or POSIX compliance | |
139 | are requested this constant is not defined, but you can easily define it | |
140 | yourself: | |
28f540f4 RM |
141 | |
142 | @smallexample | |
b4012b75 | 143 | #define M_PI 3.14159265358979323846264338327 |
28f540f4 RM |
144 | @end smallexample |
145 | ||
146 | @noindent | |
147 | You can also compute the value of pi with the expression @code{acos | |
148 | (-1.0)}. | |
149 | ||
28f540f4 | 150 | @comment math.h |
f65fd747 | 151 | @comment ISO |
28f540f4 | 152 | @deftypefun double sin (double @var{x}) |
4260bc74 UD |
153 | @comment math.h |
154 | @comment ISO | |
779ae82e | 155 | @deftypefunx float sinf (float @var{x}) |
4260bc74 UD |
156 | @comment math.h |
157 | @comment ISO | |
779ae82e | 158 | @deftypefunx {long double} sinl (long double @var{x}) |
b4012b75 | 159 | These functions return the sine of @var{x}, where @var{x} is given in |
28f540f4 RM |
160 | radians. The return value is in the range @code{-1} to @code{1}. |
161 | @end deftypefun | |
162 | ||
163 | @comment math.h | |
f65fd747 | 164 | @comment ISO |
28f540f4 | 165 | @deftypefun double cos (double @var{x}) |
4260bc74 UD |
166 | @comment math.h |
167 | @comment ISO | |
779ae82e | 168 | @deftypefunx float cosf (float @var{x}) |
4260bc74 UD |
169 | @comment math.h |
170 | @comment ISO | |
779ae82e | 171 | @deftypefunx {long double} cosl (long double @var{x}) |
b4012b75 | 172 | These functions return the cosine of @var{x}, where @var{x} is given in |
28f540f4 RM |
173 | radians. The return value is in the range @code{-1} to @code{1}. |
174 | @end deftypefun | |
175 | ||
176 | @comment math.h | |
f65fd747 | 177 | @comment ISO |
28f540f4 | 178 | @deftypefun double tan (double @var{x}) |
4260bc74 UD |
179 | @comment math.h |
180 | @comment ISO | |
779ae82e | 181 | @deftypefunx float tanf (float @var{x}) |
4260bc74 UD |
182 | @comment math.h |
183 | @comment ISO | |
779ae82e | 184 | @deftypefunx {long double} tanl (long double @var{x}) |
b4012b75 | 185 | These functions return the tangent of @var{x}, where @var{x} is given in |
28f540f4 RM |
186 | radians. |
187 | ||
28f540f4 RM |
188 | Mathematically, the tangent function has singularities at odd multiples |
189 | of pi/2. If the argument @var{x} is too close to one of these | |
7a68c94a | 190 | singularities, @code{tan} will signal overflow. |
28f540f4 RM |
191 | @end deftypefun |
192 | ||
7a68c94a UD |
193 | In many applications where @code{sin} and @code{cos} are used, the sine |
194 | and cosine of the same angle are needed at the same time. It is more | |
195 | efficient to compute them simultaneously, so the library provides a | |
196 | function to do that. | |
b4012b75 UD |
197 | |
198 | @comment math.h | |
199 | @comment GNU | |
200 | @deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx}) | |
4260bc74 UD |
201 | @comment math.h |
202 | @comment GNU | |
779ae82e | 203 | @deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx}) |
4260bc74 UD |
204 | @comment math.h |
205 | @comment GNU | |
779ae82e | 206 | @deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx}) |
b4012b75 UD |
207 | These functions return the sine of @var{x} in @code{*@var{sinx}} and the |
208 | cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in | |
209 | radians. Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in | |
210 | the range of @code{-1} to @code{1}. | |
ca34d7a7 | 211 | |
7a68c94a UD |
212 | This function is a GNU extension. Portable programs should be prepared |
213 | to cope with its absence. | |
b4012b75 UD |
214 | @end deftypefun |
215 | ||
216 | @cindex complex trigonometric functions | |
217 | ||
7a68c94a UD |
218 | @w{ISO C 9x} defines variants of the trig functions which work on |
219 | complex numbers. The GNU C library provides these functions, but they | |
220 | are only useful if your compiler supports the new complex types defined | |
221 | by the standard. | |
222 | @c Change this when gcc is fixed. -zw | |
223 | (As of this writing GCC supports complex numbers, but there are bugs in | |
224 | the implementation.) | |
b4012b75 UD |
225 | |
226 | @comment complex.h | |
227 | @comment ISO | |
228 | @deftypefun {complex double} csin (complex double @var{z}) | |
4260bc74 UD |
229 | @comment complex.h |
230 | @comment ISO | |
779ae82e | 231 | @deftypefunx {complex float} csinf (complex float @var{z}) |
4260bc74 UD |
232 | @comment complex.h |
233 | @comment ISO | |
779ae82e | 234 | @deftypefunx {complex long double} csinl (complex long double @var{z}) |
7a68c94a | 235 | These functions return the complex sine of @var{z}. |
b4012b75 UD |
236 | The mathematical definition of the complex sine is |
237 | ||
779ae82e UD |
238 | @ifinfo |
239 | @math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}. | |
240 | @end ifinfo | |
779ae82e UD |
241 | @tex |
242 | $$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$ | |
243 | @end tex | |
b4012b75 UD |
244 | @end deftypefun |
245 | ||
246 | @comment complex.h | |
247 | @comment ISO | |
248 | @deftypefun {complex double} ccos (complex double @var{z}) | |
4260bc74 UD |
249 | @comment complex.h |
250 | @comment ISO | |
779ae82e | 251 | @deftypefunx {complex float} ccosf (complex float @var{z}) |
4260bc74 UD |
252 | @comment complex.h |
253 | @comment ISO | |
779ae82e | 254 | @deftypefunx {complex long double} ccosl (complex long double @var{z}) |
7a68c94a | 255 | These functions return the complex cosine of @var{z}. |
b4012b75 UD |
256 | The mathematical definition of the complex cosine is |
257 | ||
779ae82e UD |
258 | @ifinfo |
259 | @math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))} | |
260 | @end ifinfo | |
779ae82e UD |
261 | @tex |
262 | $$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$ | |
263 | @end tex | |
b4012b75 UD |
264 | @end deftypefun |
265 | ||
266 | @comment complex.h | |
267 | @comment ISO | |
268 | @deftypefun {complex double} ctan (complex double @var{z}) | |
4260bc74 UD |
269 | @comment complex.h |
270 | @comment ISO | |
779ae82e | 271 | @deftypefunx {complex float} ctanf (complex float @var{z}) |
4260bc74 UD |
272 | @comment complex.h |
273 | @comment ISO | |
779ae82e | 274 | @deftypefunx {complex long double} ctanl (complex long double @var{z}) |
7a68c94a | 275 | These functions return the complex tangent of @var{z}. |
b4012b75 UD |
276 | The mathematical definition of the complex tangent is |
277 | ||
779ae82e | 278 | @ifinfo |
7a68c94a | 279 | @math{tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))} |
779ae82e | 280 | @end ifinfo |
779ae82e | 281 | @tex |
7a68c94a | 282 | $$\tan(z) = -i \cdot {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$ |
779ae82e | 283 | @end tex |
7a68c94a UD |
284 | |
285 | @noindent | |
286 | The complex tangent has poles at @math{pi/2 + 2n}, where @math{n} is an | |
287 | integer. @code{ctan} may signal overflow if @var{z} is too close to a | |
288 | pole. | |
b4012b75 UD |
289 | @end deftypefun |
290 | ||
28f540f4 RM |
291 | |
292 | @node Inverse Trig Functions | |
293 | @section Inverse Trigonometric Functions | |
6d52618b | 294 | @cindex inverse trigonometric functions |
28f540f4 RM |
295 | |
296 | These are the usual arc sine, arc cosine and arc tangent functions, | |
04b9968b | 297 | which are the inverses of the sine, cosine and tangent functions |
28f540f4 RM |
298 | respectively. |
299 | ||
300 | @comment math.h | |
f65fd747 | 301 | @comment ISO |
28f540f4 | 302 | @deftypefun double asin (double @var{x}) |
4260bc74 UD |
303 | @comment math.h |
304 | @comment ISO | |
779ae82e | 305 | @deftypefunx float asinf (float @var{x}) |
4260bc74 UD |
306 | @comment math.h |
307 | @comment ISO | |
779ae82e | 308 | @deftypefunx {long double} asinl (long double @var{x}) |
b4012b75 | 309 | These functions compute the arc sine of @var{x}---that is, the value whose |
28f540f4 RM |
310 | sine is @var{x}. The value is in units of radians. Mathematically, |
311 | there are infinitely many such values; the one actually returned is the | |
312 | one between @code{-pi/2} and @code{pi/2} (inclusive). | |
313 | ||
7a68c94a UD |
314 | The arc sine function is defined mathematically only |
315 | over the domain @code{-1} to @code{1}. If @var{x} is outside the | |
316 | domain, @code{asin} signals a domain error. | |
28f540f4 RM |
317 | @end deftypefun |
318 | ||
319 | @comment math.h | |
f65fd747 | 320 | @comment ISO |
28f540f4 | 321 | @deftypefun double acos (double @var{x}) |
4260bc74 UD |
322 | @comment math.h |
323 | @comment ISO | |
779ae82e | 324 | @deftypefunx float acosf (float @var{x}) |
4260bc74 UD |
325 | @comment math.h |
326 | @comment ISO | |
779ae82e | 327 | @deftypefunx {long double} acosl (long double @var{x}) |
b4012b75 | 328 | These functions compute the arc cosine of @var{x}---that is, the value |
28f540f4 RM |
329 | whose cosine is @var{x}. The value is in units of radians. |
330 | Mathematically, there are infinitely many such values; the one actually | |
331 | returned is the one between @code{0} and @code{pi} (inclusive). | |
332 | ||
7a68c94a UD |
333 | The arc cosine function is defined mathematically only |
334 | over the domain @code{-1} to @code{1}. If @var{x} is outside the | |
335 | domain, @code{acos} signals a domain error. | |
28f540f4 RM |
336 | @end deftypefun |
337 | ||
28f540f4 | 338 | @comment math.h |
f65fd747 | 339 | @comment ISO |
28f540f4 | 340 | @deftypefun double atan (double @var{x}) |
4260bc74 UD |
341 | @comment math.h |
342 | @comment ISO | |
779ae82e | 343 | @deftypefunx float atanf (float @var{x}) |
4260bc74 UD |
344 | @comment math.h |
345 | @comment ISO | |
779ae82e | 346 | @deftypefunx {long double} atanl (long double @var{x}) |
b4012b75 | 347 | These functions compute the arc tangent of @var{x}---that is, the value |
28f540f4 RM |
348 | whose tangent is @var{x}. The value is in units of radians. |
349 | Mathematically, there are infinitely many such values; the one actually | |
7a68c94a | 350 | returned is the one between @code{-pi/2} and @code{pi/2} (inclusive). |
28f540f4 RM |
351 | @end deftypefun |
352 | ||
353 | @comment math.h | |
f65fd747 | 354 | @comment ISO |
28f540f4 | 355 | @deftypefun double atan2 (double @var{y}, double @var{x}) |
4260bc74 UD |
356 | @comment math.h |
357 | @comment ISO | |
779ae82e | 358 | @deftypefunx float atan2f (float @var{y}, float @var{x}) |
4260bc74 UD |
359 | @comment math.h |
360 | @comment ISO | |
779ae82e | 361 | @deftypefunx {long double} atan2l (long double @var{y}, long double @var{x}) |
7a68c94a UD |
362 | This function computes the arc tangent of @var{y}/@var{x}, but the signs |
363 | of both arguments are used to determine the quadrant of the result, and | |
364 | @var{x} is permitted to be zero. The return value is given in radians | |
365 | and is in the range @code{-pi} to @code{pi}, inclusive. | |
28f540f4 RM |
366 | |
367 | If @var{x} and @var{y} are coordinates of a point in the plane, | |
368 | @code{atan2} returns the signed angle between the line from the origin | |
369 | to that point and the x-axis. Thus, @code{atan2} is useful for | |
370 | converting Cartesian coordinates to polar coordinates. (To compute the | |
371 | radial coordinate, use @code{hypot}; see @ref{Exponents and | |
372 | Logarithms}.) | |
373 | ||
7a68c94a UD |
374 | @c This is experimentally true. Should it be so? -zw |
375 | If both @var{x} and @var{y} are zero, @code{atan2} returns zero. | |
28f540f4 RM |
376 | @end deftypefun |
377 | ||
b4012b75 | 378 | @cindex inverse complex trigonometric functions |
7a68c94a | 379 | @w{ISO C 9x} defines complex versions of the inverse trig functions. |
b4012b75 UD |
380 | |
381 | @comment complex.h | |
382 | @comment ISO | |
383 | @deftypefun {complex double} casin (complex double @var{z}) | |
4260bc74 UD |
384 | @comment complex.h |
385 | @comment ISO | |
779ae82e | 386 | @deftypefunx {complex float} casinf (complex float @var{z}) |
4260bc74 UD |
387 | @comment complex.h |
388 | @comment ISO | |
779ae82e | 389 | @deftypefunx {complex long double} casinl (complex long double @var{z}) |
b4012b75 | 390 | These functions compute the complex arc sine of @var{z}---that is, the |
7a68c94a | 391 | value whose sine is @var{z}. The value returned is in radians. |
b4012b75 | 392 | |
7a68c94a UD |
393 | Unlike the real-valued functions, @code{casin} is defined for all |
394 | values of @var{z}. | |
b4012b75 UD |
395 | @end deftypefun |
396 | ||
397 | @comment complex.h | |
398 | @comment ISO | |
399 | @deftypefun {complex double} cacos (complex double @var{z}) | |
4260bc74 UD |
400 | @comment complex.h |
401 | @comment ISO | |
779ae82e | 402 | @deftypefunx {complex float} cacosf (complex float @var{z}) |
4260bc74 UD |
403 | @comment complex.h |
404 | @comment ISO | |
779ae82e | 405 | @deftypefunx {complex long double} cacosl (complex long double @var{z}) |
b4012b75 | 406 | These functions compute the complex arc cosine of @var{z}---that is, the |
7a68c94a | 407 | value whose cosine is @var{z}. The value returned is in radians. |
b4012b75 | 408 | |
7a68c94a UD |
409 | Unlike the real-valued functions, @code{cacos} is defined for all |
410 | values of @var{z}. | |
b4012b75 UD |
411 | @end deftypefun |
412 | ||
413 | ||
414 | @comment complex.h | |
415 | @comment ISO | |
416 | @deftypefun {complex double} catan (complex double @var{z}) | |
4260bc74 UD |
417 | @comment complex.h |
418 | @comment ISO | |
779ae82e | 419 | @deftypefunx {complex float} catanf (complex float @var{z}) |
4260bc74 UD |
420 | @comment complex.h |
421 | @comment ISO | |
779ae82e | 422 | @deftypefunx {complex long double} catanl (complex long double @var{z}) |
b4012b75 UD |
423 | These functions compute the complex arc tangent of @var{z}---that is, |
424 | the value whose tangent is @var{z}. The value is in units of radians. | |
425 | @end deftypefun | |
426 | ||
28f540f4 RM |
427 | |
428 | @node Exponents and Logarithms | |
429 | @section Exponentiation and Logarithms | |
430 | @cindex exponentiation functions | |
431 | @cindex power functions | |
432 | @cindex logarithm functions | |
433 | ||
434 | @comment math.h | |
f65fd747 | 435 | @comment ISO |
28f540f4 | 436 | @deftypefun double exp (double @var{x}) |
4260bc74 UD |
437 | @comment math.h |
438 | @comment ISO | |
779ae82e | 439 | @deftypefunx float expf (float @var{x}) |
4260bc74 UD |
440 | @comment math.h |
441 | @comment ISO | |
779ae82e | 442 | @deftypefunx {long double} expl (long double @var{x}) |
7a68c94a UD |
443 | These functions compute @code{e} (the base of natural logarithms) raised |
444 | to the power @var{x}. | |
28f540f4 | 445 | |
7a68c94a UD |
446 | If the magnitude of the result is too large to be representable, |
447 | @code{exp} signals overflow. | |
28f540f4 RM |
448 | @end deftypefun |
449 | ||
b4012b75 UD |
450 | @comment math.h |
451 | @comment ISO | |
04a96fd4 | 452 | @deftypefun double exp2 (double @var{x}) |
4260bc74 UD |
453 | @comment math.h |
454 | @comment ISO | |
04a96fd4 | 455 | @deftypefunx float exp2f (float @var{x}) |
4260bc74 UD |
456 | @comment math.h |
457 | @comment ISO | |
04a96fd4 | 458 | @deftypefunx {long double} exp2l (long double @var{x}) |
7a68c94a | 459 | These functions compute @code{2} raised to the power @var{x}. |
04a96fd4 | 460 | Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}. |
b4012b75 UD |
461 | @end deftypefun |
462 | ||
463 | @comment math.h | |
04a96fd4 UD |
464 | @comment GNU |
465 | @deftypefun double exp10 (double @var{x}) | |
4260bc74 UD |
466 | @comment math.h |
467 | @comment GNU | |
04a96fd4 | 468 | @deftypefunx float exp10f (float @var{x}) |
4260bc74 UD |
469 | @comment math.h |
470 | @comment GNU | |
04a96fd4 | 471 | @deftypefunx {long double} exp10l (long double @var{x}) |
4260bc74 UD |
472 | @comment math.h |
473 | @comment GNU | |
04a96fd4 | 474 | @deftypefunx double pow10 (double @var{x}) |
4260bc74 UD |
475 | @comment math.h |
476 | @comment GNU | |
04a96fd4 | 477 | @deftypefunx float pow10f (float @var{x}) |
4260bc74 UD |
478 | @comment math.h |
479 | @comment GNU | |
04a96fd4 | 480 | @deftypefunx {long double} pow10l (long double @var{x}) |
7a68c94a UD |
481 | These functions compute @code{10} raised to the power @var{x}. |
482 | Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}. | |
b4012b75 | 483 | |
7a68c94a UD |
484 | These functions are GNU extensions. The name @code{exp10} is |
485 | preferred, since it is analogous to @code{exp} and @code{exp2}. | |
b4012b75 UD |
486 | @end deftypefun |
487 | ||
488 | ||
28f540f4 | 489 | @comment math.h |
f65fd747 | 490 | @comment ISO |
28f540f4 | 491 | @deftypefun double log (double @var{x}) |
4260bc74 UD |
492 | @comment math.h |
493 | @comment ISO | |
f2ea0f5b | 494 | @deftypefunx float logf (float @var{x}) |
4260bc74 UD |
495 | @comment math.h |
496 | @comment ISO | |
779ae82e | 497 | @deftypefunx {long double} logl (long double @var{x}) |
7a68c94a | 498 | These functions compute the natural logarithm of @var{x}. @code{exp (log |
28f540f4 RM |
499 | (@var{x}))} equals @var{x}, exactly in mathematics and approximately in |
500 | C. | |
501 | ||
7a68c94a UD |
502 | If @var{x} is negative, @code{log} signals a domain error. If @var{x} |
503 | is zero, it returns negative infinity; if @var{x} is too close to zero, | |
504 | it may signal overflow. | |
28f540f4 RM |
505 | @end deftypefun |
506 | ||
507 | @comment math.h | |
f65fd747 | 508 | @comment ISO |
28f540f4 | 509 | @deftypefun double log10 (double @var{x}) |
4260bc74 UD |
510 | @comment math.h |
511 | @comment ISO | |
779ae82e | 512 | @deftypefunx float log10f (float @var{x}) |
4260bc74 UD |
513 | @comment math.h |
514 | @comment ISO | |
779ae82e | 515 | @deftypefunx {long double} log10l (long double @var{x}) |
7a68c94a | 516 | These functions return the base-10 logarithm of @var{x}. |
28f540f4 | 517 | @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}. |
7a68c94a | 518 | |
28f540f4 RM |
519 | @end deftypefun |
520 | ||
b4012b75 UD |
521 | @comment math.h |
522 | @comment ISO | |
523 | @deftypefun double log2 (double @var{x}) | |
4260bc74 UD |
524 | @comment math.h |
525 | @comment ISO | |
779ae82e | 526 | @deftypefunx float log2f (float @var{x}) |
4260bc74 UD |
527 | @comment math.h |
528 | @comment ISO | |
779ae82e | 529 | @deftypefunx {long double} log2l (long double @var{x}) |
7a68c94a | 530 | These functions return the base-2 logarithm of @var{x}. |
b4012b75 UD |
531 | @code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}. |
532 | @end deftypefun | |
533 | ||
55c14926 UD |
534 | @comment math.h |
535 | @comment ISO | |
536 | @deftypefun double logb (double @var{x}) | |
4260bc74 UD |
537 | @comment math.h |
538 | @comment ISO | |
55c14926 | 539 | @deftypefunx float logbf (float @var{x}) |
4260bc74 UD |
540 | @comment math.h |
541 | @comment ISO | |
55c14926 UD |
542 | @deftypefunx {long double} logbl (long double @var{x}) |
543 | These functions extract the exponent of @var{x} and return it as a | |
7a68c94a UD |
544 | floating-point value. If @code{FLT_RADIX} is two, @code{logb} is equal |
545 | to @code{floor (log2 (x))}, except it's probably faster. | |
55c14926 | 546 | |
04b9968b | 547 | If @var{x} is de-normalized, @code{logb} returns the exponent @var{x} |
7a68c94a UD |
548 | would have if it were normalized. If @var{x} is infinity (positive or |
549 | negative), @code{logb} returns @math{@infinity{}}. If @var{x} is zero, | |
550 | @code{logb} returns @math{@infinity{}}. It does not signal. | |
55c14926 UD |
551 | @end deftypefun |
552 | ||
553 | @comment math.h | |
554 | @comment ISO | |
555 | @deftypefun int ilogb (double @var{x}) | |
4260bc74 UD |
556 | @comment math.h |
557 | @comment ISO | |
55c14926 | 558 | @deftypefunx int ilogbf (float @var{x}) |
4260bc74 UD |
559 | @comment math.h |
560 | @comment ISO | |
55c14926 UD |
561 | @deftypefunx int ilogbl (long double @var{x}) |
562 | These functions are equivalent to the corresponding @code{logb} | |
7a68c94a UD |
563 | functions except that they return signed integer values. |
564 | @end deftypefun | |
565 | ||
566 | @noindent | |
567 | Since integers cannot represent infinity and NaN, @code{ilogb} instead | |
568 | returns an integer that can't be the exponent of a normal floating-point | |
569 | number. @file{math.h} defines constants so you can check for this. | |
570 | ||
571 | @comment math.h | |
572 | @comment ISO | |
573 | @deftypevr Macro int FP_ILOGB0 | |
574 | @code{ilogb} returns this value if its argument is @code{0}. The | |
575 | numeric value is either @code{INT_MIN} or @code{-INT_MAX}. | |
576 | ||
577 | This macro is defined in @w{ISO C 9X}. | |
578 | @end deftypevr | |
579 | ||
580 | @comment math.h | |
581 | @comment ISO | |
582 | @deftypevr Macro int FP_ILOGBNAN | |
583 | @code{ilogb} returns this value if its argument is @code{NaN}. The | |
584 | numeric value is either @code{INT_MIN} or @code{INT_MAX}. | |
585 | ||
586 | This macro is defined in @w{ISO C 9X}. | |
587 | @end deftypevr | |
588 | ||
589 | These values are system specific. They might even be the same. The | |
590 | proper way to test the result of @code{ilogb} is as follows: | |
55c14926 UD |
591 | |
592 | @smallexample | |
593 | i = ilogb (f); | |
594 | if (i == FP_ILOGB0 || i == FP_ILOGBNAN) | |
595 | @{ | |
596 | if (isnan (f)) | |
597 | @{ | |
598 | /* @r{Handle NaN.} */ | |
599 | @} | |
600 | else if (f == 0.0) | |
601 | @{ | |
602 | /* @r{Handle 0.0.} */ | |
603 | @} | |
604 | else | |
605 | @{ | |
606 | /* @r{Some other value with large exponent,} | |
607 | @r{perhaps +Inf.} */ | |
608 | @} | |
609 | @} | |
610 | @end smallexample | |
611 | ||
28f540f4 | 612 | @comment math.h |
f65fd747 | 613 | @comment ISO |
28f540f4 | 614 | @deftypefun double pow (double @var{base}, double @var{power}) |
4260bc74 UD |
615 | @comment math.h |
616 | @comment ISO | |
779ae82e | 617 | @deftypefunx float powf (float @var{base}, float @var{power}) |
4260bc74 UD |
618 | @comment math.h |
619 | @comment ISO | |
779ae82e | 620 | @deftypefunx {long double} powl (long double @var{base}, long double @var{power}) |
b4012b75 | 621 | These are general exponentiation functions, returning @var{base} raised |
28f540f4 RM |
622 | to @var{power}. |
623 | ||
7a68c94a UD |
624 | Mathematically, @code{pow} would return a complex number when @var{base} |
625 | is negative and @var{power} is not an integral value. @code{pow} can't | |
626 | do that, so instead it signals a domain error. @code{pow} may also | |
627 | underflow or overflow the destination type. | |
28f540f4 RM |
628 | @end deftypefun |
629 | ||
630 | @cindex square root function | |
631 | @comment math.h | |
f65fd747 | 632 | @comment ISO |
28f540f4 | 633 | @deftypefun double sqrt (double @var{x}) |
4260bc74 UD |
634 | @comment math.h |
635 | @comment ISO | |
779ae82e | 636 | @deftypefunx float sqrtf (float @var{x}) |
4260bc74 UD |
637 | @comment math.h |
638 | @comment ISO | |
779ae82e | 639 | @deftypefunx {long double} sqrtl (long double @var{x}) |
b4012b75 | 640 | These functions return the nonnegative square root of @var{x}. |
28f540f4 | 641 | |
7a68c94a UD |
642 | If @var{x} is negative, @code{sqrt} signals a domain error. |
643 | Mathematically, it should return a complex number. | |
28f540f4 RM |
644 | @end deftypefun |
645 | ||
646 | @cindex cube root function | |
647 | @comment math.h | |
648 | @comment BSD | |
649 | @deftypefun double cbrt (double @var{x}) | |
4260bc74 UD |
650 | @comment math.h |
651 | @comment BSD | |
779ae82e | 652 | @deftypefunx float cbrtf (float @var{x}) |
4260bc74 UD |
653 | @comment math.h |
654 | @comment BSD | |
779ae82e | 655 | @deftypefunx {long double} cbrtl (long double @var{x}) |
b4012b75 | 656 | These functions return the cube root of @var{x}. They cannot |
28f540f4 RM |
657 | fail; every representable real value has a representable real cube root. |
658 | @end deftypefun | |
659 | ||
660 | @comment math.h | |
b4012b75 | 661 | @comment ISO |
28f540f4 | 662 | @deftypefun double hypot (double @var{x}, double @var{y}) |
4260bc74 UD |
663 | @comment math.h |
664 | @comment ISO | |
779ae82e | 665 | @deftypefunx float hypotf (float @var{x}, float @var{y}) |
4260bc74 UD |
666 | @comment math.h |
667 | @comment ISO | |
779ae82e | 668 | @deftypefunx {long double} hypotl (long double @var{x}, long double @var{y}) |
b4012b75 | 669 | These functions return @code{sqrt (@var{x}*@var{x} + |
7a68c94a | 670 | @var{y}*@var{y})}. This is the length of the hypotenuse of a right |
28f540f4 | 671 | triangle with sides of length @var{x} and @var{y}, or the distance |
7a68c94a UD |
672 | of the point (@var{x}, @var{y}) from the origin. Using this function |
673 | instead of the direct formula is wise, since the error is | |
b4012b75 | 674 | much smaller. See also the function @code{cabs} in @ref{Absolute Value}. |
28f540f4 RM |
675 | @end deftypefun |
676 | ||
677 | @comment math.h | |
b4012b75 | 678 | @comment ISO |
28f540f4 | 679 | @deftypefun double expm1 (double @var{x}) |
4260bc74 UD |
680 | @comment math.h |
681 | @comment ISO | |
779ae82e | 682 | @deftypefunx float expm1f (float @var{x}) |
4260bc74 UD |
683 | @comment math.h |
684 | @comment ISO | |
779ae82e | 685 | @deftypefunx {long double} expm1l (long double @var{x}) |
b4012b75 | 686 | These functions return a value equivalent to @code{exp (@var{x}) - 1}. |
7a68c94a | 687 | They are computed in a way that is accurate even if @var{x} is |
04b9968b | 688 | near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate owing |
28f540f4 RM |
689 | to subtraction of two numbers that are nearly equal. |
690 | @end deftypefun | |
691 | ||
692 | @comment math.h | |
b4012b75 | 693 | @comment ISO |
28f540f4 | 694 | @deftypefun double log1p (double @var{x}) |
4260bc74 UD |
695 | @comment math.h |
696 | @comment ISO | |
779ae82e | 697 | @deftypefunx float log1pf (float @var{x}) |
4260bc74 UD |
698 | @comment math.h |
699 | @comment ISO | |
779ae82e | 700 | @deftypefunx {long double} log1pl (long double @var{x}) |
7a68c94a UD |
701 | These functions returns a value equivalent to @w{@code{log (1 + @var{x})}}. |
702 | They are computed in a way that is accurate even if @var{x} is | |
28f540f4 RM |
703 | near zero. |
704 | @end deftypefun | |
705 | ||
b4012b75 UD |
706 | @cindex complex exponentiation functions |
707 | @cindex complex logarithm functions | |
708 | ||
7a68c94a UD |
709 | @w{ISO C 9X} defines complex variants of some of the exponentiation and |
710 | logarithm functions. | |
b4012b75 UD |
711 | |
712 | @comment complex.h | |
713 | @comment ISO | |
714 | @deftypefun {complex double} cexp (complex double @var{z}) | |
4260bc74 UD |
715 | @comment complex.h |
716 | @comment ISO | |
779ae82e | 717 | @deftypefunx {complex float} cexpf (complex float @var{z}) |
4260bc74 UD |
718 | @comment complex.h |
719 | @comment ISO | |
779ae82e | 720 | @deftypefunx {complex long double} cexpl (complex long double @var{z}) |
7a68c94a UD |
721 | These functions return @code{e} (the base of natural |
722 | logarithms) raised to the power of @var{z}. | |
04b9968b | 723 | Mathematically, this corresponds to the value |
b4012b75 | 724 | |
779ae82e UD |
725 | @ifinfo |
726 | @math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))} | |
727 | @end ifinfo | |
779ae82e | 728 | @tex |
7a68c94a | 729 | $$\exp(z) = e^z = e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$ |
779ae82e | 730 | @end tex |
b4012b75 UD |
731 | @end deftypefun |
732 | ||
733 | @comment complex.h | |
734 | @comment ISO | |
735 | @deftypefun {complex double} clog (complex double @var{z}) | |
4260bc74 UD |
736 | @comment complex.h |
737 | @comment ISO | |
779ae82e | 738 | @deftypefunx {complex float} clogf (complex float @var{z}) |
4260bc74 UD |
739 | @comment complex.h |
740 | @comment ISO | |
779ae82e | 741 | @deftypefunx {complex long double} clogl (complex long double @var{z}) |
7a68c94a | 742 | These functions return the natural logarithm of @var{z}. |
04b9968b | 743 | Mathematically, this corresponds to the value |
b4012b75 | 744 | |
779ae82e UD |
745 | @ifinfo |
746 | @math{log (z) = log (cabs (z)) + I * carg (z)} | |
747 | @end ifinfo | |
779ae82e | 748 | @tex |
7a68c94a | 749 | $$\log(z) = \log |z| + i \arg z$$ |
779ae82e | 750 | @end tex |
7a68c94a UD |
751 | |
752 | @noindent | |
753 | @code{clog} has a pole at 0, and will signal overflow if @var{z} equals | |
754 | or is very close to 0. It is well-defined for all other values of | |
755 | @var{z}. | |
b4012b75 UD |
756 | @end deftypefun |
757 | ||
dfd2257a UD |
758 | |
759 | @comment complex.h | |
760 | @comment GNU | |
761 | @deftypefun {complex double} clog10 (complex double @var{z}) | |
4260bc74 UD |
762 | @comment complex.h |
763 | @comment GNU | |
dfd2257a | 764 | @deftypefunx {complex float} clog10f (complex float @var{z}) |
4260bc74 UD |
765 | @comment complex.h |
766 | @comment GNU | |
dfd2257a UD |
767 | @deftypefunx {complex long double} clog10l (complex long double @var{z}) |
768 | These functions return the base 10 logarithm of the complex value | |
04b9968b | 769 | @var{z}. Mathematically, this corresponds to the value |
dfd2257a UD |
770 | |
771 | @ifinfo | |
772 | @math{log (z) = log10 (cabs (z)) + I * carg (z)} | |
773 | @end ifinfo | |
dfd2257a | 774 | @tex |
7a68c94a | 775 | $$\log_{10}(z) = \log_{10}|z| + i \arg z$$ |
dfd2257a | 776 | @end tex |
dfd2257a | 777 | |
7a68c94a | 778 | These functions are GNU extensions. |
dfd2257a UD |
779 | @end deftypefun |
780 | ||
b4012b75 UD |
781 | @comment complex.h |
782 | @comment ISO | |
783 | @deftypefun {complex double} csqrt (complex double @var{z}) | |
4260bc74 UD |
784 | @comment complex.h |
785 | @comment ISO | |
779ae82e | 786 | @deftypefunx {complex float} csqrtf (complex float @var{z}) |
4260bc74 UD |
787 | @comment complex.h |
788 | @comment ISO | |
779ae82e | 789 | @deftypefunx {complex long double} csqrtl (complex long double @var{z}) |
7a68c94a UD |
790 | These functions return the complex square root of the argument @var{z}. Unlike |
791 | the real-valued functions, they are defined for all values of @var{z}. | |
b4012b75 UD |
792 | @end deftypefun |
793 | ||
794 | @comment complex.h | |
795 | @comment ISO | |
796 | @deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power}) | |
4260bc74 UD |
797 | @comment complex.h |
798 | @comment ISO | |
779ae82e | 799 | @deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power}) |
4260bc74 UD |
800 | @comment complex.h |
801 | @comment ISO | |
779ae82e | 802 | @deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power}) |
7a68c94a UD |
803 | These functions return @var{base} raised to the power of |
804 | @var{power}. This is equivalent to @w{@code{cexp (y * clog (x))}} | |
b4012b75 UD |
805 | @end deftypefun |
806 | ||
28f540f4 RM |
807 | @node Hyperbolic Functions |
808 | @section Hyperbolic Functions | |
809 | @cindex hyperbolic functions | |
810 | ||
811 | The functions in this section are related to the exponential functions; | |
812 | see @ref{Exponents and Logarithms}. | |
813 | ||
814 | @comment math.h | |
f65fd747 | 815 | @comment ISO |
28f540f4 | 816 | @deftypefun double sinh (double @var{x}) |
4260bc74 UD |
817 | @comment math.h |
818 | @comment ISO | |
779ae82e | 819 | @deftypefunx float sinhf (float @var{x}) |
4260bc74 UD |
820 | @comment math.h |
821 | @comment ISO | |
779ae82e | 822 | @deftypefunx {long double} sinhl (long double @var{x}) |
b4012b75 | 823 | These functions return the hyperbolic sine of @var{x}, defined |
7a68c94a UD |
824 | mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}. They |
825 | may signal overflow if @var{x} is too large. | |
28f540f4 RM |
826 | @end deftypefun |
827 | ||
828 | @comment math.h | |
f65fd747 | 829 | @comment ISO |
28f540f4 | 830 | @deftypefun double cosh (double @var{x}) |
4260bc74 UD |
831 | @comment math.h |
832 | @comment ISO | |
779ae82e | 833 | @deftypefunx float coshf (float @var{x}) |
4260bc74 UD |
834 | @comment math.h |
835 | @comment ISO | |
779ae82e | 836 | @deftypefunx {long double} coshl (long double @var{x}) |
b4012b75 UD |
837 | These function return the hyperbolic cosine of @var{x}, |
838 | defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}. | |
7a68c94a | 839 | They may signal overflow if @var{x} is too large. |
28f540f4 RM |
840 | @end deftypefun |
841 | ||
842 | @comment math.h | |
f65fd747 | 843 | @comment ISO |
28f540f4 | 844 | @deftypefun double tanh (double @var{x}) |
4260bc74 UD |
845 | @comment math.h |
846 | @comment ISO | |
779ae82e | 847 | @deftypefunx float tanhf (float @var{x}) |
4260bc74 UD |
848 | @comment math.h |
849 | @comment ISO | |
779ae82e | 850 | @deftypefunx {long double} tanhl (long double @var{x}) |
7a68c94a UD |
851 | These functions return the hyperbolic tangent of @var{x}, |
852 | defined mathematically as @w{@code{sinh (@var{x}) / cosh (@var{x})}}. | |
853 | They may signal overflow if @var{x} is too large. | |
28f540f4 RM |
854 | @end deftypefun |
855 | ||
b4012b75 UD |
856 | @cindex hyperbolic functions |
857 | ||
7a68c94a UD |
858 | There are counterparts for the hyperbolic functions which take |
859 | complex arguments. | |
b4012b75 UD |
860 | |
861 | @comment complex.h | |
862 | @comment ISO | |
863 | @deftypefun {complex double} csinh (complex double @var{z}) | |
4260bc74 UD |
864 | @comment complex.h |
865 | @comment ISO | |
779ae82e | 866 | @deftypefunx {complex float} csinhf (complex float @var{z}) |
4260bc74 UD |
867 | @comment complex.h |
868 | @comment ISO | |
779ae82e | 869 | @deftypefunx {complex long double} csinhl (complex long double @var{z}) |
b4012b75 | 870 | These functions return the complex hyperbolic sine of @var{z}, defined |
7a68c94a | 871 | mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}. |
b4012b75 UD |
872 | @end deftypefun |
873 | ||
874 | @comment complex.h | |
875 | @comment ISO | |
876 | @deftypefun {complex double} ccosh (complex double @var{z}) | |
4260bc74 UD |
877 | @comment complex.h |
878 | @comment ISO | |
779ae82e | 879 | @deftypefunx {complex float} ccoshf (complex float @var{z}) |
4260bc74 UD |
880 | @comment complex.h |
881 | @comment ISO | |
779ae82e | 882 | @deftypefunx {complex long double} ccoshl (complex long double @var{z}) |
b4012b75 | 883 | These functions return the complex hyperbolic cosine of @var{z}, defined |
7a68c94a | 884 | mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}. |
b4012b75 UD |
885 | @end deftypefun |
886 | ||
887 | @comment complex.h | |
888 | @comment ISO | |
889 | @deftypefun {complex double} ctanh (complex double @var{z}) | |
4260bc74 UD |
890 | @comment complex.h |
891 | @comment ISO | |
779ae82e | 892 | @deftypefunx {complex float} ctanhf (complex float @var{z}) |
4260bc74 UD |
893 | @comment complex.h |
894 | @comment ISO | |
779ae82e | 895 | @deftypefunx {complex long double} ctanhl (complex long double @var{z}) |
7a68c94a UD |
896 | These functions return the complex hyperbolic tangent of @var{z}, |
897 | defined mathematically as @w{@code{csinh (@var{z}) / ccosh (@var{z})}}. | |
b4012b75 UD |
898 | @end deftypefun |
899 | ||
900 | ||
28f540f4 RM |
901 | @cindex inverse hyperbolic functions |
902 | ||
903 | @comment math.h | |
b4012b75 | 904 | @comment ISO |
28f540f4 | 905 | @deftypefun double asinh (double @var{x}) |
4260bc74 UD |
906 | @comment math.h |
907 | @comment ISO | |
779ae82e | 908 | @deftypefunx float asinhf (float @var{x}) |
4260bc74 UD |
909 | @comment math.h |
910 | @comment ISO | |
779ae82e | 911 | @deftypefunx {long double} asinhl (long double @var{x}) |
b4012b75 | 912 | These functions return the inverse hyperbolic sine of @var{x}---the |
28f540f4 RM |
913 | value whose hyperbolic sine is @var{x}. |
914 | @end deftypefun | |
915 | ||
916 | @comment math.h | |
b4012b75 | 917 | @comment ISO |
28f540f4 | 918 | @deftypefun double acosh (double @var{x}) |
4260bc74 UD |
919 | @comment math.h |
920 | @comment ISO | |
779ae82e | 921 | @deftypefunx float acoshf (float @var{x}) |
4260bc74 UD |
922 | @comment math.h |
923 | @comment ISO | |
779ae82e | 924 | @deftypefunx {long double} acoshl (long double @var{x}) |
b4012b75 | 925 | These functions return the inverse hyperbolic cosine of @var{x}---the |
28f540f4 | 926 | value whose hyperbolic cosine is @var{x}. If @var{x} is less than |
7a68c94a | 927 | @code{1}, @code{acosh} signals a domain error. |
28f540f4 RM |
928 | @end deftypefun |
929 | ||
930 | @comment math.h | |
b4012b75 | 931 | @comment ISO |
28f540f4 | 932 | @deftypefun double atanh (double @var{x}) |
4260bc74 UD |
933 | @comment math.h |
934 | @comment ISO | |
779ae82e | 935 | @deftypefunx float atanhf (float @var{x}) |
4260bc74 UD |
936 | @comment math.h |
937 | @comment ISO | |
779ae82e | 938 | @deftypefunx {long double} atanhl (long double @var{x}) |
b4012b75 | 939 | These functions return the inverse hyperbolic tangent of @var{x}---the |
28f540f4 | 940 | value whose hyperbolic tangent is @var{x}. If the absolute value of |
7a68c94a UD |
941 | @var{x} is greater than @code{1}, @code{atanh} signals a domain error; |
942 | if it is equal to 1, @code{atanh} returns infinity. | |
28f540f4 RM |
943 | @end deftypefun |
944 | ||
b4012b75 UD |
945 | @cindex inverse complex hyperbolic functions |
946 | ||
947 | @comment complex.h | |
948 | @comment ISO | |
949 | @deftypefun {complex double} casinh (complex double @var{z}) | |
4260bc74 UD |
950 | @comment complex.h |
951 | @comment ISO | |
779ae82e | 952 | @deftypefunx {complex float} casinhf (complex float @var{z}) |
4260bc74 UD |
953 | @comment complex.h |
954 | @comment ISO | |
779ae82e | 955 | @deftypefunx {complex long double} casinhl (complex long double @var{z}) |
b4012b75 UD |
956 | These functions return the inverse complex hyperbolic sine of |
957 | @var{z}---the value whose complex hyperbolic sine is @var{z}. | |
958 | @end deftypefun | |
959 | ||
960 | @comment complex.h | |
961 | @comment ISO | |
962 | @deftypefun {complex double} cacosh (complex double @var{z}) | |
4260bc74 UD |
963 | @comment complex.h |
964 | @comment ISO | |
779ae82e | 965 | @deftypefunx {complex float} cacoshf (complex float @var{z}) |
4260bc74 UD |
966 | @comment complex.h |
967 | @comment ISO | |
779ae82e | 968 | @deftypefunx {complex long double} cacoshl (complex long double @var{z}) |
b4012b75 UD |
969 | These functions return the inverse complex hyperbolic cosine of |
970 | @var{z}---the value whose complex hyperbolic cosine is @var{z}. Unlike | |
7a68c94a | 971 | the real-valued functions, there are no restrictions on the value of @var{z}. |
b4012b75 UD |
972 | @end deftypefun |
973 | ||
974 | @comment complex.h | |
975 | @comment ISO | |
976 | @deftypefun {complex double} catanh (complex double @var{z}) | |
4260bc74 UD |
977 | @comment complex.h |
978 | @comment ISO | |
779ae82e | 979 | @deftypefunx {complex float} catanhf (complex float @var{z}) |
4260bc74 UD |
980 | @comment complex.h |
981 | @comment ISO | |
779ae82e | 982 | @deftypefunx {complex long double} catanhl (complex long double @var{z}) |
b4012b75 UD |
983 | These functions return the inverse complex hyperbolic tangent of |
984 | @var{z}---the value whose complex hyperbolic tangent is @var{z}. Unlike | |
7a68c94a UD |
985 | the real-valued functions, there are no restrictions on the value of |
986 | @var{z}. | |
b4012b75 UD |
987 | @end deftypefun |
988 | ||
7a68c94a UD |
989 | @node Special Functions |
990 | @section Special Functions | |
991 | @cindex special functions | |
992 | @cindex Bessel functions | |
993 | @cindex gamma function | |
994 | ||
04b9968b | 995 | These are some more exotic mathematical functions which are sometimes |
7a68c94a UD |
996 | useful. Currently they only have real-valued versions. |
997 | ||
998 | @comment math.h | |
999 | @comment SVID | |
1000 | @deftypefun double erf (double @var{x}) | |
4260bc74 UD |
1001 | @comment math.h |
1002 | @comment SVID | |
7a68c94a | 1003 | @deftypefunx float erff (float @var{x}) |
4260bc74 UD |
1004 | @comment math.h |
1005 | @comment SVID | |
7a68c94a UD |
1006 | @deftypefunx {long double} erfl (long double @var{x}) |
1007 | @code{erf} returns the error function of @var{x}. The error | |
1008 | function is defined as | |
1009 | @tex | |
1010 | $$\hbox{erf}(x) = {2\over\sqrt{\pi}}\cdot\int_0^x e^{-t^2} \hbox{d}t$$ | |
1011 | @end tex | |
1012 | @ifnottex | |
1013 | @smallexample | |
1014 | erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt | |
1015 | @end smallexample | |
1016 | @end ifnottex | |
1017 | @end deftypefun | |
1018 | ||
1019 | @comment math.h | |
1020 | @comment SVID | |
1021 | @deftypefun double erfc (double @var{x}) | |
4260bc74 UD |
1022 | @comment math.h |
1023 | @comment SVID | |
7a68c94a | 1024 | @deftypefunx float erfcf (float @var{x}) |
4260bc74 UD |
1025 | @comment math.h |
1026 | @comment SVID | |
7a68c94a UD |
1027 | @deftypefunx {long double} erfcl (long double @var{x}) |
1028 | @code{erfc} returns @code{1.0 - erf(@var{x})}, but computed in a | |
1029 | fashion that avoids round-off error when @var{x} is large. | |
1030 | @end deftypefun | |
1031 | ||
1032 | @comment math.h | |
1033 | @comment SVID | |
1034 | @deftypefun double lgamma (double @var{x}) | |
4260bc74 UD |
1035 | @comment math.h |
1036 | @comment SVID | |
7a68c94a | 1037 | @deftypefunx float lgammaf (float @var{x}) |
4260bc74 UD |
1038 | @comment math.h |
1039 | @comment SVID | |
7a68c94a UD |
1040 | @deftypefunx {long double} lgammal (long double @var{x}) |
1041 | @code{lgamma} returns the natural logarithm of the absolute value of | |
1042 | the gamma function of @var{x}. The gamma function is defined as | |
1043 | @tex | |
1044 | $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$ | |
1045 | @end tex | |
1046 | @ifnottex | |
1047 | @smallexample | |
1048 | gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt | |
1049 | @end smallexample | |
1050 | @end ifnottex | |
1051 | ||
1052 | @vindex signgam | |
1053 | The sign of the gamma function is stored in the global variable | |
1054 | @var{signgam}, which is declared in @file{math.h}. It is @code{1} if | |
04b9968b | 1055 | the intermediate result was positive or zero, or @code{-1} if it was |
7a68c94a UD |
1056 | negative. |
1057 | ||
e852e889 UD |
1058 | To compute the real gamma function you can use the @code{tgamma} |
1059 | function or you can compute the values as follows: | |
7a68c94a UD |
1060 | @smallexample |
1061 | lgam = lgamma(x); | |
1062 | gam = signgam*exp(lgam); | |
1063 | @end smallexample | |
1064 | ||
04b9968b | 1065 | The gamma function has singularities at the non-positive integers. |
7a68c94a UD |
1066 | @code{lgamma} will raise the zero divide exception if evaluated at a |
1067 | singularity. | |
1068 | @end deftypefun | |
1069 | ||
1070 | @comment math.h | |
1071 | @comment XPG | |
07435eb4 | 1072 | @deftypefun double lgamma_r (double @var{x}, int *@var{signp}) |
4260bc74 UD |
1073 | @comment math.h |
1074 | @comment XPG | |
07435eb4 | 1075 | @deftypefunx float lgammaf_r (float @var{x}, int *@var{signp}) |
4260bc74 UD |
1076 | @comment math.h |
1077 | @comment XPG | |
07435eb4 | 1078 | @deftypefunx {long double} lgammal_r (long double @var{x}, int *@var{signp}) |
7a68c94a UD |
1079 | @code{lgamma_r} is just like @code{lgamma}, but it stores the sign of |
1080 | the intermediate result in the variable pointed to by @var{signp} | |
04b9968b | 1081 | instead of in the @var{signgam} global. This means it is reentrant. |
7a68c94a UD |
1082 | @end deftypefun |
1083 | ||
7a68c94a UD |
1084 | @comment math.h |
1085 | @comment SVID | |
1086 | @deftypefun double gamma (double @var{x}) | |
4260bc74 UD |
1087 | @comment math.h |
1088 | @comment SVID | |
7a68c94a | 1089 | @deftypefunx float gammaf (float @var{x}) |
4260bc74 UD |
1090 | @comment math.h |
1091 | @comment SVID | |
7a68c94a | 1092 | @deftypefunx {long double} gammal (long double @var{x}) |
e852e889 UD |
1093 | These functions exist for compatibility reasons. They are equivalent to |
1094 | @code{lgamma} etc. It is better to use @code{lgamma} since for one the | |
04b9968b | 1095 | name reflects better the actual computation, moreover @code{lgamma} is |
e852e889 UD |
1096 | standardized in @w{ISO C 9x} while @code{gamma} is not. |
1097 | @end deftypefun | |
1098 | ||
1099 | @comment math.h | |
1100 | @comment XPG | |
1101 | @deftypefun double tgamma (double @var{x}) | |
4260bc74 UD |
1102 | @comment math.h |
1103 | @comment XPG | |
e852e889 | 1104 | @deftypefunx float tgammaf (float @var{x}) |
4260bc74 UD |
1105 | @comment math.h |
1106 | @comment XPG | |
e852e889 UD |
1107 | @deftypefunx {long double} tgammal (long double @var{x}) |
1108 | @code{tgamma} applies the gamma function to @var{x}. The gamma | |
1109 | function is defined as | |
1110 | @tex | |
1111 | $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$ | |
1112 | @end tex | |
1113 | @ifnottex | |
1114 | @smallexample | |
1115 | gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt | |
1116 | @end smallexample | |
1117 | @end ifnottex | |
1118 | ||
1119 | This function was introduced in @w{ISO C 9x}. | |
7a68c94a | 1120 | @end deftypefun |
7a68c94a UD |
1121 | |
1122 | @comment math.h | |
1123 | @comment SVID | |
1124 | @deftypefun double j0 (double @var{x}) | |
4260bc74 UD |
1125 | @comment math.h |
1126 | @comment SVID | |
7a68c94a | 1127 | @deftypefunx float j0f (float @var{x}) |
4260bc74 UD |
1128 | @comment math.h |
1129 | @comment SVID | |
7a68c94a UD |
1130 | @deftypefunx {long double} j0l (long double @var{x}) |
1131 | @code{j0} returns the Bessel function of the first kind of order 0 of | |
1132 | @var{x}. It may signal underflow if @var{x} is too large. | |
1133 | @end deftypefun | |
1134 | ||
1135 | @comment math.h | |
1136 | @comment SVID | |
1137 | @deftypefun double j1 (double @var{x}) | |
4260bc74 UD |
1138 | @comment math.h |
1139 | @comment SVID | |
7a68c94a | 1140 | @deftypefunx float j1f (float @var{x}) |
4260bc74 UD |
1141 | @comment math.h |
1142 | @comment SVID | |
7a68c94a UD |
1143 | @deftypefunx {long double} j1l (long double @var{x}) |
1144 | @code{j1} returns the Bessel function of the first kind of order 1 of | |
1145 | @var{x}. It may signal underflow if @var{x} is too large. | |
1146 | @end deftypefun | |
1147 | ||
1148 | @comment math.h | |
1149 | @comment SVID | |
1150 | @deftypefun double jn (int n, double @var{x}) | |
4260bc74 UD |
1151 | @comment math.h |
1152 | @comment SVID | |
7a68c94a | 1153 | @deftypefunx float jnf (int n, float @var{x}) |
4260bc74 UD |
1154 | @comment math.h |
1155 | @comment SVID | |
7a68c94a UD |
1156 | @deftypefunx {long double} jnl (int n, long double @var{x}) |
1157 | @code{jn} returns the Bessel function of the first kind of order | |
1158 | @var{n} of @var{x}. It may signal underflow if @var{x} is too large. | |
1159 | @end deftypefun | |
1160 | ||
1161 | @comment math.h | |
1162 | @comment SVID | |
1163 | @deftypefun double y0 (double @var{x}) | |
4260bc74 UD |
1164 | @comment math.h |
1165 | @comment SVID | |
7a68c94a | 1166 | @deftypefunx float y0f (float @var{x}) |
4260bc74 UD |
1167 | @comment math.h |
1168 | @comment SVID | |
7a68c94a UD |
1169 | @deftypefunx {long double} y0l (long double @var{x}) |
1170 | @code{y0} returns the Bessel function of the second kind of order 0 of | |
1171 | @var{x}. It may signal underflow if @var{x} is too large. If @var{x} | |
1172 | is negative, @code{y0} signals a domain error; if it is zero, | |
1173 | @code{y0} signals overflow and returns @math{-@infinity}. | |
1174 | @end deftypefun | |
1175 | ||
1176 | @comment math.h | |
1177 | @comment SVID | |
1178 | @deftypefun double y1 (double @var{x}) | |
4260bc74 UD |
1179 | @comment math.h |
1180 | @comment SVID | |
7a68c94a | 1181 | @deftypefunx float y1f (float @var{x}) |
4260bc74 UD |
1182 | @comment math.h |
1183 | @comment SVID | |
7a68c94a UD |
1184 | @deftypefunx {long double} y1l (long double @var{x}) |
1185 | @code{y1} returns the Bessel function of the second kind of order 1 of | |
1186 | @var{x}. It may signal underflow if @var{x} is too large. If @var{x} | |
1187 | is negative, @code{y1} signals a domain error; if it is zero, | |
1188 | @code{y1} signals overflow and returns @math{-@infinity}. | |
1189 | @end deftypefun | |
1190 | ||
1191 | @comment math.h | |
1192 | @comment SVID | |
1193 | @deftypefun double yn (int n, double @var{x}) | |
4260bc74 UD |
1194 | @comment math.h |
1195 | @comment SVID | |
7a68c94a | 1196 | @deftypefunx float ynf (int n, float @var{x}) |
4260bc74 UD |
1197 | @comment math.h |
1198 | @comment SVID | |
7a68c94a UD |
1199 | @deftypefunx {long double} ynl (int n, long double @var{x}) |
1200 | @code{yn} returns the Bessel function of the second kind of order @var{n} of | |
1201 | @var{x}. It may signal underflow if @var{x} is too large. If @var{x} | |
1202 | is negative, @code{yn} signals a domain error; if it is zero, | |
1203 | @code{yn} signals overflow and returns @math{-@infinity}. | |
1204 | @end deftypefun | |
55c14926 | 1205 | |
28f540f4 RM |
1206 | @node Pseudo-Random Numbers |
1207 | @section Pseudo-Random Numbers | |
1208 | @cindex random numbers | |
1209 | @cindex pseudo-random numbers | |
1210 | @cindex seed (for random numbers) | |
1211 | ||
1212 | This section describes the GNU facilities for generating a series of | |
1213 | pseudo-random numbers. The numbers generated are not truly random; | |
7a68c94a UD |
1214 | typically, they form a sequence that repeats periodically, with a period |
1215 | so large that you can ignore it for ordinary purposes. The random | |
1216 | number generator works by remembering a @dfn{seed} value which it uses | |
1217 | to compute the next random number and also to compute a new seed. | |
28f540f4 RM |
1218 | |
1219 | Although the generated numbers look unpredictable within one run of a | |
1220 | program, the sequence of numbers is @emph{exactly the same} from one run | |
1221 | to the next. This is because the initial seed is always the same. This | |
1222 | is convenient when you are debugging a program, but it is unhelpful if | |
7a68c94a UD |
1223 | you want the program to behave unpredictably. If you want a different |
1224 | pseudo-random series each time your program runs, you must specify a | |
1225 | different seed each time. For ordinary purposes, basing the seed on the | |
1226 | current time works well. | |
28f540f4 | 1227 | |
04b9968b | 1228 | You can obtain repeatable sequences of numbers on a particular machine type |
28f540f4 RM |
1229 | by specifying the same initial seed value for the random number |
1230 | generator. There is no standard meaning for a particular seed value; | |
1231 | the same seed, used in different C libraries or on different CPU types, | |
1232 | will give you different random numbers. | |
1233 | ||
f65fd747 | 1234 | The GNU library supports the standard @w{ISO C} random number functions |
7a68c94a UD |
1235 | plus two other sets derived from BSD and SVID. The BSD and @w{ISO C} |
1236 | functions provide identical, somewhat limited functionality. If only a | |
1237 | small number of random bits are required, we recommend you use the | |
1238 | @w{ISO C} interface, @code{rand} and @code{srand}. The SVID functions | |
1239 | provide a more flexible interface, which allows better random number | |
1240 | generator algorithms, provides more random bits (up to 48) per call, and | |
1241 | can provide random floating-point numbers. These functions are required | |
1242 | by the XPG standard and therefore will be present in all modern Unix | |
1243 | systems. | |
28f540f4 RM |
1244 | |
1245 | @menu | |
7a68c94a UD |
1246 | * ISO Random:: @code{rand} and friends. |
1247 | * BSD Random:: @code{random} and friends. | |
1248 | * SVID Random:: @code{drand48} and friends. | |
28f540f4 RM |
1249 | @end menu |
1250 | ||
f65fd747 UD |
1251 | @node ISO Random |
1252 | @subsection ISO C Random Number Functions | |
28f540f4 RM |
1253 | |
1254 | This section describes the random number functions that are part of | |
f65fd747 | 1255 | the @w{ISO C} standard. |
28f540f4 RM |
1256 | |
1257 | To use these facilities, you should include the header file | |
1258 | @file{stdlib.h} in your program. | |
1259 | @pindex stdlib.h | |
1260 | ||
1261 | @comment stdlib.h | |
f65fd747 | 1262 | @comment ISO |
28f540f4 | 1263 | @deftypevr Macro int RAND_MAX |
7a68c94a UD |
1264 | The value of this macro is an integer constant representing the largest |
1265 | value the @code{rand} function can return. In the GNU library, it is | |
1266 | @code{2147483647}, which is the largest signed integer representable in | |
1267 | 32 bits. In other libraries, it may be as low as @code{32767}. | |
28f540f4 RM |
1268 | @end deftypevr |
1269 | ||
1270 | @comment stdlib.h | |
f65fd747 | 1271 | @comment ISO |
ca34d7a7 | 1272 | @deftypefun int rand (void) |
28f540f4 | 1273 | The @code{rand} function returns the next pseudo-random number in the |
7a68c94a | 1274 | series. The value ranges from @code{0} to @code{RAND_MAX}. |
28f540f4 RM |
1275 | @end deftypefun |
1276 | ||
1277 | @comment stdlib.h | |
f65fd747 | 1278 | @comment ISO |
28f540f4 RM |
1279 | @deftypefun void srand (unsigned int @var{seed}) |
1280 | This function establishes @var{seed} as the seed for a new series of | |
1281 | pseudo-random numbers. If you call @code{rand} before a seed has been | |
1282 | established with @code{srand}, it uses the value @code{1} as a default | |
1283 | seed. | |
1284 | ||
7a68c94a UD |
1285 | To produce a different pseudo-random series each time your program is |
1286 | run, do @code{srand (time (0))}. | |
28f540f4 RM |
1287 | @end deftypefun |
1288 | ||
7a68c94a UD |
1289 | POSIX.1 extended the C standard functions to support reproducible random |
1290 | numbers in multi-threaded programs. However, the extension is badly | |
1291 | designed and unsuitable for serious work. | |
61eb22d3 UD |
1292 | |
1293 | @comment stdlib.h | |
1294 | @comment POSIX.1 | |
1295 | @deftypefun int rand_r (unsigned int *@var{seed}) | |
1296 | This function returns a random number in the range 0 to @code{RAND_MAX} | |
7a68c94a UD |
1297 | just as @code{rand} does. However, all its state is stored in the |
1298 | @var{seed} argument. This means the RNG's state can only have as many | |
1299 | bits as the type @code{unsigned int} has. This is far too few to | |
1300 | provide a good RNG. | |
61eb22d3 | 1301 | |
7a68c94a UD |
1302 | If your program requires a reentrant RNG, we recommend you use the |
1303 | reentrant GNU extensions to the SVID random number generator. The | |
1304 | POSIX.1 interface should only be used when the GNU extensions are not | |
1305 | available. | |
61eb22d3 UD |
1306 | @end deftypefun |
1307 | ||
1308 | ||
28f540f4 RM |
1309 | @node BSD Random |
1310 | @subsection BSD Random Number Functions | |
1311 | ||
1312 | This section describes a set of random number generation functions that | |
1313 | are derived from BSD. There is no advantage to using these functions | |
1314 | with the GNU C library; we support them for BSD compatibility only. | |
1315 | ||
1316 | The prototypes for these functions are in @file{stdlib.h}. | |
1317 | @pindex stdlib.h | |
1318 | ||
1319 | @comment stdlib.h | |
1320 | @comment BSD | |
ca34d7a7 | 1321 | @deftypefun {int32_t} random (void) |
28f540f4 | 1322 | This function returns the next pseudo-random number in the sequence. |
7a68c94a | 1323 | The value returned ranges from @code{0} to @code{RAND_MAX}. |
ca34d7a7 | 1324 | |
04b9968b UD |
1325 | @strong{Note:} Historically this function returned a @code{long int} |
1326 | value. On 64-bit systems @code{long int} would have been larger than | |
1327 | programs expected, so @code{random} is now defined to return exactly 32 | |
1328 | bits. | |
28f540f4 RM |
1329 | @end deftypefun |
1330 | ||
1331 | @comment stdlib.h | |
1332 | @comment BSD | |
1333 | @deftypefun void srandom (unsigned int @var{seed}) | |
7a68c94a UD |
1334 | The @code{srandom} function sets the state of the random number |
1335 | generator based on the integer @var{seed}. If you supply a @var{seed} value | |
28f540f4 RM |
1336 | of @code{1}, this will cause @code{random} to reproduce the default set |
1337 | of random numbers. | |
1338 | ||
7a68c94a UD |
1339 | To produce a different set of pseudo-random numbers each time your |
1340 | program runs, do @code{srandom (time (0))}. | |
28f540f4 RM |
1341 | @end deftypefun |
1342 | ||
1343 | @comment stdlib.h | |
1344 | @comment BSD | |
1345 | @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size}) | |
1346 | The @code{initstate} function is used to initialize the random number | |
1347 | generator state. The argument @var{state} is an array of @var{size} | |
7a68c94a UD |
1348 | bytes, used to hold the state information. It is initialized based on |
1349 | @var{seed}. The size must be between 8 and 256 bytes, and should be a | |
1350 | power of two. The bigger the @var{state} array, the better. | |
28f540f4 RM |
1351 | |
1352 | The return value is the previous value of the state information array. | |
1353 | You can use this value later as an argument to @code{setstate} to | |
1354 | restore that state. | |
1355 | @end deftypefun | |
1356 | ||
1357 | @comment stdlib.h | |
1358 | @comment BSD | |
1359 | @deftypefun {void *} setstate (void *@var{state}) | |
1360 | The @code{setstate} function restores the random number state | |
1361 | information @var{state}. The argument must have been the result of | |
2c6fe0bd | 1362 | a previous call to @var{initstate} or @var{setstate}. |
28f540f4 RM |
1363 | |
1364 | The return value is the previous value of the state information array. | |
f2ea0f5b | 1365 | You can use this value later as an argument to @code{setstate} to |
28f540f4 RM |
1366 | restore that state. |
1367 | @end deftypefun | |
b4012b75 | 1368 | |
b4012b75 UD |
1369 | @node SVID Random |
1370 | @subsection SVID Random Number Function | |
1371 | ||
1372 | The C library on SVID systems contains yet another kind of random number | |
1373 | generator functions. They use a state of 48 bits of data. The user can | |
7a68c94a | 1374 | choose among a collection of functions which return the random bits |
b4012b75 UD |
1375 | in different forms. |
1376 | ||
04b9968b | 1377 | Generally there are two kinds of function. The first uses a state of |
b4012b75 | 1378 | the random number generator which is shared among several functions and |
04b9968b UD |
1379 | by all threads of the process. The second requires the user to handle |
1380 | the state. | |
b4012b75 UD |
1381 | |
1382 | All functions have in common that they use the same congruential | |
1383 | formula with the same constants. The formula is | |
1384 | ||
1385 | @smallexample | |
1386 | Y = (a * X + c) mod m | |
1387 | @end smallexample | |
1388 | ||
1389 | @noindent | |
1390 | where @var{X} is the state of the generator at the beginning and | |
1391 | @var{Y} the state at the end. @code{a} and @code{c} are constants | |
04b9968b | 1392 | determining the way the generator works. By default they are |
b4012b75 UD |
1393 | |
1394 | @smallexample | |
1395 | a = 0x5DEECE66D = 25214903917 | |
1396 | c = 0xb = 11 | |
1397 | @end smallexample | |
1398 | ||
1399 | @noindent | |
1400 | but they can also be changed by the user. @code{m} is of course 2^48 | |
04b9968b | 1401 | since the state consists of a 48-bit array. |
b4012b75 UD |
1402 | |
1403 | ||
1404 | @comment stdlib.h | |
1405 | @comment SVID | |
55c14926 | 1406 | @deftypefun double drand48 (void) |
b4012b75 UD |
1407 | This function returns a @code{double} value in the range of @code{0.0} |
1408 | to @code{1.0} (exclusive). The random bits are determined by the global | |
1409 | state of the random number generator in the C library. | |
1410 | ||
04b9968b | 1411 | Since the @code{double} type according to @w{IEEE 754} has a 52-bit |
b4012b75 UD |
1412 | mantissa this means 4 bits are not initialized by the random number |
1413 | generator. These are (of course) chosen to be the least significant | |
1414 | bits and they are initialized to @code{0}. | |
1415 | @end deftypefun | |
1416 | ||
1417 | @comment stdlib.h | |
1418 | @comment SVID | |
1419 | @deftypefun double erand48 (unsigned short int @var{xsubi}[3]) | |
1420 | This function returns a @code{double} value in the range of @code{0.0} | |
04b9968b | 1421 | to @code{1.0} (exclusive), similarly to @code{drand48}. The argument is |
b4012b75 UD |
1422 | an array describing the state of the random number generator. |
1423 | ||
1424 | This function can be called subsequently since it updates the array to | |
1425 | guarantee random numbers. The array should have been initialized before | |
04b9968b | 1426 | initial use to obtain reproducible results. |
b4012b75 UD |
1427 | @end deftypefun |
1428 | ||
1429 | @comment stdlib.h | |
1430 | @comment SVID | |
55c14926 | 1431 | @deftypefun {long int} lrand48 (void) |
04b9968b | 1432 | The @code{lrand48} function returns an integer value in the range of |
b4012b75 | 1433 | @code{0} to @code{2^31} (exclusive). Even if the size of the @code{long |
04b9968b | 1434 | int} type can take more than 32 bits, no higher numbers are returned. |
b4012b75 UD |
1435 | The random bits are determined by the global state of the random number |
1436 | generator in the C library. | |
1437 | @end deftypefun | |
1438 | ||
1439 | @comment stdlib.h | |
1440 | @comment SVID | |
1441 | @deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3]) | |
1442 | This function is similar to the @code{lrand48} function in that it | |
1443 | returns a number in the range of @code{0} to @code{2^31} (exclusive) but | |
1444 | the state of the random number generator used to produce the random bits | |
1445 | is determined by the array provided as the parameter to the function. | |
1446 | ||
04b9968b UD |
1447 | The numbers in the array are updated afterwards so that subsequent calls |
1448 | to this function yield different results (as is expected of a random | |
1449 | number generator). The array should have been initialized before the | |
1450 | first call to obtain reproducible results. | |
b4012b75 UD |
1451 | @end deftypefun |
1452 | ||
1453 | @comment stdlib.h | |
1454 | @comment SVID | |
55c14926 | 1455 | @deftypefun {long int} mrand48 (void) |
b4012b75 UD |
1456 | The @code{mrand48} function is similar to @code{lrand48}. The only |
1457 | difference is that the numbers returned are in the range @code{-2^31} to | |
1458 | @code{2^31} (exclusive). | |
1459 | @end deftypefun | |
1460 | ||
1461 | @comment stdlib.h | |
1462 | @comment SVID | |
1463 | @deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3]) | |
1464 | The @code{jrand48} function is similar to @code{nrand48}. The only | |
1465 | difference is that the numbers returned are in the range @code{-2^31} to | |
1466 | @code{2^31} (exclusive). For the @code{xsubi} parameter the same | |
1467 | requirements are necessary. | |
1468 | @end deftypefun | |
1469 | ||
1470 | The internal state of the random number generator can be initialized in | |
04b9968b | 1471 | several ways. The methods differ in the completeness of the |
b4012b75 UD |
1472 | information provided. |
1473 | ||
1474 | @comment stdlib.h | |
1475 | @comment SVID | |
04b9968b | 1476 | @deftypefun void srand48 (long int @var{seedval}) |
b4012b75 | 1477 | The @code{srand48} function sets the most significant 32 bits of the |
04b9968b | 1478 | internal state of the random number generator to the least |
f2ea0f5b UD |
1479 | significant 32 bits of the @var{seedval} parameter. The lower 16 bits |
1480 | are initialized to the value @code{0x330E}. Even if the @code{long | |
04b9968b | 1481 | int} type contains more than 32 bits only the lower 32 bits are used. |
b4012b75 | 1482 | |
04b9968b UD |
1483 | Owing to this limitation, initialization of the state of this |
1484 | function is not very useful. But it makes it easy to use a construct | |
b4012b75 UD |
1485 | like @code{srand48 (time (0))}. |
1486 | ||
1487 | A side-effect of this function is that the values @code{a} and @code{c} | |
1488 | from the internal state, which are used in the congruential formula, | |
1489 | are reset to the default values given above. This is of importance once | |
04b9968b | 1490 | the user has called the @code{lcong48} function (see below). |
b4012b75 UD |
1491 | @end deftypefun |
1492 | ||
1493 | @comment stdlib.h | |
1494 | @comment SVID | |
1495 | @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3]) | |
1496 | The @code{seed48} function initializes all 48 bits of the state of the | |
04b9968b | 1497 | internal random number generator from the contents of the parameter |
b4012b75 UD |
1498 | @var{seed16v}. Here the lower 16 bits of the first element of |
1499 | @var{see16v} initialize the least significant 16 bits of the internal | |
1500 | state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order | |
1501 | 16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]} | |
1502 | initialize the most significant 16 bits of the state. | |
1503 | ||
1504 | Unlike @code{srand48} this function lets the user initialize all 48 bits | |
1505 | of the state. | |
1506 | ||
1507 | The value returned by @code{seed48} is a pointer to an array containing | |
1508 | the values of the internal state before the change. This might be | |
1509 | useful to restart the random number generator at a certain state. | |
04b9968b | 1510 | Otherwise the value can simply be ignored. |
b4012b75 UD |
1511 | |
1512 | As for @code{srand48}, the values @code{a} and @code{c} from the | |
1513 | congruential formula are reset to the default values. | |
1514 | @end deftypefun | |
1515 | ||
1516 | There is one more function to initialize the random number generator | |
04b9968b UD |
1517 | which enables you to specify even more information by allowing you to |
1518 | change the parameters in the congruential formula. | |
b4012b75 UD |
1519 | |
1520 | @comment stdlib.h | |
1521 | @comment SVID | |
1522 | @deftypefun void lcong48 (unsigned short int @var{param}[7]) | |
1523 | The @code{lcong48} function allows the user to change the complete state | |
1524 | of the random number generator. Unlike @code{srand48} and | |
1525 | @code{seed48}, this function also changes the constants in the | |
1526 | congruential formula. | |
1527 | ||
1528 | From the seven elements in the array @var{param} the least significant | |
1529 | 16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]} | |
04b9968b | 1530 | determine the initial state, the least significant 16 bits of |
b4012b75 | 1531 | @code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit |
04b9968b | 1532 | constant @code{a} and @code{@var{param}[6]} determines the 16-bit value |
b4012b75 UD |
1533 | @code{c}. |
1534 | @end deftypefun | |
1535 | ||
1536 | All the above functions have in common that they use the global | |
1537 | parameters for the congruential formula. In multi-threaded programs it | |
1538 | might sometimes be useful to have different parameters in different | |
1539 | threads. For this reason all the above functions have a counterpart | |
1540 | which works on a description of the random number generator in the | |
1541 | user-supplied buffer instead of the global state. | |
1542 | ||
1543 | Please note that it is no problem if several threads use the global | |
1544 | state if all threads use the functions which take a pointer to an array | |
1545 | containing the state. The random numbers are computed following the | |
1546 | same loop but if the state in the array is different all threads will | |
04b9968b | 1547 | obtain an individual random number generator. |
b4012b75 | 1548 | |
04b9968b UD |
1549 | The user-supplied buffer must be of type @code{struct drand48_data}. |
1550 | This type should be regarded as opaque and not manipulated directly. | |
b4012b75 UD |
1551 | |
1552 | @comment stdlib.h | |
1553 | @comment GNU | |
1554 | @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result}) | |
1555 | This function is equivalent to the @code{drand48} function with the | |
04b9968b UD |
1556 | difference that it does not modify the global random number generator |
1557 | parameters but instead the parameters in the buffer supplied through the | |
1558 | pointer @var{buffer}. The random number is returned in the variable | |
1559 | pointed to by @var{result}. | |
b4012b75 | 1560 | |
04b9968b | 1561 | The return value of the function indicates whether the call succeeded. |
b4012b75 UD |
1562 | If the value is less than @code{0} an error occurred and @var{errno} is |
1563 | set to indicate the problem. | |
1564 | ||
1565 | This function is a GNU extension and should not be used in portable | |
1566 | programs. | |
1567 | @end deftypefun | |
1568 | ||
1569 | @comment stdlib.h | |
1570 | @comment GNU | |
1571 | @deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result}) | |
04b9968b UD |
1572 | The @code{erand48_r} function works like @code{erand48}, but in addition |
1573 | it takes an argument @var{buffer} which describes the random number | |
1574 | generator. The state of the random number generator is taken from the | |
1575 | @code{xsubi} array, the parameters for the congruential formula from the | |
1576 | global random number generator data. The random number is returned in | |
1577 | the variable pointed to by @var{result}. | |
b4012b75 | 1578 | |
04b9968b | 1579 | The return value is non-negative if the call succeeded. |
b4012b75 UD |
1580 | |
1581 | This function is a GNU extension and should not be used in portable | |
1582 | programs. | |
1583 | @end deftypefun | |
1584 | ||
1585 | @comment stdlib.h | |
1586 | @comment GNU | |
1587 | @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result}) | |
04b9968b UD |
1588 | This function is similar to @code{lrand48}, but in addition it takes a |
1589 | pointer to a buffer describing the state of the random number generator | |
1590 | just like @code{drand48}. | |
b4012b75 UD |
1591 | |
1592 | If the return value of the function is non-negative the variable pointed | |
1593 | to by @var{result} contains the result. Otherwise an error occurred. | |
1594 | ||
1595 | This function is a GNU extension and should not be used in portable | |
1596 | programs. | |
1597 | @end deftypefun | |
1598 | ||
1599 | @comment stdlib.h | |
1600 | @comment GNU | |
1601 | @deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result}) | |
1602 | The @code{nrand48_r} function works like @code{nrand48} in that it | |
04b9968b | 1603 | produces a random number in the range @code{0} to @code{2^31}. But instead |
b4012b75 UD |
1604 | of using the global parameters for the congruential formula it uses the |
1605 | information from the buffer pointed to by @var{buffer}. The state is | |
1606 | described by the values in @var{xsubi}. | |
1607 | ||
1608 | If the return value is non-negative the variable pointed to by | |
1609 | @var{result} contains the result. | |
1610 | ||
1611 | This function is a GNU extension and should not be used in portable | |
1612 | programs. | |
1613 | @end deftypefun | |
1614 | ||
1615 | @comment stdlib.h | |
1616 | @comment GNU | |
1617 | @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result}) | |
04b9968b UD |
1618 | This function is similar to @code{mrand48} but like the other reentrant |
1619 | functions it uses the random number generator described by the value in | |
b4012b75 UD |
1620 | the buffer pointed to by @var{buffer}. |
1621 | ||
1622 | If the return value is non-negative the variable pointed to by | |
1623 | @var{result} contains the result. | |
1624 | ||
1625 | This function is a GNU extension and should not be used in portable | |
1626 | programs. | |
1627 | @end deftypefun | |
1628 | ||
1629 | @comment stdlib.h | |
1630 | @comment GNU | |
1631 | @deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result}) | |
04b9968b | 1632 | The @code{jrand48_r} function is similar to @code{jrand48}. Like the |
b4012b75 UD |
1633 | other reentrant functions of this function family it uses the |
1634 | congruential formula parameters from the buffer pointed to by | |
1635 | @var{buffer}. | |
1636 | ||
1637 | If the return value is non-negative the variable pointed to by | |
1638 | @var{result} contains the result. | |
1639 | ||
1640 | This function is a GNU extension and should not be used in portable | |
1641 | programs. | |
1642 | @end deftypefun | |
1643 | ||
04b9968b UD |
1644 | Before any of the above functions are used the buffer of type |
1645 | @code{struct drand48_data} should be initialized. The easiest way to do | |
1646 | this is to fill the whole buffer with null bytes, e.g. by | |
b4012b75 UD |
1647 | |
1648 | @smallexample | |
1649 | memset (buffer, '\0', sizeof (struct drand48_data)); | |
1650 | @end smallexample | |
1651 | ||
1652 | @noindent | |
f2ea0f5b | 1653 | Using any of the reentrant functions of this family now will |
b4012b75 UD |
1654 | automatically initialize the random number generator to the default |
1655 | values for the state and the parameters of the congruential formula. | |
1656 | ||
04b9968b | 1657 | The other possibility is to use any of the functions which explicitly |
b4012b75 | 1658 | initialize the buffer. Though it might be obvious how to initialize the |
04b9968b | 1659 | buffer from looking at the parameter to the function, it is highly |
b4012b75 UD |
1660 | recommended to use these functions since the result might not always be |
1661 | what you expect. | |
1662 | ||
1663 | @comment stdlib.h | |
1664 | @comment GNU | |
1665 | @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer}) | |
1666 | The description of the random number generator represented by the | |
04b9968b | 1667 | information in @var{buffer} is initialized similarly to what the function |
f2ea0f5b UD |
1668 | @code{srand48} does. The state is initialized from the parameter |
1669 | @var{seedval} and the parameters for the congruential formula are | |
04b9968b | 1670 | initialized to their default values. |
b4012b75 UD |
1671 | |
1672 | If the return value is non-negative the function call succeeded. | |
1673 | ||
1674 | This function is a GNU extension and should not be used in portable | |
1675 | programs. | |
1676 | @end deftypefun | |
1677 | ||
1678 | @comment stdlib.h | |
1679 | @comment GNU | |
1680 | @deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer}) | |
1681 | This function is similar to @code{srand48_r} but like @code{seed48} it | |
1682 | initializes all 48 bits of the state from the parameter @var{seed16v}. | |
1683 | ||
1684 | If the return value is non-negative the function call succeeded. It | |
1685 | does not return a pointer to the previous state of the random number | |
04b9968b UD |
1686 | generator like the @code{seed48} function does. If the user wants to |
1687 | preserve the state for a later re-run s/he can copy the whole buffer | |
b4012b75 UD |
1688 | pointed to by @var{buffer}. |
1689 | ||
1690 | This function is a GNU extension and should not be used in portable | |
1691 | programs. | |
1692 | @end deftypefun | |
1693 | ||
1694 | @comment stdlib.h | |
1695 | @comment GNU | |
1696 | @deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer}) | |
1697 | This function initializes all aspects of the random number generator | |
04b9968b UD |
1698 | described in @var{buffer} with the data in @var{param}. Here it is |
1699 | especially true that the function does more than just copying the | |
1700 | contents of @var{param} and @var{buffer}. More work is required and | |
1701 | therefore it is important to use this function rather than initializing | |
1702 | the random number generator directly. | |
b4012b75 UD |
1703 | |
1704 | If the return value is non-negative the function call succeeded. | |
1705 | ||
1706 | This function is a GNU extension and should not be used in portable | |
1707 | programs. | |
1708 | @end deftypefun | |
7a68c94a UD |
1709 | |
1710 | @node FP Function Optimizations | |
1711 | @section Is Fast Code or Small Code preferred? | |
1712 | @cindex Optimization | |
1713 | ||
04b9968b UD |
1714 | If an application uses many floating point functions it is often the case |
1715 | that the cost of the function calls themselves is not negligible. | |
1716 | Modern processors can often execute the operations themselves | |
1717 | very fast, but the function call disrupts the instruction pipeline. | |
7a68c94a UD |
1718 | |
1719 | For this reason the GNU C Library provides optimizations for many of the | |
04b9968b UD |
1720 | frequently-used math functions. When GNU CC is used and the user |
1721 | activates the optimizer, several new inline functions and macros are | |
7a68c94a | 1722 | defined. These new functions and macros have the same names as the |
04b9968b | 1723 | library functions and so are used instead of the latter. In the case of |
7a68c94a | 1724 | inline functions the compiler will decide whether it is reasonable to |
04b9968b | 1725 | use them, and this decision is usually correct. |
7a68c94a | 1726 | |
04b9968b UD |
1727 | This means that no calls to the library functions may be necessary, and |
1728 | can increase the speed of generated code significantly. The drawback is | |
1729 | that code size will increase, and the increase is not always negligible. | |
7a68c94a | 1730 | |
aa847ee5 UD |
1731 | The speed increase has one drawback: the inline functions might not set |
1732 | @code{errno} and might not have the same precission as the library | |
1733 | functions. | |
1734 | ||
7a68c94a UD |
1735 | In cases where the inline functions and macros are not wanted the symbol |
1736 | @code{__NO_MATH_INLINES} should be defined before any system header is | |
04b9968b UD |
1737 | included. This will ensure that only library functions are used. Of |
1738 | course, it can be determined for each file in the project whether | |
1739 | giving this option is preferable or not. | |
1740 | ||
1741 | Not all hardware implements the entire @w{IEEE 754} standard, and even | |
1742 | if it does there may be a substantial performance penalty for using some | |
1743 | of its features. For example, enabling traps on some processors forces | |
1744 | the FPU to run un-pipelined, which can more than double calculation time. | |
7a68c94a | 1745 | @c ***Add explanation of -lieee, -mieee. |