1#
2#Copyright (C) 1993 by Sun Microsystems, Inc. All rights reserved.
3#
4#Developed at SunPro, a Sun Microsystems, Inc. business.
5#Permission to use, copy, modify, and distribute this
6#software is freely granted, provided that this notice
7#is preserved.
8#
9@node Math
10@chapter Mathematical Functions (@file{math.h})
11
12This chapter groups a wide variety of mathematical functions.  The
13corresponding definitions and declarations are in @file{math.h}.
14The definition of HUGE_VAL from @file{math.h} is of particular interest.
15
16@enumerate
17@item
18The representation of infinity as a @code{double} is defined as
19@code{HUGE_VAL}; this number is returned on overflow by many functions.
20The macro @code{HUGE_VALF} is a corresponding value for @code{float}.
21@end enumerate
22
23Alternative declarations of the mathematical functions, which exploit
24specific machine capabilities to operate faster---but generally have
25less error checking and may reflect additional limitations on some
26machines---are available when you include @file{fastmath.h} instead of
27@file{math.h}.
28
29@menu
30* version::	Version of library
31* Function acos::	Arccosine
32* Function acosh::	Inverse hyperbolic cosine
33* Function asin::	Arcsine
34* Function asinh::	Inverse hyperbolic sine
35* Function atan::	Arctangent
36* Function atan2::	Arctangent of y/x
37* Function atanh::	Inverse hyperbolic tangent
38* Function jN::	        Bessel functions (jN, yN)
39* Function cbrt::	Cube root
40* Function copysign::	Sign of Y, magnitude of X
41* Function cosh::	Hyperbolic cosine
42* Function erf::		Error function (erf, erfc)
43* Function exp::		Exponential, base e
44* Function exp10::	Exponential, base 10
45* Function exp2::	Exponential, base 2
46* Function expm1::	Exponential, base e, of x - 1
47* Function fabs::	Absolute value (magnitude)
48* Function fdim::	Positive difference
49* Function floor::	Floor and ceiling (floor, ceil)
50* Function fma::		Floating multiply add
51* Function fmax::	Maximum
52* Function fmin::	Minimum
53* Function fmod::	Floating-point remainder (modulo)
54* Function fpclassify::	Floating-point classification macro
55* Function frexp::	Split floating-point number
56* Function gamma::	Logarithmic gamma function
57* Function hypot::	Distance from origin
58* Function ilogb::	Get exponent
59* Function infinity::	Floating infinity
60* Function isgreater::	Comparison macros
61* Function ldexp::	Scale by a power of 2
62* Function log::		Natural logarithms
63* Function log10::	Base 10 logarithms
64* Function log1p::	Log of 1 + X
65* Function log2::	Base 2 logarithms
66* Function logb::	Get exponent
67* Function lrint::	Round to integer
68* Function lround::	Round to integer, away from zero (lround, llround)
69* Function modf::	Split fractional and integer parts
70* Function nan::		Floating Not a Number
71* Function nearbyint::	Round to integer
72* Function nextafter::	Get next representable number
73* Function pow::		X to the power Y
74* Function pow10::	10 to the power X
75* Function remainder::	remainder of X divided by Y
76* Function remquo::	Remainder and part of quotient
77* Function rint::	Round to integer
78* Function round::	Round to integer, away from zero
79* Function scalbn::	Scale by a power of FLT_RADIX (2)
80* Function signbit::	Does floating-point number have negative sign?
81* Function sin::		Sine or cosine (sin, cos)
82* Function sinh::	Hyperbolic sine
83* Function sqrt::	Positive square root
84* Function tan::		Tangent
85* Function tanh::	Hyperbolic tangent
86* Function trunc::	Round to integer, towards zero
87@end menu
88
89@page
90@node version
91@section Error Handling
92
93There are two different versions of the math library routines: IEEE
94and POSIX.  The version may be selected at runtime by
95setting the global variable @code{_LIB_VERSION}, defined in
96@file{math.h}.  It may be set to one of the following constants defined
97in @file{math.h}: @code{_IEEE_} or @code{_POSIX_}.
98The @code{_LIB_VERSION} variable is not specific to any
99thread, and changing it will affect all threads.
100
101The versions of the library differ only in the setting of @code{errno}.
102
103In IEEE mode, @code{errno} is never set.
104
105In POSIX mode, @code{errno} is set correctly.
106
107The library is set to IEEE mode by default.
108
109The majority of the floating-point math functions are written
110so as to produce the floating-point exceptions (e.g. "invalid",
111"divide-by-zero") as required by the C and POSIX standards, for
112floating-point implementations that support them.  Newlib does not provide
113the floating-point exception access routines defined in the standards
114for fenv.h, though, which is why they are considered unsupported.  It is
115mentioned in case you have separately-provided access routines so that
116you are aware that they can be caused.
117
118@section Standards Compliance And Portability
119Most of the individual function descriptions describe the standards to which
120each function complies.  However, these descriptions are mostly out of date,
121having been written before C99 was released.  One of these days we'll get
122around to updating the rest of them.  (If you'd like to help, please let us
123know.)
124
125``C99'' refers to ISO/IEC 9899:1999, ``Programming languages--C''.
126``POSIX'' refers to IEEE Standard 1003.1.  POSIX@registeredsymbol{} is a
127registered trademark of The IEEE.
128
129@c To sort the include list easily, keep the indentation right because want to
130@c skip the s_|w_ at the start of most--but not all--of the file names.
131@c (e.g., isgreater.def does not have a leading s nor w.)  Then, sort
132@c based on the column.  For example:  "sort -t@ -k3.17"
133@c A few hand-edits might be appropriate after a sort, although not necessary
134@c and are a nuisance as ought to be kept in sync with menu list above:
135@c atan2 after atan, exp2 after exp, log first in log list, and w_j0 to place
136@c to reflect function name of Bessel (as opposed to j; e.g. after atanh,
137@c before cbrt).
138
139@page
140@include   math/w_acos.def
141@page
142@include   math/w_acosh.def
143@page
144@include   math/w_asin.def
145@page
146@include   math/s_asinh.def
147@page
148@include   math/s_atan.def
149@page
150@include   math/w_atan2.def
151@page
152@include   math/w_atanh.def
153@page
154@include   math/w_j0.def
155@page
156@include common/s_cbrt.def
157@page
158@include common/s_copysign.def
159@page
160@include   math/w_cosh.def
161@page
162@include   math/s_erf.def
163@page
164@include   math/w_exp.def
165@page
166@include   common/s_exp10.def
167@page
168@include   math/w_exp2.def
169@page
170@include common/s_expm1.def
171@page
172@include   math/s_fabs.def
173@page
174@include common/s_fdim.def
175@page
176@include   math/s_floor.def
177@page
178@include common/s_fma.def
179@page
180@include common/s_fmax.def
181@page
182@include common/s_fmin.def
183@page
184@include   math/w_fmod.def
185@page
186@include   math/s_frexp.def
187@page
188@include   math/w_gamma.def
189@page
190@include   math/w_hypot.def
191@page
192@include common/s_ilogb.def
193@page
194@include common/s_infinity.def
195@page
196@include   common/isgreater.def
197@page
198@include common/s_isnan.def
199@page
200@include   math/s_ldexp.def
201@page
202@include   math/w_log.def
203@page
204@include   math/w_log10.def
205@page
206@include common/s_log1p.def
207@page
208@include common/s_log2.def
209@page
210@include common/s_logb.def
211@page
212@include common/s_lrint.def
213@page
214@include common/s_lround.def
215@page
216@include common/s_modf.def
217@page
218@include common/s_nan.def
219@page
220@include common/s_nearbyint.def
221@page
222@include common/s_nextafter.def
223@page
224@include   math/w_pow.def
225@page
226@include   common/s_pow10.def
227@page
228@include   math/w_remainder.def
229@page
230@include common/s_remquo.def
231@page
232@include common/s_rint.def
233@page
234@include common/s_round.def
235@page
236@include common/s_scalbn.def
237@page
238@include common/s_signbit.def
239@page
240@include   math/s_sin.def
241@page
242@include   math/w_sinh.def
243@page
244@include   math/w_sqrt.def
245@page
246@include   math/s_tan.def
247@page
248@include   math/s_tanh.def
249@page
250@include common/s_trunc.def
251