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