]>
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 | |
d52b6462 | 30 | @node Mathematics, Arithmetic, Syslog, 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 | |
ec751a23 UD |
45 | defined in @w{ISO C89}. The @code{float} and @code{long double} |
46 | versions are from the numeric extensions to C included in @w{ISO C99}. | |
7a68c94a UD |
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 | 55 | |
0d93b7fd | 56 | @Theglibc{} also provides @code{_Float@var{N}} and |
7d641c41 GG |
57 | @code{_Float@var{N}x} types. These types are defined in @w{ISO/IEC TS |
58 | 18661-3}, which extends @w{ISO C} and defines floating-point types that | |
59 | are not machine-dependent. When such a type, such as @code{_Float128}, | |
60 | is supported by @theglibc{}, extra variants for most of the mathematical | |
61 | functions provided for @code{double}, @code{float}, and @code{long | |
52a8e5cb GG |
62 | double} are also provided for the supported type. Throughout this |
63 | manual, the @code{_Float@var{N}} and @code{_Float@var{N}x} variants of | |
64 | these functions are described along with the @code{double}, | |
65 | @code{float}, and @code{long double} variants and they come from | |
66 | @w{ISO/IEC TS 18661-3}, unless explicitly stated otherwise. | |
7d641c41 | 67 | |
0d93b7fd | 68 | Support for @code{_Float@var{N}} or @code{_Float@var{N}x} types is |
1f9055ce JM |
69 | provided for @code{_Float32}, @code{_Float64} and @code{_Float32x} on |
70 | all platforms. | |
0d93b7fd | 71 | It is also provided for @code{_Float128} and @code{_Float64x} on |
a23aa5b7 | 72 | powerpc64le (PowerPC 64-bits little-endian), x86_64, x86, ia64, |
40ca951b | 73 | aarch64, alpha, mips64, riscv, s390 and sparc. |
7d641c41 | 74 | |
28f540f4 | 75 | @menu |
7a68c94a UD |
76 | * Mathematical Constants:: Precise numeric values for often-used |
77 | constants. | |
78 | * Trig Functions:: Sine, cosine, tangent, and friends. | |
79 | * Inverse Trig Functions:: Arcsine, arccosine, etc. | |
80 | * Exponents and Logarithms:: Also pow and sqrt. | |
81 | * Hyperbolic Functions:: sinh, cosh, tanh, etc. | |
82 | * Special Functions:: Bessel, gamma, erf. | |
aaa1276e | 83 | * Errors in Math Functions:: Known Maximum Errors in Math Functions. |
7a68c94a UD |
84 | * Pseudo-Random Numbers:: Functions for generating pseudo-random |
85 | numbers. | |
86 | * FP Function Optimizations:: Fast code or small code. | |
28f540f4 RM |
87 | @end menu |
88 | ||
55c14926 UD |
89 | @node Mathematical Constants |
90 | @section Predefined Mathematical Constants | |
91 | @cindex constants | |
92 | @cindex mathematical constants | |
93 | ||
7a68c94a UD |
94 | The header @file{math.h} defines several useful mathematical constants. |
95 | All values are defined as preprocessor macros starting with @code{M_}. | |
96 | The values provided are: | |
55c14926 UD |
97 | |
98 | @vtable @code | |
99 | @item M_E | |
7a68c94a | 100 | The base of natural logarithms. |
55c14926 | 101 | @item M_LOG2E |
7a68c94a | 102 | The logarithm to base @code{2} of @code{M_E}. |
55c14926 | 103 | @item M_LOG10E |
7a68c94a | 104 | The logarithm to base @code{10} of @code{M_E}. |
55c14926 | 105 | @item M_LN2 |
7a68c94a | 106 | The natural logarithm of @code{2}. |
55c14926 | 107 | @item M_LN10 |
7a68c94a | 108 | The natural logarithm of @code{10}. |
55c14926 | 109 | @item M_PI |
04b9968b | 110 | Pi, the ratio of a circle's circumference to its diameter. |
55c14926 | 111 | @item M_PI_2 |
7a68c94a | 112 | Pi divided by two. |
55c14926 | 113 | @item M_PI_4 |
7a68c94a | 114 | Pi divided by four. |
55c14926 | 115 | @item M_1_PI |
7a68c94a | 116 | The reciprocal of pi (1/pi) |
55c14926 | 117 | @item M_2_PI |
7a68c94a | 118 | Two times the reciprocal of pi. |
55c14926 | 119 | @item M_2_SQRTPI |
7a68c94a | 120 | Two times the reciprocal of the square root of pi. |
55c14926 | 121 | @item M_SQRT2 |
7a68c94a | 122 | The square root of two. |
55c14926 | 123 | @item M_SQRT1_2 |
7a68c94a | 124 | The reciprocal of the square root of two (also the square root of 1/2). |
55c14926 UD |
125 | @end vtable |
126 | ||
7a68c94a | 127 | These constants come from the Unix98 standard and were also available in |
c941736c | 128 | 4.4BSD; therefore they are only defined if |
7a68c94a UD |
129 | @code{_XOPEN_SOURCE=500}, or a more general feature select macro, is |
130 | defined. The default set of features includes these constants. | |
131 | @xref{Feature Test Macros}. | |
132 | ||
1f77f049 JM |
133 | All values are of type @code{double}. As an extension, @theglibc{} |
134 | also defines these constants with type @code{long double}. The | |
7a68c94a UD |
135 | @code{long double} macros have a lowercase @samp{l} appended to their |
136 | names: @code{M_El}, @code{M_PIl}, and so forth. These are only | |
137 | available if @code{_GNU_SOURCE} is defined. | |
55c14926 | 138 | |
52a8e5cb GG |
139 | Likewise, @theglibc{} also defines these constants with the types |
140 | @code{_Float@var{N}} and @code{_Float@var{N}x} for the machines that | |
141 | have support for such types enabled (@pxref{Mathematics}) and if | |
142 | @code{_GNU_SOURCE} is defined. When available, the macros names are | |
143 | appended with @samp{f@var{N}} or @samp{f@var{N}x}, such as @samp{f128} | |
144 | for the type @code{_Float128}. | |
145 | ||
55c14926 UD |
146 | @vindex PI |
147 | @emph{Note:} Some programs use a constant named @code{PI} which has the | |
7a68c94a UD |
148 | same value as @code{M_PI}. This constant is not standard; it may have |
149 | appeared in some old AT&T headers, and is mentioned in Stroustrup's book | |
1f77f049 | 150 | on C++. It infringes on the user's name space, so @theglibc{} |
7a68c94a UD |
151 | does not define it. Fixing programs written to expect it is simple: |
152 | replace @code{PI} with @code{M_PI} throughout, or put @samp{-DPI=M_PI} | |
153 | on the compiler command line. | |
61eb22d3 | 154 | |
28f540f4 RM |
155 | @node Trig Functions |
156 | @section Trigonometric Functions | |
157 | @cindex trigonometric functions | |
158 | ||
159 | These are the familiar @code{sin}, @code{cos}, and @code{tan} functions. | |
160 | The arguments to all of these functions are in units of radians; recall | |
161 | that pi radians equals 180 degrees. | |
162 | ||
163 | @cindex pi (trigonometric constant) | |
7a68c94a UD |
164 | The math library normally defines @code{M_PI} to a @code{double} |
165 | approximation of pi. If strict ISO and/or POSIX compliance | |
166 | are requested this constant is not defined, but you can easily define it | |
167 | yourself: | |
28f540f4 RM |
168 | |
169 | @smallexample | |
b4012b75 | 170 | #define M_PI 3.14159265358979323846264338327 |
28f540f4 RM |
171 | @end smallexample |
172 | ||
173 | @noindent | |
174 | You can also compute the value of pi with the expression @code{acos | |
175 | (-1.0)}. | |
176 | ||
28f540f4 | 177 | @deftypefun double sin (double @var{x}) |
779ae82e UD |
178 | @deftypefunx float sinf (float @var{x}) |
179 | @deftypefunx {long double} sinl (long double @var{x}) | |
52a8e5cb GG |
180 | @deftypefunx _FloatN sinfN (_Float@var{N} @var{x}) |
181 | @deftypefunx _FloatNx sinfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 182 | @standards{ISO, math.h} |
52a8e5cb GG |
183 | @standardsx{sinfN, TS 18661-3:2015, math.h} |
184 | @standardsx{sinfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 185 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 186 | These functions return the sine of @var{x}, where @var{x} is given in |
28f540f4 RM |
187 | radians. The return value is in the range @code{-1} to @code{1}. |
188 | @end deftypefun | |
189 | ||
28f540f4 | 190 | @deftypefun double cos (double @var{x}) |
779ae82e UD |
191 | @deftypefunx float cosf (float @var{x}) |
192 | @deftypefunx {long double} cosl (long double @var{x}) | |
52a8e5cb GG |
193 | @deftypefunx _FloatN cosfN (_Float@var{N} @var{x}) |
194 | @deftypefunx _FloatNx cosfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 195 | @standards{ISO, math.h} |
52a8e5cb GG |
196 | @standardsx{cosfN, TS 18661-3:2015, math.h} |
197 | @standardsx{cosfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 198 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 199 | These functions return the cosine of @var{x}, where @var{x} is given in |
28f540f4 RM |
200 | radians. The return value is in the range @code{-1} to @code{1}. |
201 | @end deftypefun | |
202 | ||
28f540f4 | 203 | @deftypefun double tan (double @var{x}) |
779ae82e UD |
204 | @deftypefunx float tanf (float @var{x}) |
205 | @deftypefunx {long double} tanl (long double @var{x}) | |
52a8e5cb GG |
206 | @deftypefunx _FloatN tanfN (_Float@var{N} @var{x}) |
207 | @deftypefunx _FloatNx tanfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 208 | @standards{ISO, math.h} |
52a8e5cb GG |
209 | @standardsx{tanfN, TS 18661-3:2015, math.h} |
210 | @standardsx{tanfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 211 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 212 | These functions return the tangent of @var{x}, where @var{x} is given in |
28f540f4 RM |
213 | radians. |
214 | ||
28f540f4 RM |
215 | Mathematically, the tangent function has singularities at odd multiples |
216 | of pi/2. If the argument @var{x} is too close to one of these | |
7a68c94a | 217 | singularities, @code{tan} will signal overflow. |
28f540f4 RM |
218 | @end deftypefun |
219 | ||
7a68c94a UD |
220 | In many applications where @code{sin} and @code{cos} are used, the sine |
221 | and cosine of the same angle are needed at the same time. It is more | |
222 | efficient to compute them simultaneously, so the library provides a | |
223 | function to do that. | |
b4012b75 | 224 | |
b4012b75 | 225 | @deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx}) |
779ae82e UD |
226 | @deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx}) |
227 | @deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx}) | |
52a8e5cb GG |
228 | @deftypefunx _FloatN sincosfN (_Float@var{N} @var{x}, _Float@var{N} *@var{sinx}, _Float@var{N} *@var{cosx}) |
229 | @deftypefunx _FloatNx sincosfNx (_Float@var{N}x @var{x}, _Float@var{N}x *@var{sinx}, _Float@var{N}x *@var{cosx}) | |
d08a7e4c | 230 | @standards{GNU, math.h} |
27aaa791 | 231 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 232 | These functions return the sine of @var{x} in @code{*@var{sinx}} and the |
60843ffb | 233 | cosine of @var{x} in @code{*@var{cosx}}, where @var{x} is given in |
b4012b75 UD |
234 | radians. Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in |
235 | the range of @code{-1} to @code{1}. | |
ca34d7a7 | 236 | |
52a8e5cb GG |
237 | All these functions, including the @code{_Float@var{N}} and |
238 | @code{_Float@var{N}x} variants, are GNU extensions. Portable programs | |
d9660db2 | 239 | should be prepared to cope with their absence. |
b4012b75 UD |
240 | @end deftypefun |
241 | ||
242 | @cindex complex trigonometric functions | |
243 | ||
ec751a23 | 244 | @w{ISO C99} defines variants of the trig functions which work on |
1f77f049 | 245 | complex numbers. @Theglibc{} provides these functions, but they |
7a68c94a UD |
246 | are only useful if your compiler supports the new complex types defined |
247 | by the standard. | |
ec751a23 | 248 | @c XXX Change this when gcc is fixed. -zw |
7a68c94a UD |
249 | (As of this writing GCC supports complex numbers, but there are bugs in |
250 | the implementation.) | |
b4012b75 | 251 | |
b4012b75 | 252 | @deftypefun {complex double} csin (complex double @var{z}) |
779ae82e UD |
253 | @deftypefunx {complex float} csinf (complex float @var{z}) |
254 | @deftypefunx {complex long double} csinl (complex long double @var{z}) | |
52a8e5cb GG |
255 | @deftypefunx {complex _FloatN} csinfN (complex _Float@var{N} @var{z}) |
256 | @deftypefunx {complex _FloatNx} csinfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 257 | @standards{ISO, complex.h} |
52a8e5cb GG |
258 | @standardsx{csinfN, TS 18661-3:2015, complex.h} |
259 | @standardsx{csinfNx, TS 18661-3:2015, complex.h} | |
27aaa791 AO |
260 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
261 | @c There are calls to nan* that could trigger @mtslocale if they didn't get | |
262 | @c empty strings. | |
7a68c94a | 263 | These functions return the complex sine of @var{z}. |
b4012b75 UD |
264 | The mathematical definition of the complex sine is |
265 | ||
4c78249d | 266 | @ifnottex |
779ae82e | 267 | @math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}. |
4c78249d | 268 | @end ifnottex |
779ae82e UD |
269 | @tex |
270 | $$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$ | |
271 | @end tex | |
b4012b75 UD |
272 | @end deftypefun |
273 | ||
b4012b75 | 274 | @deftypefun {complex double} ccos (complex double @var{z}) |
779ae82e UD |
275 | @deftypefunx {complex float} ccosf (complex float @var{z}) |
276 | @deftypefunx {complex long double} ccosl (complex long double @var{z}) | |
52a8e5cb GG |
277 | @deftypefunx {complex _FloatN} ccosfN (complex _Float@var{N} @var{z}) |
278 | @deftypefunx {complex _FloatNx} ccosfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 279 | @standards{ISO, complex.h} |
52a8e5cb GG |
280 | @standardsx{ccosfN, TS 18661-3:2015, complex.h} |
281 | @standardsx{ccosfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 282 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a | 283 | These functions return the complex cosine of @var{z}. |
b4012b75 UD |
284 | The mathematical definition of the complex cosine is |
285 | ||
4c78249d | 286 | @ifnottex |
779ae82e | 287 | @math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))} |
4c78249d | 288 | @end ifnottex |
779ae82e UD |
289 | @tex |
290 | $$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$ | |
291 | @end tex | |
b4012b75 UD |
292 | @end deftypefun |
293 | ||
b4012b75 | 294 | @deftypefun {complex double} ctan (complex double @var{z}) |
779ae82e UD |
295 | @deftypefunx {complex float} ctanf (complex float @var{z}) |
296 | @deftypefunx {complex long double} ctanl (complex long double @var{z}) | |
52a8e5cb GG |
297 | @deftypefunx {complex _FloatN} ctanfN (complex _Float@var{N} @var{z}) |
298 | @deftypefunx {complex _FloatNx} ctanfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 299 | @standards{ISO, complex.h} |
52a8e5cb GG |
300 | @standardsx{ctanfN, TS 18661-3:2015, complex.h} |
301 | @standardsx{ctanfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 302 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a | 303 | These functions return the complex tangent of @var{z}. |
b4012b75 UD |
304 | The mathematical definition of the complex tangent is |
305 | ||
4c78249d | 306 | @ifnottex |
7a68c94a | 307 | @math{tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))} |
4c78249d | 308 | @end ifnottex |
779ae82e | 309 | @tex |
7a68c94a | 310 | $$\tan(z) = -i \cdot {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$ |
779ae82e | 311 | @end tex |
7a68c94a UD |
312 | |
313 | @noindent | |
314 | The complex tangent has poles at @math{pi/2 + 2n}, where @math{n} is an | |
315 | integer. @code{ctan} may signal overflow if @var{z} is too close to a | |
316 | pole. | |
b4012b75 UD |
317 | @end deftypefun |
318 | ||
28f540f4 RM |
319 | |
320 | @node Inverse Trig Functions | |
321 | @section Inverse Trigonometric Functions | |
6d52618b | 322 | @cindex inverse trigonometric functions |
28f540f4 | 323 | |
60843ffb | 324 | These are the usual arcsine, arccosine and arctangent functions, |
04b9968b | 325 | which are the inverses of the sine, cosine and tangent functions |
28f540f4 RM |
326 | respectively. |
327 | ||
28f540f4 | 328 | @deftypefun double asin (double @var{x}) |
779ae82e UD |
329 | @deftypefunx float asinf (float @var{x}) |
330 | @deftypefunx {long double} asinl (long double @var{x}) | |
52a8e5cb GG |
331 | @deftypefunx _FloatN asinfN (_Float@var{N} @var{x}) |
332 | @deftypefunx _FloatNx asinfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 333 | @standards{ISO, math.h} |
52a8e5cb GG |
334 | @standardsx{asinfN, TS 18661-3:2015, math.h} |
335 | @standardsx{asinfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 336 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
60843ffb | 337 | These functions compute the arcsine of @var{x}---that is, the value whose |
28f540f4 RM |
338 | sine is @var{x}. The value is in units of radians. Mathematically, |
339 | there are infinitely many such values; the one actually returned is the | |
340 | one between @code{-pi/2} and @code{pi/2} (inclusive). | |
341 | ||
60843ffb | 342 | The arcsine function is defined mathematically only |
7a68c94a UD |
343 | over the domain @code{-1} to @code{1}. If @var{x} is outside the |
344 | domain, @code{asin} signals a domain error. | |
28f540f4 RM |
345 | @end deftypefun |
346 | ||
28f540f4 | 347 | @deftypefun double acos (double @var{x}) |
779ae82e UD |
348 | @deftypefunx float acosf (float @var{x}) |
349 | @deftypefunx {long double} acosl (long double @var{x}) | |
52a8e5cb GG |
350 | @deftypefunx _FloatN acosfN (_Float@var{N} @var{x}) |
351 | @deftypefunx _FloatNx acosfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 352 | @standards{ISO, math.h} |
52a8e5cb GG |
353 | @standardsx{acosfN, TS 18661-3:2015, math.h} |
354 | @standardsx{acosfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 355 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
60843ffb | 356 | These functions compute the arccosine of @var{x}---that is, the value |
28f540f4 RM |
357 | whose cosine is @var{x}. The value is in units of radians. |
358 | Mathematically, there are infinitely many such values; the one actually | |
359 | returned is the one between @code{0} and @code{pi} (inclusive). | |
360 | ||
60843ffb | 361 | The arccosine function is defined mathematically only |
7a68c94a UD |
362 | over the domain @code{-1} to @code{1}. If @var{x} is outside the |
363 | domain, @code{acos} signals a domain error. | |
28f540f4 RM |
364 | @end deftypefun |
365 | ||
28f540f4 | 366 | @deftypefun double atan (double @var{x}) |
779ae82e UD |
367 | @deftypefunx float atanf (float @var{x}) |
368 | @deftypefunx {long double} atanl (long double @var{x}) | |
52a8e5cb GG |
369 | @deftypefunx _FloatN atanfN (_Float@var{N} @var{x}) |
370 | @deftypefunx _FloatNx atanfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 371 | @standards{ISO, math.h} |
52a8e5cb GG |
372 | @standardsx{atanfN, TS 18661-3:2015, math.h} |
373 | @standardsx{atanfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 374 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
60843ffb | 375 | These functions compute the arctangent of @var{x}---that is, the value |
28f540f4 RM |
376 | whose tangent is @var{x}. The value is in units of radians. |
377 | Mathematically, there are infinitely many such values; the one actually | |
7a68c94a | 378 | returned is the one between @code{-pi/2} and @code{pi/2} (inclusive). |
28f540f4 RM |
379 | @end deftypefun |
380 | ||
28f540f4 | 381 | @deftypefun double atan2 (double @var{y}, double @var{x}) |
779ae82e UD |
382 | @deftypefunx float atan2f (float @var{y}, float @var{x}) |
383 | @deftypefunx {long double} atan2l (long double @var{y}, long double @var{x}) | |
52a8e5cb GG |
384 | @deftypefunx _FloatN atan2fN (_Float@var{N} @var{y}, _Float@var{N} @var{x}) |
385 | @deftypefunx _FloatNx atan2fNx (_Float@var{N}x @var{y}, _Float@var{N}x @var{x}) | |
d08a7e4c | 386 | @standards{ISO, math.h} |
52a8e5cb GG |
387 | @standardsx{atan2fN, TS 18661-3:2015, math.h} |
388 | @standardsx{atan2fNx, TS 18661-3:2015, math.h} | |
27aaa791 | 389 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
60843ffb | 390 | This function computes the arctangent of @var{y}/@var{x}, but the signs |
7a68c94a UD |
391 | of both arguments are used to determine the quadrant of the result, and |
392 | @var{x} is permitted to be zero. The return value is given in radians | |
393 | and is in the range @code{-pi} to @code{pi}, inclusive. | |
28f540f4 RM |
394 | |
395 | If @var{x} and @var{y} are coordinates of a point in the plane, | |
396 | @code{atan2} returns the signed angle between the line from the origin | |
397 | to that point and the x-axis. Thus, @code{atan2} is useful for | |
398 | converting Cartesian coordinates to polar coordinates. (To compute the | |
399 | radial coordinate, use @code{hypot}; see @ref{Exponents and | |
400 | Logarithms}.) | |
401 | ||
7a68c94a UD |
402 | @c This is experimentally true. Should it be so? -zw |
403 | If both @var{x} and @var{y} are zero, @code{atan2} returns zero. | |
28f540f4 RM |
404 | @end deftypefun |
405 | ||
b4012b75 | 406 | @cindex inverse complex trigonometric functions |
ec751a23 | 407 | @w{ISO C99} defines complex versions of the inverse trig functions. |
b4012b75 | 408 | |
b4012b75 | 409 | @deftypefun {complex double} casin (complex double @var{z}) |
779ae82e UD |
410 | @deftypefunx {complex float} casinf (complex float @var{z}) |
411 | @deftypefunx {complex long double} casinl (complex long double @var{z}) | |
52a8e5cb GG |
412 | @deftypefunx {complex _FloatN} casinfN (complex _Float@var{N} @var{z}) |
413 | @deftypefunx {complex _FloatNx} casinfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 414 | @standards{ISO, complex.h} |
52a8e5cb GG |
415 | @standardsx{casinfN, TS 18661-3:2015, complex.h} |
416 | @standardsx{casinfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 417 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
60843ffb | 418 | These functions compute the complex arcsine of @var{z}---that is, the |
7a68c94a | 419 | value whose sine is @var{z}. The value returned is in radians. |
b4012b75 | 420 | |
7a68c94a UD |
421 | Unlike the real-valued functions, @code{casin} is defined for all |
422 | values of @var{z}. | |
b4012b75 UD |
423 | @end deftypefun |
424 | ||
b4012b75 | 425 | @deftypefun {complex double} cacos (complex double @var{z}) |
779ae82e UD |
426 | @deftypefunx {complex float} cacosf (complex float @var{z}) |
427 | @deftypefunx {complex long double} cacosl (complex long double @var{z}) | |
52a8e5cb GG |
428 | @deftypefunx {complex _FloatN} cacosfN (complex _Float@var{N} @var{z}) |
429 | @deftypefunx {complex _FloatNx} cacosfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 430 | @standards{ISO, complex.h} |
52a8e5cb GG |
431 | @standardsx{cacosfN, TS 18661-3:2015, complex.h} |
432 | @standardsx{cacosfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 433 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
60843ffb | 434 | These functions compute the complex arccosine of @var{z}---that is, the |
7a68c94a | 435 | value whose cosine is @var{z}. The value returned is in radians. |
b4012b75 | 436 | |
7a68c94a UD |
437 | Unlike the real-valued functions, @code{cacos} is defined for all |
438 | values of @var{z}. | |
b4012b75 UD |
439 | @end deftypefun |
440 | ||
441 | ||
b4012b75 | 442 | @deftypefun {complex double} catan (complex double @var{z}) |
779ae82e UD |
443 | @deftypefunx {complex float} catanf (complex float @var{z}) |
444 | @deftypefunx {complex long double} catanl (complex long double @var{z}) | |
52a8e5cb GG |
445 | @deftypefunx {complex _FloatN} catanfN (complex _Float@var{N} @var{z}) |
446 | @deftypefunx {complex _FloatNx} catanfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 447 | @standards{ISO, complex.h} |
52a8e5cb GG |
448 | @standardsx{catanfN, TS 18661-3:2015, complex.h} |
449 | @standardsx{catanfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 450 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
60843ffb | 451 | These functions compute the complex arctangent of @var{z}---that is, |
b4012b75 UD |
452 | the value whose tangent is @var{z}. The value is in units of radians. |
453 | @end deftypefun | |
454 | ||
28f540f4 RM |
455 | |
456 | @node Exponents and Logarithms | |
457 | @section Exponentiation and Logarithms | |
458 | @cindex exponentiation functions | |
459 | @cindex power functions | |
460 | @cindex logarithm functions | |
461 | ||
28f540f4 | 462 | @deftypefun double exp (double @var{x}) |
779ae82e UD |
463 | @deftypefunx float expf (float @var{x}) |
464 | @deftypefunx {long double} expl (long double @var{x}) | |
52a8e5cb GG |
465 | @deftypefunx _FloatN expfN (_Float@var{N} @var{x}) |
466 | @deftypefunx _FloatNx expfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 467 | @standards{ISO, math.h} |
52a8e5cb GG |
468 | @standardsx{expfN, TS 18661-3:2015, math.h} |
469 | @standardsx{expfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 470 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
471 | These functions compute @code{e} (the base of natural logarithms) raised |
472 | to the power @var{x}. | |
28f540f4 | 473 | |
7a68c94a UD |
474 | If the magnitude of the result is too large to be representable, |
475 | @code{exp} signals overflow. | |
28f540f4 RM |
476 | @end deftypefun |
477 | ||
04a96fd4 UD |
478 | @deftypefun double exp2 (double @var{x}) |
479 | @deftypefunx float exp2f (float @var{x}) | |
480 | @deftypefunx {long double} exp2l (long double @var{x}) | |
52a8e5cb GG |
481 | @deftypefunx _FloatN exp2fN (_Float@var{N} @var{x}) |
482 | @deftypefunx _FloatNx exp2fNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 483 | @standards{ISO, math.h} |
52a8e5cb GG |
484 | @standardsx{exp2fN, TS 18661-3:2015, math.h} |
485 | @standardsx{exp2fNx, TS 18661-3:2015, math.h} | |
27aaa791 | 486 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a | 487 | These functions compute @code{2} raised to the power @var{x}. |
04a96fd4 | 488 | Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}. |
b4012b75 UD |
489 | @end deftypefun |
490 | ||
04a96fd4 UD |
491 | @deftypefun double exp10 (double @var{x}) |
492 | @deftypefunx float exp10f (float @var{x}) | |
493 | @deftypefunx {long double} exp10l (long double @var{x}) | |
52a8e5cb GG |
494 | @deftypefunx _FloatN exp10fN (_Float@var{N} @var{x}) |
495 | @deftypefunx _FloatNx exp10fNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 496 | @standards{ISO, math.h} |
52a8e5cb GG |
497 | @standardsx{exp10fN, TS 18661-4:2015, math.h} |
498 | @standardsx{exp10fNx, TS 18661-4:2015, math.h} | |
27aaa791 | 499 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
500 | These functions compute @code{10} raised to the power @var{x}. |
501 | Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}. | |
b4012b75 | 502 | |
5a80d39d | 503 | The @code{exp10} functions are from TS 18661-4:2015. |
b4012b75 UD |
504 | @end deftypefun |
505 | ||
506 | ||
28f540f4 | 507 | @deftypefun double log (double @var{x}) |
f2ea0f5b | 508 | @deftypefunx float logf (float @var{x}) |
779ae82e | 509 | @deftypefunx {long double} logl (long double @var{x}) |
52a8e5cb GG |
510 | @deftypefunx _FloatN logfN (_Float@var{N} @var{x}) |
511 | @deftypefunx _FloatNx logfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 512 | @standards{ISO, math.h} |
52a8e5cb GG |
513 | @standardsx{logfN, TS 18661-3:2015, math.h} |
514 | @standardsx{logfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 515 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a | 516 | These functions compute the natural logarithm of @var{x}. @code{exp (log |
28f540f4 RM |
517 | (@var{x}))} equals @var{x}, exactly in mathematics and approximately in |
518 | C. | |
519 | ||
7a68c94a UD |
520 | If @var{x} is negative, @code{log} signals a domain error. If @var{x} |
521 | is zero, it returns negative infinity; if @var{x} is too close to zero, | |
522 | it may signal overflow. | |
28f540f4 RM |
523 | @end deftypefun |
524 | ||
28f540f4 | 525 | @deftypefun double log10 (double @var{x}) |
779ae82e UD |
526 | @deftypefunx float log10f (float @var{x}) |
527 | @deftypefunx {long double} log10l (long double @var{x}) | |
52a8e5cb GG |
528 | @deftypefunx _FloatN log10fN (_Float@var{N} @var{x}) |
529 | @deftypefunx _FloatNx log10fNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 530 | @standards{ISO, math.h} |
52a8e5cb GG |
531 | @standardsx{log10fN, TS 18661-3:2015, math.h} |
532 | @standardsx{log10fNx, TS 18661-3:2015, math.h} | |
27aaa791 | 533 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a | 534 | These functions return the base-10 logarithm of @var{x}. |
28f540f4 | 535 | @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}. |
7a68c94a | 536 | |
28f540f4 RM |
537 | @end deftypefun |
538 | ||
b4012b75 | 539 | @deftypefun double log2 (double @var{x}) |
779ae82e UD |
540 | @deftypefunx float log2f (float @var{x}) |
541 | @deftypefunx {long double} log2l (long double @var{x}) | |
52a8e5cb GG |
542 | @deftypefunx _FloatN log2fN (_Float@var{N} @var{x}) |
543 | @deftypefunx _FloatNx log2fNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 544 | @standards{ISO, math.h} |
52a8e5cb GG |
545 | @standardsx{log2fN, TS 18661-3:2015, math.h} |
546 | @standardsx{log2fNx, TS 18661-3:2015, math.h} | |
27aaa791 | 547 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a | 548 | These functions return the base-2 logarithm of @var{x}. |
b4012b75 UD |
549 | @code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}. |
550 | @end deftypefun | |
551 | ||
55c14926 UD |
552 | @deftypefun double logb (double @var{x}) |
553 | @deftypefunx float logbf (float @var{x}) | |
554 | @deftypefunx {long double} logbl (long double @var{x}) | |
52a8e5cb GG |
555 | @deftypefunx _FloatN logbfN (_Float@var{N} @var{x}) |
556 | @deftypefunx _FloatNx logbfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 557 | @standards{ISO, math.h} |
52a8e5cb GG |
558 | @standardsx{logbfN, TS 18661-3:2015, math.h} |
559 | @standardsx{logbfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 560 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
55c14926 | 561 | These functions extract the exponent of @var{x} and return it as a |
7a68c94a UD |
562 | floating-point value. If @code{FLT_RADIX} is two, @code{logb} is equal |
563 | to @code{floor (log2 (x))}, except it's probably faster. | |
55c14926 | 564 | |
04b9968b | 565 | If @var{x} is de-normalized, @code{logb} returns the exponent @var{x} |
7a68c94a UD |
566 | would have if it were normalized. If @var{x} is infinity (positive or |
567 | negative), @code{logb} returns @math{@infinity{}}. If @var{x} is zero, | |
568 | @code{logb} returns @math{@infinity{}}. It does not signal. | |
55c14926 UD |
569 | @end deftypefun |
570 | ||
55c14926 UD |
571 | @deftypefun int ilogb (double @var{x}) |
572 | @deftypefunx int ilogbf (float @var{x}) | |
573 | @deftypefunx int ilogbl (long double @var{x}) | |
52a8e5cb GG |
574 | @deftypefunx int ilogbfN (_Float@var{N} @var{x}) |
575 | @deftypefunx int ilogbfNx (_Float@var{N}x @var{x}) | |
55a38f82 | 576 | @deftypefunx {long int} llogb (double @var{x}) |
55a38f82 | 577 | @deftypefunx {long int} llogbf (float @var{x}) |
55a38f82 | 578 | @deftypefunx {long int} llogbl (long double @var{x}) |
52a8e5cb GG |
579 | @deftypefunx {long int} llogbfN (_Float@var{N} @var{x}) |
580 | @deftypefunx {long int} llogbfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 581 | @standards{ISO, math.h} |
52a8e5cb GG |
582 | @standardsx{ilogbfN, TS 18661-3:2015, math.h} |
583 | @standardsx{ilogbfNx, TS 18661-3:2015, math.h} | |
584 | @standardsx{llogbfN, TS 18661-3:2015, math.h} | |
585 | @standardsx{llogbfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 586 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
55c14926 | 587 | These functions are equivalent to the corresponding @code{logb} |
55a38f82 | 588 | functions except that they return signed integer values. The |
52a8e5cb GG |
589 | @code{ilogb}, @code{ilogbf}, and @code{ilogbl} functions are from ISO |
590 | C99; the @code{llogb}, @code{llogbf}, @code{llogbl} functions are from | |
591 | TS 18661-1:2014; the @code{ilogbfN}, @code{ilogbfNx}, @code{llogbfN}, | |
592 | and @code{llogbfNx} functions are from TS 18661-3:2015. | |
7a68c94a UD |
593 | @end deftypefun |
594 | ||
595 | @noindent | |
596 | Since integers cannot represent infinity and NaN, @code{ilogb} instead | |
597 | returns an integer that can't be the exponent of a normal floating-point | |
598 | number. @file{math.h} defines constants so you can check for this. | |
599 | ||
7a68c94a | 600 | @deftypevr Macro int FP_ILOGB0 |
d08a7e4c | 601 | @standards{ISO, math.h} |
7a68c94a UD |
602 | @code{ilogb} returns this value if its argument is @code{0}. The |
603 | numeric value is either @code{INT_MIN} or @code{-INT_MAX}. | |
604 | ||
ec751a23 | 605 | This macro is defined in @w{ISO C99}. |
7a68c94a UD |
606 | @end deftypevr |
607 | ||
55a38f82 | 608 | @deftypevr Macro {long int} FP_LLOGB0 |
d08a7e4c | 609 | @standards{ISO, math.h} |
55a38f82 JM |
610 | @code{llogb} returns this value if its argument is @code{0}. The |
611 | numeric value is either @code{LONG_MIN} or @code{-LONG_MAX}. | |
612 | ||
613 | This macro is defined in TS 18661-1:2014. | |
614 | @end deftypevr | |
615 | ||
7a68c94a | 616 | @deftypevr Macro int FP_ILOGBNAN |
d08a7e4c | 617 | @standards{ISO, math.h} |
7a68c94a UD |
618 | @code{ilogb} returns this value if its argument is @code{NaN}. The |
619 | numeric value is either @code{INT_MIN} or @code{INT_MAX}. | |
620 | ||
ec751a23 | 621 | This macro is defined in @w{ISO C99}. |
7a68c94a UD |
622 | @end deftypevr |
623 | ||
55a38f82 | 624 | @deftypevr Macro {long int} FP_LLOGBNAN |
d08a7e4c | 625 | @standards{ISO, math.h} |
55a38f82 JM |
626 | @code{llogb} returns this value if its argument is @code{NaN}. The |
627 | numeric value is either @code{LONG_MIN} or @code{LONG_MAX}. | |
628 | ||
629 | This macro is defined in TS 18661-1:2014. | |
630 | @end deftypevr | |
631 | ||
7a68c94a UD |
632 | These values are system specific. They might even be the same. The |
633 | proper way to test the result of @code{ilogb} is as follows: | |
55c14926 UD |
634 | |
635 | @smallexample | |
636 | i = ilogb (f); | |
637 | if (i == FP_ILOGB0 || i == FP_ILOGBNAN) | |
638 | @{ | |
639 | if (isnan (f)) | |
640 | @{ | |
641 | /* @r{Handle NaN.} */ | |
642 | @} | |
643 | else if (f == 0.0) | |
644 | @{ | |
645 | /* @r{Handle 0.0.} */ | |
646 | @} | |
647 | else | |
648 | @{ | |
649 | /* @r{Some other value with large exponent,} | |
650 | @r{perhaps +Inf.} */ | |
651 | @} | |
652 | @} | |
653 | @end smallexample | |
654 | ||
28f540f4 | 655 | @deftypefun double pow (double @var{base}, double @var{power}) |
779ae82e UD |
656 | @deftypefunx float powf (float @var{base}, float @var{power}) |
657 | @deftypefunx {long double} powl (long double @var{base}, long double @var{power}) | |
52a8e5cb GG |
658 | @deftypefunx _FloatN powfN (_Float@var{N} @var{base}, _Float@var{N} @var{power}) |
659 | @deftypefunx _FloatNx powfNx (_Float@var{N}x @var{base}, _Float@var{N}x @var{power}) | |
d08a7e4c | 660 | @standards{ISO, math.h} |
52a8e5cb GG |
661 | @standardsx{powfN, TS 18661-3:2015, math.h} |
662 | @standardsx{powfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 663 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 664 | These are general exponentiation functions, returning @var{base} raised |
28f540f4 RM |
665 | to @var{power}. |
666 | ||
7a68c94a UD |
667 | Mathematically, @code{pow} would return a complex number when @var{base} |
668 | is negative and @var{power} is not an integral value. @code{pow} can't | |
669 | do that, so instead it signals a domain error. @code{pow} may also | |
670 | underflow or overflow the destination type. | |
28f540f4 RM |
671 | @end deftypefun |
672 | ||
673 | @cindex square root function | |
28f540f4 | 674 | @deftypefun double sqrt (double @var{x}) |
779ae82e UD |
675 | @deftypefunx float sqrtf (float @var{x}) |
676 | @deftypefunx {long double} sqrtl (long double @var{x}) | |
52a8e5cb GG |
677 | @deftypefunx _FloatN sqrtfN (_Float@var{N} @var{x}) |
678 | @deftypefunx _FloatNx sqrtfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 679 | @standards{ISO, math.h} |
52a8e5cb GG |
680 | @standardsx{sqrtfN, TS 18661-3:2015, math.h} |
681 | @standardsx{sqrtfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 682 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 683 | These functions return the nonnegative square root of @var{x}. |
28f540f4 | 684 | |
7a68c94a UD |
685 | If @var{x} is negative, @code{sqrt} signals a domain error. |
686 | Mathematically, it should return a complex number. | |
28f540f4 RM |
687 | @end deftypefun |
688 | ||
689 | @cindex cube root function | |
28f540f4 | 690 | @deftypefun double cbrt (double @var{x}) |
779ae82e UD |
691 | @deftypefunx float cbrtf (float @var{x}) |
692 | @deftypefunx {long double} cbrtl (long double @var{x}) | |
52a8e5cb GG |
693 | @deftypefunx _FloatN cbrtfN (_Float@var{N} @var{x}) |
694 | @deftypefunx _FloatNx cbrtfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 695 | @standards{BSD, math.h} |
52a8e5cb GG |
696 | @standardsx{cbrtfN, TS 18661-3:2015, math.h} |
697 | @standardsx{cbrtfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 698 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 699 | These functions return the cube root of @var{x}. They cannot |
28f540f4 RM |
700 | fail; every representable real value has a representable real cube root. |
701 | @end deftypefun | |
702 | ||
28f540f4 | 703 | @deftypefun double hypot (double @var{x}, double @var{y}) |
779ae82e UD |
704 | @deftypefunx float hypotf (float @var{x}, float @var{y}) |
705 | @deftypefunx {long double} hypotl (long double @var{x}, long double @var{y}) | |
52a8e5cb GG |
706 | @deftypefunx _FloatN hypotfN (_Float@var{N} @var{x}, _Float@var{N} @var{y}) |
707 | @deftypefunx _FloatNx hypotfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y}) | |
d08a7e4c | 708 | @standards{ISO, math.h} |
52a8e5cb GG |
709 | @standardsx{hypotfN, TS 18661-3:2015, math.h} |
710 | @standardsx{hypotfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 711 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 712 | These functions return @code{sqrt (@var{x}*@var{x} + |
7a68c94a | 713 | @var{y}*@var{y})}. This is the length of the hypotenuse of a right |
28f540f4 | 714 | triangle with sides of length @var{x} and @var{y}, or the distance |
7a68c94a UD |
715 | of the point (@var{x}, @var{y}) from the origin. Using this function |
716 | instead of the direct formula is wise, since the error is | |
b4012b75 | 717 | much smaller. See also the function @code{cabs} in @ref{Absolute Value}. |
28f540f4 RM |
718 | @end deftypefun |
719 | ||
28f540f4 | 720 | @deftypefun double expm1 (double @var{x}) |
779ae82e UD |
721 | @deftypefunx float expm1f (float @var{x}) |
722 | @deftypefunx {long double} expm1l (long double @var{x}) | |
52a8e5cb GG |
723 | @deftypefunx _FloatN expm1fN (_Float@var{N} @var{x}) |
724 | @deftypefunx _FloatNx expm1fNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 725 | @standards{ISO, math.h} |
52a8e5cb GG |
726 | @standardsx{expm1fN, TS 18661-3:2015, math.h} |
727 | @standardsx{expm1fNx, TS 18661-3:2015, math.h} | |
27aaa791 | 728 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 729 | These functions return a value equivalent to @code{exp (@var{x}) - 1}. |
7a68c94a | 730 | They are computed in a way that is accurate even if @var{x} is |
04b9968b | 731 | near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate owing |
28f540f4 RM |
732 | to subtraction of two numbers that are nearly equal. |
733 | @end deftypefun | |
734 | ||
28f540f4 | 735 | @deftypefun double log1p (double @var{x}) |
779ae82e UD |
736 | @deftypefunx float log1pf (float @var{x}) |
737 | @deftypefunx {long double} log1pl (long double @var{x}) | |
52a8e5cb GG |
738 | @deftypefunx _FloatN log1pfN (_Float@var{N} @var{x}) |
739 | @deftypefunx _FloatNx log1pfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 740 | @standards{ISO, math.h} |
52a8e5cb GG |
741 | @standardsx{log1pfN, TS 18661-3:2015, math.h} |
742 | @standardsx{log1pfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 743 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
60843ffb | 744 | These functions return a value equivalent to @w{@code{log (1 + @var{x})}}. |
7a68c94a | 745 | They are computed in a way that is accurate even if @var{x} is |
28f540f4 RM |
746 | near zero. |
747 | @end deftypefun | |
748 | ||
b4012b75 UD |
749 | @cindex complex exponentiation functions |
750 | @cindex complex logarithm functions | |
751 | ||
ec751a23 | 752 | @w{ISO C99} defines complex variants of some of the exponentiation and |
7a68c94a | 753 | logarithm functions. |
b4012b75 | 754 | |
b4012b75 | 755 | @deftypefun {complex double} cexp (complex double @var{z}) |
779ae82e UD |
756 | @deftypefunx {complex float} cexpf (complex float @var{z}) |
757 | @deftypefunx {complex long double} cexpl (complex long double @var{z}) | |
52a8e5cb GG |
758 | @deftypefunx {complex _FloatN} cexpfN (complex _Float@var{N} @var{z}) |
759 | @deftypefunx {complex _FloatNx} cexpfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 760 | @standards{ISO, complex.h} |
52a8e5cb GG |
761 | @standardsx{cexpfN, TS 18661-3:2015, complex.h} |
762 | @standardsx{cexpfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 763 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
764 | These functions return @code{e} (the base of natural |
765 | logarithms) raised to the power of @var{z}. | |
04b9968b | 766 | Mathematically, this corresponds to the value |
b4012b75 | 767 | |
4c78249d | 768 | @ifnottex |
779ae82e | 769 | @math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))} |
4c78249d | 770 | @end ifnottex |
779ae82e | 771 | @tex |
7a68c94a | 772 | $$\exp(z) = e^z = e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$ |
779ae82e | 773 | @end tex |
b4012b75 UD |
774 | @end deftypefun |
775 | ||
b4012b75 | 776 | @deftypefun {complex double} clog (complex double @var{z}) |
779ae82e UD |
777 | @deftypefunx {complex float} clogf (complex float @var{z}) |
778 | @deftypefunx {complex long double} clogl (complex long double @var{z}) | |
52a8e5cb GG |
779 | @deftypefunx {complex _FloatN} clogfN (complex _Float@var{N} @var{z}) |
780 | @deftypefunx {complex _FloatNx} clogfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 781 | @standards{ISO, complex.h} |
52a8e5cb GG |
782 | @standardsx{clogfN, TS 18661-3:2015, complex.h} |
783 | @standardsx{clogfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 784 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a | 785 | These functions return the natural logarithm of @var{z}. |
04b9968b | 786 | Mathematically, this corresponds to the value |
b4012b75 | 787 | |
4c78249d | 788 | @ifnottex |
779ae82e | 789 | @math{log (z) = log (cabs (z)) + I * carg (z)} |
4c78249d | 790 | @end ifnottex |
779ae82e | 791 | @tex |
7a68c94a | 792 | $$\log(z) = \log |z| + i \arg z$$ |
779ae82e | 793 | @end tex |
7a68c94a UD |
794 | |
795 | @noindent | |
796 | @code{clog} has a pole at 0, and will signal overflow if @var{z} equals | |
797 | or is very close to 0. It is well-defined for all other values of | |
798 | @var{z}. | |
b4012b75 UD |
799 | @end deftypefun |
800 | ||
dfd2257a | 801 | |
dfd2257a UD |
802 | @deftypefun {complex double} clog10 (complex double @var{z}) |
803 | @deftypefunx {complex float} clog10f (complex float @var{z}) | |
804 | @deftypefunx {complex long double} clog10l (complex long double @var{z}) | |
52a8e5cb GG |
805 | @deftypefunx {complex _FloatN} clog10fN (complex _Float@var{N} @var{z}) |
806 | @deftypefunx {complex _FloatNx} clog10fNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 807 | @standards{GNU, complex.h} |
27aaa791 | 808 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
dfd2257a | 809 | These functions return the base 10 logarithm of the complex value |
cf822e3c | 810 | @var{z}. Mathematically, this corresponds to the value |
dfd2257a | 811 | |
4c78249d | 812 | @ifnottex |
6adaeadf | 813 | @math{log10 (z) = log10 (cabs (z)) + I * carg (z) / log (10)} |
4c78249d | 814 | @end ifnottex |
dfd2257a | 815 | @tex |
6adaeadf | 816 | $$\log_{10}(z) = \log_{10}|z| + i \arg z / \log (10)$$ |
dfd2257a | 817 | @end tex |
dfd2257a | 818 | |
52a8e5cb GG |
819 | All these functions, including the @code{_Float@var{N}} and |
820 | @code{_Float@var{N}x} variants, are GNU extensions. | |
dfd2257a UD |
821 | @end deftypefun |
822 | ||
b4012b75 | 823 | @deftypefun {complex double} csqrt (complex double @var{z}) |
779ae82e UD |
824 | @deftypefunx {complex float} csqrtf (complex float @var{z}) |
825 | @deftypefunx {complex long double} csqrtl (complex long double @var{z}) | |
52a8e5cb GG |
826 | @deftypefunx {complex _FloatN} csqrtfN (_Float@var{N} @var{z}) |
827 | @deftypefunx {complex _FloatNx} csqrtfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 828 | @standards{ISO, complex.h} |
52a8e5cb GG |
829 | @standardsx{csqrtfN, TS 18661-3:2015, complex.h} |
830 | @standardsx{csqrtfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 831 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
832 | These functions return the complex square root of the argument @var{z}. Unlike |
833 | the real-valued functions, they are defined for all values of @var{z}. | |
b4012b75 UD |
834 | @end deftypefun |
835 | ||
b4012b75 | 836 | @deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power}) |
779ae82e UD |
837 | @deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power}) |
838 | @deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power}) | |
52a8e5cb GG |
839 | @deftypefunx {complex _FloatN} cpowfN (complex _Float@var{N} @var{base}, complex _Float@var{N} @var{power}) |
840 | @deftypefunx {complex _FloatNx} cpowfNx (complex _Float@var{N}x @var{base}, complex _Float@var{N}x @var{power}) | |
d08a7e4c | 841 | @standards{ISO, complex.h} |
52a8e5cb GG |
842 | @standardsx{cpowfN, TS 18661-3:2015, complex.h} |
843 | @standardsx{cpowfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 844 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
845 | These functions return @var{base} raised to the power of |
846 | @var{power}. This is equivalent to @w{@code{cexp (y * clog (x))}} | |
b4012b75 UD |
847 | @end deftypefun |
848 | ||
28f540f4 RM |
849 | @node Hyperbolic Functions |
850 | @section Hyperbolic Functions | |
851 | @cindex hyperbolic functions | |
852 | ||
853 | The functions in this section are related to the exponential functions; | |
854 | see @ref{Exponents and Logarithms}. | |
855 | ||
28f540f4 | 856 | @deftypefun double sinh (double @var{x}) |
779ae82e UD |
857 | @deftypefunx float sinhf (float @var{x}) |
858 | @deftypefunx {long double} sinhl (long double @var{x}) | |
52a8e5cb GG |
859 | @deftypefunx _FloatN sinhfN (_Float@var{N} @var{x}) |
860 | @deftypefunx _FloatNx sinhfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 861 | @standards{ISO, math.h} |
52a8e5cb GG |
862 | @standardsx{sinhfN, TS 18661-3:2015, math.h} |
863 | @standardsx{sinhfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 864 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 865 | These functions return the hyperbolic sine of @var{x}, defined |
7a68c94a UD |
866 | mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}. They |
867 | may signal overflow if @var{x} is too large. | |
28f540f4 RM |
868 | @end deftypefun |
869 | ||
28f540f4 | 870 | @deftypefun double cosh (double @var{x}) |
779ae82e UD |
871 | @deftypefunx float coshf (float @var{x}) |
872 | @deftypefunx {long double} coshl (long double @var{x}) | |
52a8e5cb GG |
873 | @deftypefunx _FloatN coshfN (_Float@var{N} @var{x}) |
874 | @deftypefunx _FloatNx coshfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 875 | @standards{ISO, math.h} |
52a8e5cb GG |
876 | @standardsx{coshfN, TS 18661-3:2015, math.h} |
877 | @standardsx{coshfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 878 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
60843ffb | 879 | These functions return the hyperbolic cosine of @var{x}, |
b4012b75 | 880 | defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}. |
7a68c94a | 881 | They may signal overflow if @var{x} is too large. |
28f540f4 RM |
882 | @end deftypefun |
883 | ||
28f540f4 | 884 | @deftypefun double tanh (double @var{x}) |
779ae82e UD |
885 | @deftypefunx float tanhf (float @var{x}) |
886 | @deftypefunx {long double} tanhl (long double @var{x}) | |
52a8e5cb GG |
887 | @deftypefunx _FloatN tanhfN (_Float@var{N} @var{x}) |
888 | @deftypefunx _FloatNx tanhfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 889 | @standards{ISO, math.h} |
52a8e5cb GG |
890 | @standardsx{tanhfN, TS 18661-3:2015, math.h} |
891 | @standardsx{tanhfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 892 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
893 | These functions return the hyperbolic tangent of @var{x}, |
894 | defined mathematically as @w{@code{sinh (@var{x}) / cosh (@var{x})}}. | |
895 | They may signal overflow if @var{x} is too large. | |
28f540f4 RM |
896 | @end deftypefun |
897 | ||
b4012b75 UD |
898 | @cindex hyperbolic functions |
899 | ||
7a68c94a UD |
900 | There are counterparts for the hyperbolic functions which take |
901 | complex arguments. | |
b4012b75 | 902 | |
b4012b75 | 903 | @deftypefun {complex double} csinh (complex double @var{z}) |
779ae82e UD |
904 | @deftypefunx {complex float} csinhf (complex float @var{z}) |
905 | @deftypefunx {complex long double} csinhl (complex long double @var{z}) | |
52a8e5cb GG |
906 | @deftypefunx {complex _FloatN} csinhfN (complex _Float@var{N} @var{z}) |
907 | @deftypefunx {complex _FloatNx} csinhfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 908 | @standards{ISO, complex.h} |
52a8e5cb GG |
909 | @standardsx{csinhfN, TS 18661-3:2015, complex.h} |
910 | @standardsx{csinhfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 911 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 912 | These functions return the complex hyperbolic sine of @var{z}, defined |
7a68c94a | 913 | mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}. |
b4012b75 UD |
914 | @end deftypefun |
915 | ||
b4012b75 | 916 | @deftypefun {complex double} ccosh (complex double @var{z}) |
779ae82e UD |
917 | @deftypefunx {complex float} ccoshf (complex float @var{z}) |
918 | @deftypefunx {complex long double} ccoshl (complex long double @var{z}) | |
52a8e5cb GG |
919 | @deftypefunx {complex _FloatN} ccoshfN (complex _Float@var{N} @var{z}) |
920 | @deftypefunx {complex _FloatNx} ccoshfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 921 | @standards{ISO, complex.h} |
52a8e5cb GG |
922 | @standardsx{ccoshfN, TS 18661-3:2015, complex.h} |
923 | @standardsx{ccoshfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 924 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 925 | These functions return the complex hyperbolic cosine of @var{z}, defined |
7a68c94a | 926 | mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}. |
b4012b75 UD |
927 | @end deftypefun |
928 | ||
b4012b75 | 929 | @deftypefun {complex double} ctanh (complex double @var{z}) |
779ae82e UD |
930 | @deftypefunx {complex float} ctanhf (complex float @var{z}) |
931 | @deftypefunx {complex long double} ctanhl (complex long double @var{z}) | |
52a8e5cb GG |
932 | @deftypefunx {complex _FloatN} ctanhfN (complex _Float@var{N} @var{z}) |
933 | @deftypefunx {complex _FloatNx} ctanhfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 934 | @standards{ISO, complex.h} |
52a8e5cb GG |
935 | @standardsx{ctanhfN, TS 18661-3:2015, complex.h} |
936 | @standardsx{ctanhfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 937 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
938 | These functions return the complex hyperbolic tangent of @var{z}, |
939 | defined mathematically as @w{@code{csinh (@var{z}) / ccosh (@var{z})}}. | |
b4012b75 UD |
940 | @end deftypefun |
941 | ||
942 | ||
28f540f4 RM |
943 | @cindex inverse hyperbolic functions |
944 | ||
28f540f4 | 945 | @deftypefun double asinh (double @var{x}) |
779ae82e UD |
946 | @deftypefunx float asinhf (float @var{x}) |
947 | @deftypefunx {long double} asinhl (long double @var{x}) | |
52a8e5cb GG |
948 | @deftypefunx _FloatN asinhfN (_Float@var{N} @var{x}) |
949 | @deftypefunx _FloatNx asinhfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 950 | @standards{ISO, math.h} |
52a8e5cb GG |
951 | @standardsx{asinhfN, TS 18661-3:2015, math.h} |
952 | @standardsx{asinhfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 953 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 954 | These functions return the inverse hyperbolic sine of @var{x}---the |
28f540f4 RM |
955 | value whose hyperbolic sine is @var{x}. |
956 | @end deftypefun | |
957 | ||
28f540f4 | 958 | @deftypefun double acosh (double @var{x}) |
779ae82e UD |
959 | @deftypefunx float acoshf (float @var{x}) |
960 | @deftypefunx {long double} acoshl (long double @var{x}) | |
52a8e5cb GG |
961 | @deftypefunx _FloatN acoshfN (_Float@var{N} @var{x}) |
962 | @deftypefunx _FloatNx acoshfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 963 | @standards{ISO, math.h} |
52a8e5cb GG |
964 | @standardsx{acoshfN, TS 18661-3:2015, math.h} |
965 | @standardsx{acoshfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 966 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 967 | These functions return the inverse hyperbolic cosine of @var{x}---the |
28f540f4 | 968 | value whose hyperbolic cosine is @var{x}. If @var{x} is less than |
7a68c94a | 969 | @code{1}, @code{acosh} signals a domain error. |
28f540f4 RM |
970 | @end deftypefun |
971 | ||
28f540f4 | 972 | @deftypefun double atanh (double @var{x}) |
779ae82e UD |
973 | @deftypefunx float atanhf (float @var{x}) |
974 | @deftypefunx {long double} atanhl (long double @var{x}) | |
52a8e5cb GG |
975 | @deftypefunx _FloatN atanhfN (_Float@var{N} @var{x}) |
976 | @deftypefunx _FloatNx atanhfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 977 | @standards{ISO, math.h} |
52a8e5cb GG |
978 | @standardsx{atanhfN, TS 18661-3:2015, math.h} |
979 | @standardsx{atanhfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 980 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 | 981 | These functions return the inverse hyperbolic tangent of @var{x}---the |
28f540f4 | 982 | value whose hyperbolic tangent is @var{x}. If the absolute value of |
7a68c94a UD |
983 | @var{x} is greater than @code{1}, @code{atanh} signals a domain error; |
984 | if it is equal to 1, @code{atanh} returns infinity. | |
28f540f4 RM |
985 | @end deftypefun |
986 | ||
b4012b75 UD |
987 | @cindex inverse complex hyperbolic functions |
988 | ||
b4012b75 | 989 | @deftypefun {complex double} casinh (complex double @var{z}) |
779ae82e UD |
990 | @deftypefunx {complex float} casinhf (complex float @var{z}) |
991 | @deftypefunx {complex long double} casinhl (complex long double @var{z}) | |
52a8e5cb GG |
992 | @deftypefunx {complex _FloatN} casinhfN (complex _Float@var{N} @var{z}) |
993 | @deftypefunx {complex _FloatNx} casinhfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 994 | @standards{ISO, complex.h} |
52a8e5cb GG |
995 | @standardsx{casinhfN, TS 18661-3:2015, complex.h} |
996 | @standardsx{casinhfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 997 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 UD |
998 | These functions return the inverse complex hyperbolic sine of |
999 | @var{z}---the value whose complex hyperbolic sine is @var{z}. | |
1000 | @end deftypefun | |
1001 | ||
b4012b75 | 1002 | @deftypefun {complex double} cacosh (complex double @var{z}) |
779ae82e UD |
1003 | @deftypefunx {complex float} cacoshf (complex float @var{z}) |
1004 | @deftypefunx {complex long double} cacoshl (complex long double @var{z}) | |
52a8e5cb GG |
1005 | @deftypefunx {complex _FloatN} cacoshfN (complex _Float@var{N} @var{z}) |
1006 | @deftypefunx {complex _FloatNx} cacoshfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 1007 | @standards{ISO, complex.h} |
52a8e5cb GG |
1008 | @standardsx{cacoshfN, TS 18661-3:2015, complex.h} |
1009 | @standardsx{cacoshfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 1010 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 UD |
1011 | These functions return the inverse complex hyperbolic cosine of |
1012 | @var{z}---the value whose complex hyperbolic cosine is @var{z}. Unlike | |
7a68c94a | 1013 | the real-valued functions, there are no restrictions on the value of @var{z}. |
b4012b75 UD |
1014 | @end deftypefun |
1015 | ||
b4012b75 | 1016 | @deftypefun {complex double} catanh (complex double @var{z}) |
779ae82e UD |
1017 | @deftypefunx {complex float} catanhf (complex float @var{z}) |
1018 | @deftypefunx {complex long double} catanhl (complex long double @var{z}) | |
52a8e5cb GG |
1019 | @deftypefunx {complex _FloatN} catanhfN (complex _Float@var{N} @var{z}) |
1020 | @deftypefunx {complex _FloatNx} catanhfNx (complex _Float@var{N}x @var{z}) | |
d08a7e4c | 1021 | @standards{ISO, complex.h} |
52a8e5cb GG |
1022 | @standardsx{catanhfN, TS 18661-3:2015, complex.h} |
1023 | @standardsx{catanhfNx, TS 18661-3:2015, complex.h} | |
27aaa791 | 1024 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
b4012b75 UD |
1025 | These functions return the inverse complex hyperbolic tangent of |
1026 | @var{z}---the value whose complex hyperbolic tangent is @var{z}. Unlike | |
7a68c94a UD |
1027 | the real-valued functions, there are no restrictions on the value of |
1028 | @var{z}. | |
b4012b75 UD |
1029 | @end deftypefun |
1030 | ||
7a68c94a UD |
1031 | @node Special Functions |
1032 | @section Special Functions | |
1033 | @cindex special functions | |
1034 | @cindex Bessel functions | |
1035 | @cindex gamma function | |
1036 | ||
04b9968b | 1037 | These are some more exotic mathematical functions which are sometimes |
7a68c94a UD |
1038 | useful. Currently they only have real-valued versions. |
1039 | ||
7a68c94a UD |
1040 | @deftypefun double erf (double @var{x}) |
1041 | @deftypefunx float erff (float @var{x}) | |
1042 | @deftypefunx {long double} erfl (long double @var{x}) | |
52a8e5cb GG |
1043 | @deftypefunx _FloatN erffN (_Float@var{N} @var{x}) |
1044 | @deftypefunx _FloatNx erffNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 1045 | @standards{SVID, math.h} |
52a8e5cb GG |
1046 | @standardsx{erffN, TS 18661-3:2015, math.h} |
1047 | @standardsx{erffNx, TS 18661-3:2015, math.h} | |
27aaa791 | 1048 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
1049 | @code{erf} returns the error function of @var{x}. The error |
1050 | function is defined as | |
1051 | @tex | |
1052 | $$\hbox{erf}(x) = {2\over\sqrt{\pi}}\cdot\int_0^x e^{-t^2} \hbox{d}t$$ | |
1053 | @end tex | |
1054 | @ifnottex | |
1055 | @smallexample | |
1056 | erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt | |
1057 | @end smallexample | |
1058 | @end ifnottex | |
1059 | @end deftypefun | |
1060 | ||
7a68c94a UD |
1061 | @deftypefun double erfc (double @var{x}) |
1062 | @deftypefunx float erfcf (float @var{x}) | |
1063 | @deftypefunx {long double} erfcl (long double @var{x}) | |
52a8e5cb GG |
1064 | @deftypefunx _FloatN erfcfN (_Float@var{N} @var{x}) |
1065 | @deftypefunx _FloatNx erfcfNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 1066 | @standards{SVID, math.h} |
52a8e5cb GG |
1067 | @standardsx{erfcfN, TS 18661-3:2015, math.h} |
1068 | @standardsx{erfcfNx, TS 18661-3:2015, math.h} | |
27aaa791 | 1069 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
1070 | @code{erfc} returns @code{1.0 - erf(@var{x})}, but computed in a |
1071 | fashion that avoids round-off error when @var{x} is large. | |
1072 | @end deftypefun | |
1073 | ||
7a68c94a UD |
1074 | @deftypefun double lgamma (double @var{x}) |
1075 | @deftypefunx float lgammaf (float @var{x}) | |
1076 | @deftypefunx {long double} lgammal (long double @var{x}) | |
52a8e5cb GG |
1077 | @deftypefunx _FloatN lgammafN (_Float@var{N} @var{x}) |
1078 | @deftypefunx _FloatNx lgammafNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 1079 | @standards{SVID, math.h} |
52a8e5cb GG |
1080 | @standardsx{lgammafN, TS 18661-3:2015, math.h} |
1081 | @standardsx{lgammafNx, TS 18661-3:2015, math.h} | |
27aaa791 | 1082 | @safety{@prelim{}@mtunsafe{@mtasurace{:signgam}}@asunsafe{}@acsafe{}} |
7a68c94a UD |
1083 | @code{lgamma} returns the natural logarithm of the absolute value of |
1084 | the gamma function of @var{x}. The gamma function is defined as | |
1085 | @tex | |
1086 | $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$ | |
1087 | @end tex | |
1088 | @ifnottex | |
1089 | @smallexample | |
1090 | gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt | |
1091 | @end smallexample | |
1092 | @end ifnottex | |
1093 | ||
1094 | @vindex signgam | |
1095 | The sign of the gamma function is stored in the global variable | |
1096 | @var{signgam}, which is declared in @file{math.h}. It is @code{1} if | |
04b9968b | 1097 | the intermediate result was positive or zero, or @code{-1} if it was |
7a68c94a UD |
1098 | negative. |
1099 | ||
e852e889 UD |
1100 | To compute the real gamma function you can use the @code{tgamma} |
1101 | function or you can compute the values as follows: | |
7a68c94a UD |
1102 | @smallexample |
1103 | lgam = lgamma(x); | |
1104 | gam = signgam*exp(lgam); | |
1105 | @end smallexample | |
1106 | ||
04b9968b | 1107 | The gamma function has singularities at the non-positive integers. |
7a68c94a UD |
1108 | @code{lgamma} will raise the zero divide exception if evaluated at a |
1109 | singularity. | |
1110 | @end deftypefun | |
1111 | ||
07435eb4 UD |
1112 | @deftypefun double lgamma_r (double @var{x}, int *@var{signp}) |
1113 | @deftypefunx float lgammaf_r (float @var{x}, int *@var{signp}) | |
1114 | @deftypefunx {long double} lgammal_r (long double @var{x}, int *@var{signp}) | |
52a8e5cb GG |
1115 | @deftypefunx _FloatN lgammafN_r (_Float@var{N} @var{x}, int *@var{signp}) |
1116 | @deftypefunx _FloatNx lgammafNx_r (_Float@var{N}x @var{x}, int *@var{signp}) | |
d08a7e4c | 1117 | @standards{XPG, math.h} |
52a8e5cb GG |
1118 | @standardsx{lgammafN_r, GNU, math.h} |
1119 | @standardsx{lgammafNx_r, GNU, math.h} | |
27aaa791 | 1120 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
1121 | @code{lgamma_r} is just like @code{lgamma}, but it stores the sign of |
1122 | the intermediate result in the variable pointed to by @var{signp} | |
04b9968b | 1123 | instead of in the @var{signgam} global. This means it is reentrant. |
52a8e5cb GG |
1124 | |
1125 | The @code{lgammaf@var{N}_r} and @code{lgammaf@var{N}x_r} functions are | |
1126 | GNU extensions. | |
7a68c94a UD |
1127 | @end deftypefun |
1128 | ||
7a68c94a UD |
1129 | @deftypefun double gamma (double @var{x}) |
1130 | @deftypefunx float gammaf (float @var{x}) | |
1131 | @deftypefunx {long double} gammal (long double @var{x}) | |
d08a7e4c | 1132 | @standards{SVID, math.h} |
27aaa791 | 1133 | @safety{@prelim{}@mtunsafe{@mtasurace{:signgam}}@asunsafe{}@acsafe{}} |
e852e889 UD |
1134 | These functions exist for compatibility reasons. They are equivalent to |
1135 | @code{lgamma} etc. It is better to use @code{lgamma} since for one the | |
60843ffb | 1136 | name reflects better the actual computation, and moreover @code{lgamma} is |
ec751a23 | 1137 | standardized in @w{ISO C99} while @code{gamma} is not. |
e852e889 UD |
1138 | @end deftypefun |
1139 | ||
e852e889 UD |
1140 | @deftypefun double tgamma (double @var{x}) |
1141 | @deftypefunx float tgammaf (float @var{x}) | |
1142 | @deftypefunx {long double} tgammal (long double @var{x}) | |
52a8e5cb GG |
1143 | @deftypefunx _FloatN tgammafN (_Float@var{N} @var{x}) |
1144 | @deftypefunx _FloatNx tgammafNx (_Float@var{N}x @var{x}) | |
d08a7e4c RJ |
1145 | @standardsx{tgamma, XPG, math.h} |
1146 | @standardsx{tgamma, ISO, math.h} | |
1147 | @standardsx{tgammaf, XPG, math.h} | |
1148 | @standardsx{tgammaf, ISO, math.h} | |
1149 | @standardsx{tgammal, XPG, math.h} | |
1150 | @standardsx{tgammal, ISO, math.h} | |
52a8e5cb GG |
1151 | @standardsx{tgammafN, TS 18661-3:2015, math.h} |
1152 | @standardsx{tgammafNx, TS 18661-3:2015, math.h} | |
27aaa791 | 1153 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
e852e889 UD |
1154 | @code{tgamma} applies the gamma function to @var{x}. The gamma |
1155 | function is defined as | |
1156 | @tex | |
1157 | $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$ | |
1158 | @end tex | |
1159 | @ifnottex | |
1160 | @smallexample | |
1161 | gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt | |
1162 | @end smallexample | |
1163 | @end ifnottex | |
1164 | ||
52a8e5cb GG |
1165 | This function was introduced in @w{ISO C99}. The @code{_Float@var{N}} |
1166 | and @code{_Float@var{N}x} variants were introduced in @w{ISO/IEC TS | |
1167 | 18661-3}. | |
7a68c94a | 1168 | @end deftypefun |
7a68c94a | 1169 | |
7a68c94a UD |
1170 | @deftypefun double j0 (double @var{x}) |
1171 | @deftypefunx float j0f (float @var{x}) | |
1172 | @deftypefunx {long double} j0l (long double @var{x}) | |
52a8e5cb GG |
1173 | @deftypefunx _FloatN j0fN (_Float@var{N} @var{x}) |
1174 | @deftypefunx _FloatNx j0fNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 1175 | @standards{SVID, math.h} |
52a8e5cb GG |
1176 | @standardsx{j0fN, GNU, math.h} |
1177 | @standardsx{j0fNx, GNU, math.h} | |
27aaa791 | 1178 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
1179 | @code{j0} returns the Bessel function of the first kind of order 0 of |
1180 | @var{x}. It may signal underflow if @var{x} is too large. | |
52a8e5cb GG |
1181 | |
1182 | The @code{_Float@var{N}} and @code{_Float@var{N}x} variants are GNU | |
1183 | extensions. | |
7a68c94a UD |
1184 | @end deftypefun |
1185 | ||
7a68c94a UD |
1186 | @deftypefun double j1 (double @var{x}) |
1187 | @deftypefunx float j1f (float @var{x}) | |
1188 | @deftypefunx {long double} j1l (long double @var{x}) | |
52a8e5cb GG |
1189 | @deftypefunx _FloatN j1fN (_Float@var{N} @var{x}) |
1190 | @deftypefunx _FloatNx j1fNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 1191 | @standards{SVID, math.h} |
52a8e5cb GG |
1192 | @standardsx{j1fN, GNU, math.h} |
1193 | @standardsx{j1fNx, GNU, math.h} | |
27aaa791 | 1194 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
1195 | @code{j1} returns the Bessel function of the first kind of order 1 of |
1196 | @var{x}. It may signal underflow if @var{x} is too large. | |
52a8e5cb GG |
1197 | |
1198 | The @code{_Float@var{N}} and @code{_Float@var{N}x} variants are GNU | |
1199 | extensions. | |
7a68c94a UD |
1200 | @end deftypefun |
1201 | ||
cc6e48bc | 1202 | @deftypefun double jn (int @var{n}, double @var{x}) |
cc6e48bc | 1203 | @deftypefunx float jnf (int @var{n}, float @var{x}) |
cc6e48bc | 1204 | @deftypefunx {long double} jnl (int @var{n}, long double @var{x}) |
52a8e5cb GG |
1205 | @deftypefunx _FloatN jnfN (int @var{n}, _Float@var{N} @var{x}) |
1206 | @deftypefunx _FloatNx jnfNx (int @var{n}, _Float@var{N}x @var{x}) | |
d08a7e4c | 1207 | @standards{SVID, math.h} |
52a8e5cb GG |
1208 | @standardsx{jnfN, GNU, math.h} |
1209 | @standardsx{jnfNx, GNU, math.h} | |
27aaa791 | 1210 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
1211 | @code{jn} returns the Bessel function of the first kind of order |
1212 | @var{n} of @var{x}. It may signal underflow if @var{x} is too large. | |
52a8e5cb GG |
1213 | |
1214 | The @code{_Float@var{N}} and @code{_Float@var{N}x} variants are GNU | |
1215 | extensions. | |
7a68c94a UD |
1216 | @end deftypefun |
1217 | ||
7a68c94a UD |
1218 | @deftypefun double y0 (double @var{x}) |
1219 | @deftypefunx float y0f (float @var{x}) | |
1220 | @deftypefunx {long double} y0l (long double @var{x}) | |
52a8e5cb GG |
1221 | @deftypefunx _FloatN y0fN (_Float@var{N} @var{x}) |
1222 | @deftypefunx _FloatNx y0fNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 1223 | @standards{SVID, math.h} |
52a8e5cb GG |
1224 | @standardsx{y0fN, GNU, math.h} |
1225 | @standardsx{y0fNx, GNU, math.h} | |
27aaa791 | 1226 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
1227 | @code{y0} returns the Bessel function of the second kind of order 0 of |
1228 | @var{x}. It may signal underflow if @var{x} is too large. If @var{x} | |
1229 | is negative, @code{y0} signals a domain error; if it is zero, | |
1230 | @code{y0} signals overflow and returns @math{-@infinity}. | |
52a8e5cb GG |
1231 | |
1232 | The @code{_Float@var{N}} and @code{_Float@var{N}x} variants are GNU | |
1233 | extensions. | |
7a68c94a UD |
1234 | @end deftypefun |
1235 | ||
7a68c94a UD |
1236 | @deftypefun double y1 (double @var{x}) |
1237 | @deftypefunx float y1f (float @var{x}) | |
1238 | @deftypefunx {long double} y1l (long double @var{x}) | |
52a8e5cb GG |
1239 | @deftypefunx _FloatN y1fN (_Float@var{N} @var{x}) |
1240 | @deftypefunx _FloatNx y1fNx (_Float@var{N}x @var{x}) | |
d08a7e4c | 1241 | @standards{SVID, math.h} |
52a8e5cb GG |
1242 | @standardsx{y1fN, GNU, math.h} |
1243 | @standardsx{y1fNx, GNU, math.h} | |
27aaa791 | 1244 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
1245 | @code{y1} returns the Bessel function of the second kind of order 1 of |
1246 | @var{x}. It may signal underflow if @var{x} is too large. If @var{x} | |
1247 | is negative, @code{y1} signals a domain error; if it is zero, | |
1248 | @code{y1} signals overflow and returns @math{-@infinity}. | |
52a8e5cb GG |
1249 | |
1250 | The @code{_Float@var{N}} and @code{_Float@var{N}x} variants are GNU | |
1251 | extensions. | |
7a68c94a UD |
1252 | @end deftypefun |
1253 | ||
cc6e48bc | 1254 | @deftypefun double yn (int @var{n}, double @var{x}) |
cc6e48bc | 1255 | @deftypefunx float ynf (int @var{n}, float @var{x}) |
cc6e48bc | 1256 | @deftypefunx {long double} ynl (int @var{n}, long double @var{x}) |
52a8e5cb GG |
1257 | @deftypefunx _FloatN ynfN (int @var{n}, _Float@var{N} @var{x}) |
1258 | @deftypefunx _FloatNx ynfNx (int @var{n}, _Float@var{N}x @var{x}) | |
d08a7e4c | 1259 | @standards{SVID, math.h} |
52a8e5cb GG |
1260 | @standardsx{ynfN, GNU, math.h} |
1261 | @standardsx{ynfNx, GNU, math.h} | |
27aaa791 | 1262 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
7a68c94a UD |
1263 | @code{yn} returns the Bessel function of the second kind of order @var{n} of |
1264 | @var{x}. It may signal underflow if @var{x} is too large. If @var{x} | |
1265 | is negative, @code{yn} signals a domain error; if it is zero, | |
1266 | @code{yn} signals overflow and returns @math{-@infinity}. | |
52a8e5cb GG |
1267 | |
1268 | The @code{_Float@var{N}} and @code{_Float@var{N}x} variants are GNU | |
1269 | extensions. | |
7a68c94a | 1270 | @end deftypefun |
55c14926 | 1271 | |
aaa1276e UD |
1272 | @node Errors in Math Functions |
1273 | @section Known Maximum Errors in Math Functions | |
1274 | @cindex math errors | |
1275 | @cindex ulps | |
1276 | ||
1277 | This section lists the known errors of the functions in the math | |
1278 | library. Errors are measured in ``units of the last place''. This is a | |
1279 | measure for the relative error. For a number @math{z} with the | |
1280 | representation @math{d.d@dots{}d@mul{}2^e} (we assume IEEE | |
1281 | floating-point numbers with base 2) the ULP is represented by | |
1282 | ||
1283 | @tex | |
ec751a23 | 1284 | $${|d.d\dots d - (z/2^e)|}\over {2^{p-1}}$$ |
aaa1276e UD |
1285 | @end tex |
1286 | @ifnottex | |
1287 | @smallexample | |
1288 | |d.d...d - (z / 2^e)| / 2^(p - 1) | |
1289 | @end smallexample | |
1290 | @end ifnottex | |
1291 | ||
1292 | @noindent | |
1293 | where @math{p} is the number of bits in the mantissa of the | |
1294 | floating-point number representation. Ideally the error for all | |
7475aef5 JM |
1295 | functions is always less than 0.5ulps in round-to-nearest mode. Using |
1296 | rounding bits this is also | |
1297 | possible and normally implemented for the basic operations. Except | |
1298 | for certain functions such as @code{sqrt}, @code{fma} and @code{rint} | |
1299 | whose results are fully specified by reference to corresponding IEEE | |
1300 | 754 floating-point operations, and conversions between strings and | |
1301 | floating point, @theglibc{} does not aim for correctly rounded results | |
1302 | for functions in the math library, and does not aim for correctness in | |
1303 | whether ``inexact'' exceptions are raised. Instead, the goals for | |
1304 | accuracy of functions without fully specified results are as follows; | |
1305 | some functions have bugs meaning they do not meet these goals in all | |
60843ffb | 1306 | cases. In the future, @theglibc{} may provide some other correctly |
7475aef5 JM |
1307 | rounding functions under the names such as @code{crsin} proposed for |
1308 | an extension to ISO C. | |
1309 | ||
1310 | @itemize @bullet | |
1311 | ||
1312 | @item | |
1313 | Each function with a floating-point result behaves as if it computes | |
1314 | an infinite-precision result that is within a few ulp (in both real | |
1315 | and complex parts, for functions with complex results) of the | |
1316 | mathematically correct value of the function (interpreted together | |
1317 | with ISO C or POSIX semantics for the function in question) at the | |
1318 | exact value passed as the input. Exceptions are raised appropriately | |
1319 | for this value and in accordance with IEEE 754 / ISO C / POSIX | |
1320 | semantics, and it is then rounded according to the current rounding | |
1321 | direction to the result that is returned to the user. @code{errno} | |
18a218b7 JM |
1322 | may also be set (@pxref{Math Error Reporting}). (The ``inexact'' |
1323 | exception may be raised, or not raised, even if this is inconsistent | |
1324 | with the infinite-precision value.) | |
7475aef5 JM |
1325 | |
1326 | @item | |
1327 | For the IBM @code{long double} format, as used on PowerPC GNU/Linux, | |
1328 | the accuracy goal is weaker for input values not exactly representable | |
1329 | in 106 bits of precision; it is as if the input value is some value | |
1330 | within 0.5ulp of the value actually passed, where ``ulp'' is | |
1331 | interpreted in terms of a fixed-precision 106-bit mantissa, but not | |
1332 | necessarily the exact value actually passed with discontiguous | |
1333 | mantissa bits. | |
1334 | ||
b55b28e6 JM |
1335 | @item |
1336 | For the IBM @code{long double} format, functions whose results are | |
1337 | fully specified by reference to corresponding IEEE 754 floating-point | |
1338 | operations have the same accuracy goals as other functions, but with | |
1339 | the error bound being the same as that for division (3ulp). | |
1340 | Furthermore, ``inexact'' and ``underflow'' exceptions may be raised | |
1341 | for all functions for any inputs, even where such exceptions are | |
1342 | inconsistent with the returned value, since the underlying | |
1343 | floating-point arithmetic has that property. | |
1344 | ||
7475aef5 JM |
1345 | @item |
1346 | Functions behave as if the infinite-precision result computed is zero, | |
1347 | infinity or NaN if and only if that is the mathematically correct | |
1348 | infinite-precision result. They behave as if the infinite-precision | |
1349 | result computed always has the same sign as the mathematically correct | |
1350 | result. | |
1351 | ||
1352 | @item | |
1353 | If the mathematical result is more than a few ulp above the overflow | |
1354 | threshold for the current rounding direction, the value returned is | |
1355 | the appropriate overflow value for the current rounding direction, | |
1356 | with the overflow exception raised. | |
1357 | ||
1358 | @item | |
1359 | If the mathematical result has magnitude well below half the least | |
1360 | subnormal magnitude, the returned value is either zero or the least | |
1361 | subnormal (in each case, with the correct sign), according to the | |
1362 | current rounding direction and with the underflow exception raised. | |
1363 | ||
1364 | @item | |
18a218b7 JM |
1365 | Where the mathematical result underflows (before rounding) and is not |
1366 | exactly representable as a floating-point value, the function does not | |
1367 | behave as if the computed infinite-precision result is an exact value | |
1368 | in the subnormal range. This means that the underflow exception is | |
1369 | raised other than possibly for cases where the mathematical result is | |
1370 | very close to the underflow threshold and the function behaves as if | |
1371 | it computes an infinite-precision result that does not underflow. (So | |
1372 | there may be spurious underflow exceptions in cases where the | |
1373 | underflowing result is exact, but not missing underflow exceptions in | |
1374 | cases where it is inexact.) | |
7475aef5 JM |
1375 | |
1376 | @item | |
1377 | @Theglibc{} does not aim for functions to satisfy other properties of | |
1378 | the underlying mathematical function, such as monotonicity, where not | |
1379 | implied by the above goals. | |
1380 | ||
1381 | @item | |
1382 | All the above applies to both real and complex parts, for complex | |
1383 | functions. | |
1384 | ||
1385 | @end itemize | |
aaa1276e UD |
1386 | |
1387 | Therefore many of the functions in the math library have errors. The | |
1388 | table lists the maximum error for each function which is exposed by one | |
41713d4e AJ |
1389 | of the existing tests in the test suite. The table tries to cover as much |
1390 | as possible and list the actual maximum error (or at least a ballpark | |
aaa1276e UD |
1391 | figure) but this is often not achieved due to the large search space. |
1392 | ||
1393 | The table lists the ULP values for different architectures. Different | |
1394 | architectures have different results since their hardware support for | |
1395 | floating-point operations varies and also the existing hardware support | |
2b7dc4c8 JM |
1396 | is different. Only the round-to-nearest rounding mode is covered by |
1397 | this table, and vector versions of functions are not covered. | |
1398 | Functions not listed do not have known errors. | |
aaa1276e | 1399 | |
41713d4e AJ |
1400 | @page |
1401 | @c This multitable does not fit on a single page | |
aaa1276e UD |
1402 | @include libm-err.texi |
1403 | ||
28f540f4 RM |
1404 | @node Pseudo-Random Numbers |
1405 | @section Pseudo-Random Numbers | |
1406 | @cindex random numbers | |
1407 | @cindex pseudo-random numbers | |
1408 | @cindex seed (for random numbers) | |
1409 | ||
1410 | This section describes the GNU facilities for generating a series of | |
1411 | pseudo-random numbers. The numbers generated are not truly random; | |
7a68c94a UD |
1412 | typically, they form a sequence that repeats periodically, with a period |
1413 | so large that you can ignore it for ordinary purposes. The random | |
1414 | number generator works by remembering a @dfn{seed} value which it uses | |
1415 | to compute the next random number and also to compute a new seed. | |
28f540f4 RM |
1416 | |
1417 | Although the generated numbers look unpredictable within one run of a | |
1418 | program, the sequence of numbers is @emph{exactly the same} from one run | |
1419 | to the next. This is because the initial seed is always the same. This | |
1420 | is convenient when you are debugging a program, but it is unhelpful if | |
7a68c94a UD |
1421 | you want the program to behave unpredictably. If you want a different |
1422 | pseudo-random series each time your program runs, you must specify a | |
1423 | different seed each time. For ordinary purposes, basing the seed on the | |
92dcaa3e FW |
1424 | current time works well. For random numbers in cryptography, |
1425 | @pxref{Unpredictable Bytes}. | |
28f540f4 | 1426 | |
04b9968b | 1427 | You can obtain repeatable sequences of numbers on a particular machine type |
28f540f4 RM |
1428 | by specifying the same initial seed value for the random number |
1429 | generator. There is no standard meaning for a particular seed value; | |
1430 | the same seed, used in different C libraries or on different CPU types, | |
1431 | will give you different random numbers. | |
1432 | ||
1f77f049 | 1433 | @Theglibc{} supports the standard @w{ISO C} random number functions |
7a68c94a UD |
1434 | plus two other sets derived from BSD and SVID. The BSD and @w{ISO C} |
1435 | functions provide identical, somewhat limited functionality. If only a | |
1436 | small number of random bits are required, we recommend you use the | |
1437 | @w{ISO C} interface, @code{rand} and @code{srand}. The SVID functions | |
1438 | provide a more flexible interface, which allows better random number | |
1439 | generator algorithms, provides more random bits (up to 48) per call, and | |
1440 | can provide random floating-point numbers. These functions are required | |
1441 | by the XPG standard and therefore will be present in all modern Unix | |
1442 | systems. | |
28f540f4 RM |
1443 | |
1444 | @menu | |
7a68c94a UD |
1445 | * ISO Random:: @code{rand} and friends. |
1446 | * BSD Random:: @code{random} and friends. | |
1447 | * SVID Random:: @code{drand48} and friends. | |
28f540f4 RM |
1448 | @end menu |
1449 | ||
f65fd747 UD |
1450 | @node ISO Random |
1451 | @subsection ISO C Random Number Functions | |
28f540f4 RM |
1452 | |
1453 | This section describes the random number functions that are part of | |
f65fd747 | 1454 | the @w{ISO C} standard. |
28f540f4 RM |
1455 | |
1456 | To use these facilities, you should include the header file | |
1457 | @file{stdlib.h} in your program. | |
1458 | @pindex stdlib.h | |
1459 | ||
28f540f4 | 1460 | @deftypevr Macro int RAND_MAX |
d08a7e4c | 1461 | @standards{ISO, stdlib.h} |
7a68c94a | 1462 | The value of this macro is an integer constant representing the largest |
1f77f049 | 1463 | value the @code{rand} function can return. In @theglibc{}, it is |
7a68c94a UD |
1464 | @code{2147483647}, which is the largest signed integer representable in |
1465 | 32 bits. In other libraries, it may be as low as @code{32767}. | |
28f540f4 RM |
1466 | @end deftypevr |
1467 | ||
ca34d7a7 | 1468 | @deftypefun int rand (void) |
d08a7e4c | 1469 | @standards{ISO, stdlib.h} |
27aaa791 AO |
1470 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} |
1471 | @c Just calls random. | |
28f540f4 | 1472 | The @code{rand} function returns the next pseudo-random number in the |
7a68c94a | 1473 | series. The value ranges from @code{0} to @code{RAND_MAX}. |
28f540f4 RM |
1474 | @end deftypefun |
1475 | ||
28f540f4 | 1476 | @deftypefun void srand (unsigned int @var{seed}) |
d08a7e4c | 1477 | @standards{ISO, stdlib.h} |
27aaa791 AO |
1478 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} |
1479 | @c Alias to srandom. | |
28f540f4 RM |
1480 | This function establishes @var{seed} as the seed for a new series of |
1481 | pseudo-random numbers. If you call @code{rand} before a seed has been | |
1482 | established with @code{srand}, it uses the value @code{1} as a default | |
1483 | seed. | |
1484 | ||
7a68c94a UD |
1485 | To produce a different pseudo-random series each time your program is |
1486 | run, do @code{srand (time (0))}. | |
28f540f4 RM |
1487 | @end deftypefun |
1488 | ||
7a68c94a UD |
1489 | POSIX.1 extended the C standard functions to support reproducible random |
1490 | numbers in multi-threaded programs. However, the extension is badly | |
1491 | designed and unsuitable for serious work. | |
61eb22d3 | 1492 | |
61eb22d3 | 1493 | @deftypefun int rand_r (unsigned int *@var{seed}) |
d08a7e4c | 1494 | @standards{POSIX.1, stdlib.h} |
27aaa791 | 1495 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
61eb22d3 | 1496 | This function returns a random number in the range 0 to @code{RAND_MAX} |
7a68c94a UD |
1497 | just as @code{rand} does. However, all its state is stored in the |
1498 | @var{seed} argument. This means the RNG's state can only have as many | |
1499 | bits as the type @code{unsigned int} has. This is far too few to | |
1500 | provide a good RNG. | |
61eb22d3 | 1501 | |
7a68c94a UD |
1502 | If your program requires a reentrant RNG, we recommend you use the |
1503 | reentrant GNU extensions to the SVID random number generator. The | |
1504 | POSIX.1 interface should only be used when the GNU extensions are not | |
1505 | available. | |
61eb22d3 UD |
1506 | @end deftypefun |
1507 | ||
1508 | ||
28f540f4 RM |
1509 | @node BSD Random |
1510 | @subsection BSD Random Number Functions | |
1511 | ||
1512 | This section describes a set of random number generation functions that | |
1513 | are derived from BSD. There is no advantage to using these functions | |
1f77f049 | 1514 | with @theglibc{}; we support them for BSD compatibility only. |
28f540f4 RM |
1515 | |
1516 | The prototypes for these functions are in @file{stdlib.h}. | |
1517 | @pindex stdlib.h | |
1518 | ||
0423ee17 | 1519 | @deftypefun {long int} random (void) |
d08a7e4c | 1520 | @standards{BSD, stdlib.h} |
27aaa791 AO |
1521 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} |
1522 | @c Takes a lock and calls random_r with an automatic variable and the | |
1523 | @c global state, while holding a lock. | |
28f540f4 | 1524 | This function returns the next pseudo-random number in the sequence. |
8c5c2600 | 1525 | The value returned ranges from @code{0} to @code{2147483647}. |
ca34d7a7 | 1526 | |
48b22986 | 1527 | @strong{NB:} Temporarily this function was defined to return a |
0423ee17 UD |
1528 | @code{int32_t} value to indicate that the return value always contains |
1529 | 32 bits even if @code{long int} is wider. The standard demands it | |
1530 | differently. Users must always be aware of the 32-bit limitation, | |
1531 | though. | |
28f540f4 RM |
1532 | @end deftypefun |
1533 | ||
28f540f4 | 1534 | @deftypefun void srandom (unsigned int @var{seed}) |
d08a7e4c | 1535 | @standards{BSD, stdlib.h} |
27aaa791 AO |
1536 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} |
1537 | @c Takes a lock and calls srandom_r with an automatic variable and a | |
1538 | @c static buffer. There's no MT-safety issue because the static buffer | |
1539 | @c is internally protected by a lock, although other threads may modify | |
1540 | @c the set state before it is used. | |
7a68c94a UD |
1541 | The @code{srandom} function sets the state of the random number |
1542 | generator based on the integer @var{seed}. If you supply a @var{seed} value | |
28f540f4 RM |
1543 | of @code{1}, this will cause @code{random} to reproduce the default set |
1544 | of random numbers. | |
1545 | ||
7a68c94a UD |
1546 | To produce a different set of pseudo-random numbers each time your |
1547 | program runs, do @code{srandom (time (0))}. | |
28f540f4 RM |
1548 | @end deftypefun |
1549 | ||
8ded91fb | 1550 | @deftypefun {char *} initstate (unsigned int @var{seed}, char *@var{state}, size_t @var{size}) |
d08a7e4c | 1551 | @standards{BSD, stdlib.h} |
27aaa791 | 1552 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} |
28f540f4 RM |
1553 | The @code{initstate} function is used to initialize the random number |
1554 | generator state. The argument @var{state} is an array of @var{size} | |
7a68c94a UD |
1555 | bytes, used to hold the state information. It is initialized based on |
1556 | @var{seed}. The size must be between 8 and 256 bytes, and should be a | |
1557 | power of two. The bigger the @var{state} array, the better. | |
28f540f4 RM |
1558 | |
1559 | The return value is the previous value of the state information array. | |
1560 | You can use this value later as an argument to @code{setstate} to | |
1561 | restore that state. | |
1562 | @end deftypefun | |
1563 | ||
8ded91fb | 1564 | @deftypefun {char *} setstate (char *@var{state}) |
d08a7e4c | 1565 | @standards{BSD, stdlib.h} |
27aaa791 | 1566 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} |
28f540f4 RM |
1567 | The @code{setstate} function restores the random number state |
1568 | information @var{state}. The argument must have been the result of | |
2c6fe0bd | 1569 | a previous call to @var{initstate} or @var{setstate}. |
28f540f4 RM |
1570 | |
1571 | The return value is the previous value of the state information array. | |
f2ea0f5b | 1572 | You can use this value later as an argument to @code{setstate} to |
28f540f4 | 1573 | restore that state. |
a785f6c5 UD |
1574 | |
1575 | If the function fails the return value is @code{NULL}. | |
28f540f4 | 1576 | @end deftypefun |
b4012b75 | 1577 | |
4c78249d UD |
1578 | The four functions described so far in this section all work on a state |
1579 | which is shared by all threads. The state is not directly accessible to | |
1580 | the user and can only be modified by these functions. This makes it | |
1581 | hard to deal with situations where each thread should have its own | |
1582 | pseudo-random number generator. | |
1583 | ||
1f77f049 | 1584 | @Theglibc{} contains four additional functions which contain the |
4c78249d | 1585 | state as an explicit parameter and therefore make it possible to handle |
60843ffb | 1586 | thread-local PRNGs. Besides this there is no difference. In fact, the |
4c78249d UD |
1587 | four functions already discussed are implemented internally using the |
1588 | following interfaces. | |
1589 | ||
1590 | The @file{stdlib.h} header contains a definition of the following type: | |
1591 | ||
4c78249d | 1592 | @deftp {Data Type} {struct random_data} |
d08a7e4c | 1593 | @standards{GNU, stdlib.h} |
4c78249d UD |
1594 | |
1595 | Objects of type @code{struct random_data} contain the information | |
1596 | necessary to represent the state of the PRNG. Although a complete | |
1597 | definition of the type is present the type should be treated as opaque. | |
1598 | @end deftp | |
1599 | ||
1600 | The functions modifying the state follow exactly the already described | |
1601 | functions. | |
1602 | ||
4c78249d | 1603 | @deftypefun int random_r (struct random_data *restrict @var{buf}, int32_t *restrict @var{result}) |
d08a7e4c | 1604 | @standards{GNU, stdlib.h} |
27aaa791 | 1605 | @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}} |
4c78249d UD |
1606 | The @code{random_r} function behaves exactly like the @code{random} |
1607 | function except that it uses and modifies the state in the object | |
1608 | pointed to by the first parameter instead of the global state. | |
1609 | @end deftypefun | |
1610 | ||
4c78249d | 1611 | @deftypefun int srandom_r (unsigned int @var{seed}, struct random_data *@var{buf}) |
d08a7e4c | 1612 | @standards{GNU, stdlib.h} |
27aaa791 | 1613 | @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}} |
4c78249d UD |
1614 | The @code{srandom_r} function behaves exactly like the @code{srandom} |
1615 | function except that it uses and modifies the state in the object | |
1616 | pointed to by the second parameter instead of the global state. | |
1617 | @end deftypefun | |
1618 | ||
4c78249d | 1619 | @deftypefun int initstate_r (unsigned int @var{seed}, char *restrict @var{statebuf}, size_t @var{statelen}, struct random_data *restrict @var{buf}) |
d08a7e4c | 1620 | @standards{GNU, stdlib.h} |
27aaa791 | 1621 | @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}} |
4c78249d UD |
1622 | The @code{initstate_r} function behaves exactly like the @code{initstate} |
1623 | function except that it uses and modifies the state in the object | |
1624 | pointed to by the fourth parameter instead of the global state. | |
1625 | @end deftypefun | |
1626 | ||
4c78249d | 1627 | @deftypefun int setstate_r (char *restrict @var{statebuf}, struct random_data *restrict @var{buf}) |
d08a7e4c | 1628 | @standards{GNU, stdlib.h} |
27aaa791 | 1629 | @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}} |
4c78249d UD |
1630 | The @code{setstate_r} function behaves exactly like the @code{setstate} |
1631 | function except that it uses and modifies the state in the object | |
1632 | pointed to by the first parameter instead of the global state. | |
1633 | @end deftypefun | |
1634 | ||
b4012b75 UD |
1635 | @node SVID Random |
1636 | @subsection SVID Random Number Function | |
1637 | ||
1638 | The C library on SVID systems contains yet another kind of random number | |
1639 | generator functions. They use a state of 48 bits of data. The user can | |
7a68c94a | 1640 | choose among a collection of functions which return the random bits |
b4012b75 UD |
1641 | in different forms. |
1642 | ||
04b9968b | 1643 | Generally there are two kinds of function. The first uses a state of |
b4012b75 | 1644 | the random number generator which is shared among several functions and |
04b9968b UD |
1645 | by all threads of the process. The second requires the user to handle |
1646 | the state. | |
b4012b75 UD |
1647 | |
1648 | All functions have in common that they use the same congruential | |
1649 | formula with the same constants. The formula is | |
1650 | ||
1651 | @smallexample | |
1652 | Y = (a * X + c) mod m | |
1653 | @end smallexample | |
1654 | ||
1655 | @noindent | |
1656 | where @var{X} is the state of the generator at the beginning and | |
1657 | @var{Y} the state at the end. @code{a} and @code{c} are constants | |
04b9968b | 1658 | determining the way the generator works. By default they are |
b4012b75 UD |
1659 | |
1660 | @smallexample | |
1661 | a = 0x5DEECE66D = 25214903917 | |
1662 | c = 0xb = 11 | |
1663 | @end smallexample | |
1664 | ||
1665 | @noindent | |
1666 | but they can also be changed by the user. @code{m} is of course 2^48 | |
04b9968b | 1667 | since the state consists of a 48-bit array. |
b4012b75 | 1668 | |
f2615995 UD |
1669 | The prototypes for these functions are in @file{stdlib.h}. |
1670 | @pindex stdlib.h | |
1671 | ||
b4012b75 | 1672 | |
55c14926 | 1673 | @deftypefun double drand48 (void) |
d08a7e4c | 1674 | @standards{SVID, stdlib.h} |
27aaa791 AO |
1675 | @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} |
1676 | @c Uses of the static state buffer are not guarded by a lock (thus | |
1677 | @c @mtasurace:drand48), so they may be found or left at a | |
1678 | @c partially-updated state in case of calls from within signal handlers | |
1679 | @c or cancellation. None of this will break safety rules or invoke | |
1680 | @c undefined behavior, but it may affect randomness. | |
b4012b75 UD |
1681 | This function returns a @code{double} value in the range of @code{0.0} |
1682 | to @code{1.0} (exclusive). The random bits are determined by the global | |
1683 | state of the random number generator in the C library. | |
1684 | ||
04b9968b | 1685 | Since the @code{double} type according to @w{IEEE 754} has a 52-bit |
b4012b75 UD |
1686 | mantissa this means 4 bits are not initialized by the random number |
1687 | generator. These are (of course) chosen to be the least significant | |
1688 | bits and they are initialized to @code{0}. | |
1689 | @end deftypefun | |
1690 | ||
b4012b75 | 1691 | @deftypefun double erand48 (unsigned short int @var{xsubi}[3]) |
d08a7e4c | 1692 | @standards{SVID, stdlib.h} |
27aaa791 AO |
1693 | @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} |
1694 | @c The static buffer is just initialized with default parameters, which | |
1695 | @c are later read to advance the state held in xsubi. | |
b4012b75 | 1696 | This function returns a @code{double} value in the range of @code{0.0} |
04b9968b | 1697 | to @code{1.0} (exclusive), similarly to @code{drand48}. The argument is |
b4012b75 UD |
1698 | an array describing the state of the random number generator. |
1699 | ||
1700 | This function can be called subsequently since it updates the array to | |
1701 | guarantee random numbers. The array should have been initialized before | |
04b9968b | 1702 | initial use to obtain reproducible results. |
b4012b75 UD |
1703 | @end deftypefun |
1704 | ||
55c14926 | 1705 | @deftypefun {long int} lrand48 (void) |
d08a7e4c | 1706 | @standards{SVID, stdlib.h} |
27aaa791 | 1707 | @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} |
04b9968b | 1708 | The @code{lrand48} function returns an integer value in the range of |
b4012b75 | 1709 | @code{0} to @code{2^31} (exclusive). Even if the size of the @code{long |
04b9968b | 1710 | int} type can take more than 32 bits, no higher numbers are returned. |
b4012b75 UD |
1711 | The random bits are determined by the global state of the random number |
1712 | generator in the C library. | |
1713 | @end deftypefun | |
1714 | ||
b4012b75 | 1715 | @deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3]) |
d08a7e4c | 1716 | @standards{SVID, stdlib.h} |
27aaa791 | 1717 | @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} |
b4012b75 UD |
1718 | This function is similar to the @code{lrand48} function in that it |
1719 | returns a number in the range of @code{0} to @code{2^31} (exclusive) but | |
1720 | the state of the random number generator used to produce the random bits | |
1721 | is determined by the array provided as the parameter to the function. | |
1722 | ||
04b9968b UD |
1723 | The numbers in the array are updated afterwards so that subsequent calls |
1724 | to this function yield different results (as is expected of a random | |
1725 | number generator). The array should have been initialized before the | |
1726 | first call to obtain reproducible results. | |
b4012b75 UD |
1727 | @end deftypefun |
1728 | ||
55c14926 | 1729 | @deftypefun {long int} mrand48 (void) |
d08a7e4c | 1730 | @standards{SVID, stdlib.h} |
27aaa791 | 1731 | @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} |
b4012b75 UD |
1732 | The @code{mrand48} function is similar to @code{lrand48}. The only |
1733 | difference is that the numbers returned are in the range @code{-2^31} to | |
1734 | @code{2^31} (exclusive). | |
1735 | @end deftypefun | |
1736 | ||
b4012b75 | 1737 | @deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3]) |
d08a7e4c | 1738 | @standards{SVID, stdlib.h} |
27aaa791 | 1739 | @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} |
b4012b75 UD |
1740 | The @code{jrand48} function is similar to @code{nrand48}. The only |
1741 | difference is that the numbers returned are in the range @code{-2^31} to | |
1742 | @code{2^31} (exclusive). For the @code{xsubi} parameter the same | |
1743 | requirements are necessary. | |
1744 | @end deftypefun | |
1745 | ||
1746 | The internal state of the random number generator can be initialized in | |
04b9968b | 1747 | several ways. The methods differ in the completeness of the |
b4012b75 UD |
1748 | information provided. |
1749 | ||
04b9968b | 1750 | @deftypefun void srand48 (long int @var{seedval}) |
d08a7e4c | 1751 | @standards{SVID, stdlib.h} |
27aaa791 | 1752 | @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} |
b4012b75 | 1753 | The @code{srand48} function sets the most significant 32 bits of the |
04b9968b | 1754 | internal state of the random number generator to the least |
f2ea0f5b UD |
1755 | significant 32 bits of the @var{seedval} parameter. The lower 16 bits |
1756 | are initialized to the value @code{0x330E}. Even if the @code{long | |
04b9968b | 1757 | int} type contains more than 32 bits only the lower 32 bits are used. |
b4012b75 | 1758 | |
04b9968b UD |
1759 | Owing to this limitation, initialization of the state of this |
1760 | function is not very useful. But it makes it easy to use a construct | |
b4012b75 UD |
1761 | like @code{srand48 (time (0))}. |
1762 | ||
1763 | A side-effect of this function is that the values @code{a} and @code{c} | |
1764 | from the internal state, which are used in the congruential formula, | |
1765 | are reset to the default values given above. This is of importance once | |
04b9968b | 1766 | the user has called the @code{lcong48} function (see below). |
b4012b75 UD |
1767 | @end deftypefun |
1768 | ||
b4012b75 | 1769 | @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3]) |
d08a7e4c | 1770 | @standards{SVID, stdlib.h} |
27aaa791 | 1771 | @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} |
b4012b75 | 1772 | The @code{seed48} function initializes all 48 bits of the state of the |
04b9968b | 1773 | internal random number generator from the contents of the parameter |
b4012b75 | 1774 | @var{seed16v}. Here the lower 16 bits of the first element of |
60843ffb | 1775 | @var{seed16v} initialize the least significant 16 bits of the internal |
b4012b75 UD |
1776 | state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order |
1777 | 16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]} | |
1778 | initialize the most significant 16 bits of the state. | |
1779 | ||
1780 | Unlike @code{srand48} this function lets the user initialize all 48 bits | |
1781 | of the state. | |
1782 | ||
1783 | The value returned by @code{seed48} is a pointer to an array containing | |
1784 | the values of the internal state before the change. This might be | |
1785 | useful to restart the random number generator at a certain state. | |
04b9968b | 1786 | Otherwise the value can simply be ignored. |
b4012b75 UD |
1787 | |
1788 | As for @code{srand48}, the values @code{a} and @code{c} from the | |
1789 | congruential formula are reset to the default values. | |
1790 | @end deftypefun | |
1791 | ||
1792 | There is one more function to initialize the random number generator | |
04b9968b UD |
1793 | which enables you to specify even more information by allowing you to |
1794 | change the parameters in the congruential formula. | |
b4012b75 | 1795 | |
b4012b75 | 1796 | @deftypefun void lcong48 (unsigned short int @var{param}[7]) |
d08a7e4c | 1797 | @standards{SVID, stdlib.h} |
27aaa791 | 1798 | @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} |
b4012b75 UD |
1799 | The @code{lcong48} function allows the user to change the complete state |
1800 | of the random number generator. Unlike @code{srand48} and | |
1801 | @code{seed48}, this function also changes the constants in the | |
1802 | congruential formula. | |
1803 | ||
1804 | From the seven elements in the array @var{param} the least significant | |
1805 | 16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]} | |
04b9968b | 1806 | determine the initial state, the least significant 16 bits of |
b4012b75 | 1807 | @code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit |
04b9968b | 1808 | constant @code{a} and @code{@var{param}[6]} determines the 16-bit value |
b4012b75 UD |
1809 | @code{c}. |
1810 | @end deftypefun | |
1811 | ||
1812 | All the above functions have in common that they use the global | |
1813 | parameters for the congruential formula. In multi-threaded programs it | |
1814 | might sometimes be useful to have different parameters in different | |
1815 | threads. For this reason all the above functions have a counterpart | |
1816 | which works on a description of the random number generator in the | |
1817 | user-supplied buffer instead of the global state. | |
1818 | ||
1819 | Please note that it is no problem if several threads use the global | |
1820 | state if all threads use the functions which take a pointer to an array | |
1821 | containing the state. The random numbers are computed following the | |
1822 | same loop but if the state in the array is different all threads will | |
04b9968b | 1823 | obtain an individual random number generator. |
b4012b75 | 1824 | |
04b9968b UD |
1825 | The user-supplied buffer must be of type @code{struct drand48_data}. |
1826 | This type should be regarded as opaque and not manipulated directly. | |
b4012b75 | 1827 | |
b4012b75 | 1828 | @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result}) |
d08a7e4c | 1829 | @standards{GNU, stdlib.h} |
27aaa791 | 1830 | @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} |
b4012b75 | 1831 | This function is equivalent to the @code{drand48} function with the |
04b9968b UD |
1832 | difference that it does not modify the global random number generator |
1833 | parameters but instead the parameters in the buffer supplied through the | |
1834 | pointer @var{buffer}. The random number is returned in the variable | |
1835 | pointed to by @var{result}. | |
b4012b75 | 1836 | |
04b9968b | 1837 | The return value of the function indicates whether the call succeeded. |
b4012b75 UD |
1838 | If the value is less than @code{0} an error occurred and @var{errno} is |
1839 | set to indicate the problem. | |
1840 | ||
1841 | This function is a GNU extension and should not be used in portable | |
1842 | programs. | |
1843 | @end deftypefun | |
1844 | ||
b4012b75 | 1845 | @deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result}) |
d08a7e4c | 1846 | @standards{GNU, stdlib.h} |
27aaa791 | 1847 | @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} |
04b9968b UD |
1848 | The @code{erand48_r} function works like @code{erand48}, but in addition |
1849 | it takes an argument @var{buffer} which describes the random number | |
1850 | generator. The state of the random number generator is taken from the | |
1851 | @code{xsubi} array, the parameters for the congruential formula from the | |
1852 | global random number generator data. The random number is returned in | |
1853 | the variable pointed to by @var{result}. | |
b4012b75 | 1854 | |
04b9968b | 1855 | The return value is non-negative if the call succeeded. |
b4012b75 UD |
1856 | |
1857 | This function is a GNU extension and should not be used in portable | |
1858 | programs. | |
1859 | @end deftypefun | |
1860 | ||
8ded91fb | 1861 | @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, long int *@var{result}) |
d08a7e4c | 1862 | @standards{GNU, stdlib.h} |
27aaa791 | 1863 | @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} |
04b9968b UD |
1864 | This function is similar to @code{lrand48}, but in addition it takes a |
1865 | pointer to a buffer describing the state of the random number generator | |
1866 | just like @code{drand48}. | |
b4012b75 UD |
1867 | |
1868 | If the return value of the function is non-negative the variable pointed | |
1869 | to by @var{result} contains the result. Otherwise an error occurred. | |
1870 | ||
1871 | This function is a GNU extension and should not be used in portable | |
1872 | programs. | |
1873 | @end deftypefun | |
1874 | ||
b4012b75 | 1875 | @deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result}) |
d08a7e4c | 1876 | @standards{GNU, stdlib.h} |
27aaa791 | 1877 | @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} |
b4012b75 | 1878 | The @code{nrand48_r} function works like @code{nrand48} in that it |
04b9968b | 1879 | produces a random number in the range @code{0} to @code{2^31}. But instead |
b4012b75 UD |
1880 | of using the global parameters for the congruential formula it uses the |
1881 | information from the buffer pointed to by @var{buffer}. The state is | |
1882 | described by the values in @var{xsubi}. | |
1883 | ||
1884 | If the return value is non-negative the variable pointed to by | |
1885 | @var{result} contains the result. | |
1886 | ||
1887 | This function is a GNU extension and should not be used in portable | |
1888 | programs. | |
1889 | @end deftypefun | |
1890 | ||
8ded91fb | 1891 | @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, long int *@var{result}) |
d08a7e4c | 1892 | @standards{GNU, stdlib.h} |
27aaa791 | 1893 | @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} |
04b9968b UD |
1894 | This function is similar to @code{mrand48} but like the other reentrant |
1895 | functions it uses the random number generator described by the value in | |
b4012b75 UD |
1896 | the buffer pointed to by @var{buffer}. |
1897 | ||
1898 | If the return value is non-negative the variable pointed to by | |
1899 | @var{result} contains the result. | |
1900 | ||
1901 | This function is a GNU extension and should not be used in portable | |
1902 | programs. | |
1903 | @end deftypefun | |
1904 | ||
b4012b75 | 1905 | @deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result}) |
d08a7e4c | 1906 | @standards{GNU, stdlib.h} |
27aaa791 | 1907 | @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} |
04b9968b | 1908 | The @code{jrand48_r} function is similar to @code{jrand48}. Like the |
b4012b75 UD |
1909 | other reentrant functions of this function family it uses the |
1910 | congruential formula parameters from the buffer pointed to by | |
1911 | @var{buffer}. | |
1912 | ||
1913 | If the return value is non-negative the variable pointed to by | |
1914 | @var{result} contains the result. | |
1915 | ||
1916 | This function is a GNU extension and should not be used in portable | |
1917 | programs. | |
1918 | @end deftypefun | |
1919 | ||
04b9968b UD |
1920 | Before any of the above functions are used the buffer of type |
1921 | @code{struct drand48_data} should be initialized. The easiest way to do | |
1922 | this is to fill the whole buffer with null bytes, e.g. by | |
b4012b75 UD |
1923 | |
1924 | @smallexample | |
1925 | memset (buffer, '\0', sizeof (struct drand48_data)); | |
1926 | @end smallexample | |
1927 | ||
1928 | @noindent | |
f2ea0f5b | 1929 | Using any of the reentrant functions of this family now will |
b4012b75 UD |
1930 | automatically initialize the random number generator to the default |
1931 | values for the state and the parameters of the congruential formula. | |
1932 | ||
04b9968b | 1933 | The other possibility is to use any of the functions which explicitly |
b4012b75 | 1934 | initialize the buffer. Though it might be obvious how to initialize the |
04b9968b | 1935 | buffer from looking at the parameter to the function, it is highly |
b4012b75 UD |
1936 | recommended to use these functions since the result might not always be |
1937 | what you expect. | |
1938 | ||
b4012b75 | 1939 | @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer}) |
d08a7e4c | 1940 | @standards{GNU, stdlib.h} |
27aaa791 | 1941 | @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} |
b4012b75 | 1942 | The description of the random number generator represented by the |
04b9968b | 1943 | information in @var{buffer} is initialized similarly to what the function |
f2ea0f5b UD |
1944 | @code{srand48} does. The state is initialized from the parameter |
1945 | @var{seedval} and the parameters for the congruential formula are | |
04b9968b | 1946 | initialized to their default values. |
b4012b75 UD |
1947 | |
1948 | If the return value is non-negative the function call succeeded. | |
1949 | ||
1950 | This function is a GNU extension and should not be used in portable | |
1951 | programs. | |
1952 | @end deftypefun | |
1953 | ||
b4012b75 | 1954 | @deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer}) |
d08a7e4c | 1955 | @standards{GNU, stdlib.h} |
27aaa791 | 1956 | @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} |
b4012b75 UD |
1957 | This function is similar to @code{srand48_r} but like @code{seed48} it |
1958 | initializes all 48 bits of the state from the parameter @var{seed16v}. | |
1959 | ||
1960 | If the return value is non-negative the function call succeeded. It | |
1961 | does not return a pointer to the previous state of the random number | |
04b9968b UD |
1962 | generator like the @code{seed48} function does. If the user wants to |
1963 | preserve the state for a later re-run s/he can copy the whole buffer | |
b4012b75 UD |
1964 | pointed to by @var{buffer}. |
1965 | ||
1966 | This function is a GNU extension and should not be used in portable | |
1967 | programs. | |
1968 | @end deftypefun | |
1969 | ||
b4012b75 | 1970 | @deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer}) |
d08a7e4c | 1971 | @standards{GNU, stdlib.h} |
27aaa791 | 1972 | @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} |
b4012b75 | 1973 | This function initializes all aspects of the random number generator |
04b9968b UD |
1974 | described in @var{buffer} with the data in @var{param}. Here it is |
1975 | especially true that the function does more than just copying the | |
1976 | contents of @var{param} and @var{buffer}. More work is required and | |
1977 | therefore it is important to use this function rather than initializing | |
1978 | the random number generator directly. | |
b4012b75 UD |
1979 | |
1980 | If the return value is non-negative the function call succeeded. | |
1981 | ||
1982 | This function is a GNU extension and should not be used in portable | |
1983 | programs. | |
1984 | @end deftypefun | |
7a68c94a UD |
1985 | |
1986 | @node FP Function Optimizations | |
1987 | @section Is Fast Code or Small Code preferred? | |
1988 | @cindex Optimization | |
1989 | ||
04b9968b UD |
1990 | If an application uses many floating point functions it is often the case |
1991 | that the cost of the function calls themselves is not negligible. | |
1992 | Modern processors can often execute the operations themselves | |
1993 | very fast, but the function call disrupts the instruction pipeline. | |
7a68c94a | 1994 | |
1f77f049 | 1995 | For this reason @theglibc{} provides optimizations for many of the |
04b9968b UD |
1996 | frequently-used math functions. When GNU CC is used and the user |
1997 | activates the optimizer, several new inline functions and macros are | |
7a68c94a | 1998 | defined. These new functions and macros have the same names as the |
04b9968b | 1999 | library functions and so are used instead of the latter. In the case of |
7a68c94a | 2000 | inline functions the compiler will decide whether it is reasonable to |
04b9968b | 2001 | use them, and this decision is usually correct. |
7a68c94a | 2002 | |
04b9968b UD |
2003 | This means that no calls to the library functions may be necessary, and |
2004 | can increase the speed of generated code significantly. The drawback is | |
2005 | that code size will increase, and the increase is not always negligible. | |
7a68c94a | 2006 | |
60843ffb | 2007 | There are two kinds of inline functions: those that give the same result |
378fbeb4 UD |
2008 | as the library functions and others that might not set @code{errno} and |
2009 | might have a reduced precision and/or argument range in comparison with | |
2010 | the library functions. The latter inline functions are only available | |
2011 | if the flag @code{-ffast-math} is given to GNU CC. | |
aa847ee5 | 2012 | |
7a68c94a UD |
2013 | In cases where the inline functions and macros are not wanted the symbol |
2014 | @code{__NO_MATH_INLINES} should be defined before any system header is | |
04b9968b UD |
2015 | included. This will ensure that only library functions are used. Of |
2016 | course, it can be determined for each file in the project whether | |
2017 | giving this option is preferable or not. | |
2018 | ||
2019 | Not all hardware implements the entire @w{IEEE 754} standard, and even | |
2020 | if it does there may be a substantial performance penalty for using some | |
2021 | of its features. For example, enabling traps on some processors forces | |
2022 | the FPU to run un-pipelined, which can more than double calculation time. | |
7a68c94a | 2023 | @c ***Add explanation of -lieee, -mieee. |