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