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}.
6Two definitions from @file{math.h} are 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.
12
13@item
14The structure @code{exception} is used when you write customized error
15handlers for the mathematical functions.  You can customize error
16handling for most of these functions by defining your own version of
17@code{matherr}; see the section on @code{matherr} for details.
18@end enumerate
19
20@cindex system calls
21@cindex support subroutines
22@cindex stubs
23@cindex OS stubs
24Since the error handling code calls @code{fputs}, the mathematical
25subroutines require stubs or minimal implementations for the same list
26of OS subroutines as @code{fputs}: @code{close}, @code{fstat},
27@code{isatty}, @code{lseek}, @code{read}, @code{sbrk}, @code{write}.
28@xref{syscalls,,System Calls, libc.info, The Cygnus C Support Library},
29for a discussion and for sample minimal implementations of these support
30subroutines.
31
32Alternative declarations of the mathematical functions, which exploit
33specific machine capabilities to operate faster---but generally have
34less error checking and may reflect additional limitations on some
35machines---are available when you include @file{fastmath.h} instead of
36@file{math.h}.
37
38@menu
39* version::	Version of library
40* acos::	Arccosine
41* acosh::	Inverse hyperbolic cosine
42* asin::	Arcsine
43* asinh::	Inverse hyperbolic sine
44* atan::	Arctangent
45* atan2::	Arctangent of y/x
46* atanh::	Inverse hyperbolic tangent
47* jN::	        Bessel functions  (jN, yN)
48* cbrt::	Cube root
49* copysign::	Sign of Y, magnitude of X
50* cosh::	Hyperbolic cosine
51* erf::		Error function  (erf, erfc)
52* exp::		Exponential
53* expm1::	Exponential of x, - 1
54* fabs::	Absolute value (magnitude)
55* floor::	Floor and ceiling  (floor, ceil)
56* fmod::	Floating-point remainder (modulo)
57* frexp::	Split floating-point number
58* gamma::	Logarithmic gamma function
59* hypot::	Distance from origin
60* ilogb::	Get exponent
61* infinity::	Floating infinity
62* isnan::	Check type of number
63* ldexp::	Load exponent
64* log::		Natural logarithms
65* log10::	Base 10 logarithms
66* log1p::	Log of 1 + X
67* matherr::	Modifiable math error handler
68* modf::	Split fractional and integer parts
69* nan::		Floating Not a Number
70* nextafter::	Get next representable number
71* pow::		X to the power Y
72* remainder::	remainder of X divided by Y
73* scalbn::	scalbn
74* sin::		Sine or cosine (sin, cos)
75* sinh::	Hyperbolic sine
76* sqrt::	Positive square root
77* tan::		Tangent
78* tanh::	Hyperbolic tangent
79@end menu
80
81@page
82@node version
83@section Version of library
84
85There are four different versions of the math library routines: IEEE,
86POSIX, X/Open, or SVID.  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_}, @code{_POSIX_}, @code{_XOPEN_}, or
90@code{_SVID_}.  The @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 how errors are handled.
94
95In IEEE mode, the @code{matherr} function is never called, no warning
96messages are printed, and @code{errno} is never set.
97
98In POSIX mode, @code{errno} is set correctly, but the @code{matherr}
99function is never called and no warning messages are printed.
100
101In X/Open mode, @code{errno} is set correctly, and @code{matherr} is
102called, but warning message are not printed.
103
104In SVID mode, functions which overflow return 3.40282346638528860e+38,
105the maximum single-precision floating-point value, rather than infinity.
106Also, @code{errno} is set correctly, @code{matherr} is called, and, if
107@code{matherr} returns 0, warning messages are printed for some errors.
108For example, by default @samp{log(-1.0)} writes this message on standard
109error output:
110
111@example
112log: DOMAIN error
113@end example
114
115The library is set to X/Open mode by default.
116
117@page
118@include math/wacos.def
119
120@page
121@include math/wacosh.def
122
123@page
124@include math/wasin.def
125
126@page
127@include math/sasinh.def
128
129@page
130@include math/satan.def
131
132@page
133@include math/watan2.def
134
135@page
136@include math/watanh.def
137
138@page
139@include math/wj0.def
140
141@page
142@include math/wcosh.def
143
144@page
145@include math/serf.def
146
147@page
148@include math/wexp.def
149
150@page
151@include math/sfabs.def
152
153@page
154@include math/sfloor.def
155
156@page
157@include math/wfmod.def
158
159@page
160@include math/sfrexp.def
161
162@page
163@include math/wgamma.def
164
165@page
166@include math/whypot.def
167
168@page
169@include math/sisnan.def
170
171@page
172@include math/sldexp.def
173
174@page
175@include math/wlog.def
176
177@page
178@include math/wlog10.def
179
180@page
181@include math/wpow.def
182
183@page
184@include math/wremainder.def
185
186@page
187@include math/wsqrt.def
188
189@page
190@include math/ssin.def
191
192@page
193@include math/wsinh.def
194
195@page
196@include math/stan.def
197
198@page
199@include math/stanh.def
200