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* acos::	Arccosine
32* acosh::	Inverse hyperbolic cosine
33* asin::	Arcsine
34* asinh::	Inverse hyperbolic sine
35* atan::	Arctangent
36* atan2::	Arctangent of y/x
37* atanh::	Inverse hyperbolic tangent
38* jN::	        Bessel functions (jN, yN)
39* cbrt::	Cube root
40* copysign::	Sign of Y, magnitude of X
41* cosh::	Hyperbolic cosine
42* erf::		Error function (erf, erfc)
43* exp::		Exponential, base e
44* exp10::	Exponential, base 10
45* exp2::	Exponential, base 2
46* expm1::	Exponential, base e, of x - 1
47* fabs::	Absolute value (magnitude)
48* fdim::	Positive difference
49* floor::	Floor and ceiling (floor, ceil)
50* fma::		Floating multiply add
51* fmax::	Maximum
52* fmin::	Minimum
53* fmod::	Floating-point remainder (modulo)
54* fpclassify::	Floating-point classification macro
55* frexp::	Split floating-point number
56* gamma::	Logarithmic gamma function
57* hypot::	Distance from origin
58* ilogb::	Get exponent
59* infinity::	Floating infinity
60* isgreater::	Comparison macros
61* ldexp::	Scale by a power of 2
62* log::		Natural logarithms
63* log10::	Base 10 logarithms
64* log1p::	Log of 1 + X
65* log2::	Base 2 logarithms
66* logb::	Get exponent
67* lrint::	Round to integer
68* lround::	Round to integer, away from zero (lround, llround)
69* modf::	Split fractional and integer parts
70* nan::		Floating Not a Number
71* nearbyint::	Round to integer
72* nextafter::	Get next representable number
73* pow::		X to the power Y
74* pow10::	10 to the power X
75* remainder::	remainder of X divided by Y
76* remquo::	Remainder and part of quotient
77* rint::	Round to integer
78* round::	Round to integer, away from zero
79* scalbn::	Scale by a power of FLT_RADIX (2)
80* signbit::	Does floating-point number have negative sign?
81* sin::		Sine or cosine (sin, cos)
82* sinh::	Hyperbolic sine
83* sqrt::	Positive square root
84* tan::		Tangent
85* tanh::	Hyperbolic tangent
86* 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