]>
Commit | Line | Data |
---|---|---|
88fb3501 MK |
1 | .\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
88fb3501 MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
88fb3501 | 25 | .\" |
00df6756 | 26 | .TH MATH_ERROR 7 2008-08-11 "Linux" "Linux Programmer's Manual" |
547768b4 MK |
27 | .SH NAME |
28 | math_error \- detecting errors from mathematical functions | |
88fb3501 MK |
29 | .SH SYNOPSIS |
30 | .nf | |
31 | .B #include <math.h> | |
32 | .B #include <errno.h> | |
33 | .B #include <fenv.h> | |
34 | .fi | |
88fb3501 | 35 | .SH DESCRIPTION |
00df6756 MK |
36 | When an error occurs, |
37 | most library functions indicate this fact by returning a special value | |
38 | (e.g., \-1 or NULL). | |
39 | Because they typically return a floating-point number, | |
40 | the mathematical functions declared in | |
88fb3501 | 41 | .IR <math.h> |
00df6756 MK |
42 | indicate an error using other mechanisms. |
43 | There are two error-reporting mechanisms: | |
88fb3501 MK |
44 | the older one sets |
45 | .IR errno ; | |
46 | the newer one uses the floating-point exception mechanism (the use of | |
47 | .BR feclearexcept (3) | |
48 | and | |
49 | .BR fetestexcept (3), | |
50 | as outlined below) | |
51 | described in | |
52 | .BR fenv (3). | |
53 | ||
88fb3501 MK |
54 | A portable program that needs to check for an error from a mathematical |
55 | function should set | |
56 | .I errno | |
57 | to zero, and make the following call | |
58 | .in +4n | |
59 | .nf | |
60 | ||
61 | feclearexcept(FE_ALL_EXCEPT); | |
62 | ||
63 | .fi | |
64 | .in | |
65 | before calling a mathematical function. | |
66 | ||
67 | Upon return from the mathematical function, if | |
68 | .I errno | |
c7094399 | 69 | is nonzero, or the following call (see |
88fb3501 | 70 | .BR fenv (3)) |
c7094399 | 71 | returns nonzero |
88fb3501 MK |
72 | .in +4n |
73 | .nf | |
74 | ||
75 | fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | | |
76 | FE_UNDERFLOW); | |
77 | ||
78 | .fi | |
79 | .in | |
80 | .\" enum | |
81 | .\" { | |
82 | .\" FE_INVALID = 0x01, | |
83 | .\" __FE_DENORM = 0x02, | |
84 | .\" FE_DIVBYZERO = 0x04, | |
85 | .\" FE_OVERFLOW = 0x08, | |
86 | .\" FE_UNDERFLOW = 0x10, | |
87 | .\" FE_INEXACT = 0x20 | |
88 | .\" }; | |
89 | then an error occurred in the mathematical function. | |
90 | ||
91 | The error conditions that can occur for mathematical functions | |
92 | are described below. | |
c634028a | 93 | .SS Domain error |
88fb3501 MK |
94 | A |
95 | .I domain error | |
96 | occurs when a mathematical function is supplied with an argument whose | |
97 | value falls outside the domain for which the function | |
98 | is defined (e.g., giving a negative argument to | |
99 | .BR log (3)). | |
100 | When a domain error occurs, | |
00df6756 MK |
101 | math functions commonly return a NaN |
102 | (though some functions return a different value in this case); | |
88fb3501 MK |
103 | .I errno |
104 | is set to | |
105 | .BR EDOM , | |
106 | and an "invalid" | |
107 | .RB ( FE_INVALID ) | |
108 | floating-point exception is raised. | |
c634028a | 109 | .SS Pole error |
88fb3501 MK |
110 | A |
111 | .I pole error | |
112 | occurs when the mathematical result of a function is an exact infinity | |
113 | (e.g., the logarithm of 0 is negative infinity). | |
114 | When a pole error occurs, | |
115 | the function returns the (signed) value | |
116 | .BR HUGE_VAL , | |
117 | .BR HUGE_VALF , | |
118 | or | |
119 | .BR HUGE_VALL , | |
120 | depending on whether the function result type is | |
121 | .IR double , | |
122 | .IR float , | |
123 | or | |
124 | .IR "long double" . | |
125 | The sign of the result is that which is mathematically correct for | |
126 | the function. | |
127 | .I errno | |
128 | is set to | |
129 | .BR ERANGE , | |
130 | and a "divide-by-zero" | |
131 | .RB ( FE_DIVBYZERO ) | |
132 | floating-point exception is raised. | |
c634028a | 133 | .SS Range error |
88fb3501 MK |
134 | A |
135 | .I range error | |
136 | occurs when the magnitude of the function result means that it | |
137 | cannot be represented in the result type of the function. | |
138 | The return value of the function depends on whether the range error | |
139 | was an overflow or an underflow. | |
140 | ||
141 | A floating result | |
142 | .I overflows | |
4e836144 | 143 | if the result is finite, |
88fb3501 MK |
144 | but is too large to represented in the result type. |
145 | When an overflow occurs, | |
146 | the function returns the value | |
147 | .BR HUGE_VAL , | |
148 | .BR HUGE_VALF , | |
149 | or | |
150 | .BR HUGE_VALL , | |
151 | depending on whether the function result type is | |
152 | .IR double , | |
153 | .IR float , | |
154 | or | |
155 | .IR "long double" . | |
156 | .I errno | |
157 | is set to | |
158 | .BR ERANGE , | |
159 | and an "overflow" | |
160 | .RB ( FE_OVERFLOW ) | |
161 | floating-point exception is raised. | |
162 | ||
163 | A floating result | |
164 | .I underflows | |
165 | if the result is too small to be represented in the result type. | |
166 | If an underflow occurs, | |
167 | a mathematical function typically returns 0.0 | |
168 | (C99 says a function shall return "an implementation-defined value | |
169 | whose magnitude is no greater than the smallest normalized | |
170 | positive number in the specified type"). | |
88fb3501 MK |
171 | .I errno |
172 | may be set to | |
173 | .BR ERANGE , | |
174 | and an "overflow" | |
175 | .RB ( FE_UNDERFLOW ) | |
176 | floating-point exception may be raised. | |
177 | ||
178 | Some functions deliver a range error if the supplied argument value, | |
179 | or the correct function result, would be | |
180 | .IR subnormal . | |
c7094399 | 181 | A subnormal value is one that is nonzero, |
88fb3501 MK |
182 | but with a magnitude that is so small that |
183 | it can't be presented in normalized form | |
184 | (i.e., with a 1 in the most significant bit of the significand). | |
185 | The representation of a subnormal number will contain one | |
186 | or more leading zeros in the significand. | |
187 | .SH NOTES | |
188 | The | |
189 | .I math_errhandling | |
77d824ca | 190 | identifier specified by C99 and POSIX.1 is not supported by glibc. |
88fb3501 | 191 | .\" See CONFORMANCE in the glibc 2.8 (and earlier) source. |
82245f7a | 192 | This identifier is supposed to indicate which of the two |
bb5baf62 MK |
193 | error-notification mechanisms |
194 | .RI ( errno , | |
195 | exceptions retrievable via | |
196 | .BR fettestexcept (3)) | |
197 | is in use. | |
198 | The standards require that at least one be in use, | |
199 | but permit both to be available. | |
200 | The current (version 2.8) situation under glibc is messy. | |
201 | Most (but not all) functions raise exceptions on errors. | |
202 | Some also set | |
203 | .IR errno . | |
204 | A few functions set | |
205 | .IR errno , | |
206 | but don't raise an exception. | |
207 | A very few functions do neither. | |
208 | See the individual manual pages for details. | |
88fb3501 MK |
209 | |
210 | To avoid the complexities of using | |
211 | .I errno | |
212 | and | |
213 | .BR fetestexcept (3) | |
214 | for error checking, | |
215 | it is often advised that one should instead check for bad argument | |
216 | values before each call. | |
217 | .\" http://www.securecoding.cert.org/confluence/display/seccode/FLP32-C.+Prevent+or+detect+domain+and+range+errors+in+math+functions | |
218 | For example, the following code ensures that | |
219 | .BR log (3)'s | |
220 | argument is not a NaN and is not zero (a pole error) or | |
221 | less than zero (a domain error): | |
222 | .in +4n | |
223 | .nf | |
224 | ||
225 | double x, r; | |
226 | ||
227 | if (isnan(x) || islessequal(x, 0)) { | |
228 | /* Deal with NaN / pole error / domain error */ | |
229 | } | |
230 | ||
231 | r = log(x); | |
232 | ||
233 | .fi | |
234 | .in | |
235 | The discussion on this page does not apply to the complex | |
236 | mathematical functions (i.e., those declared by | |
237 | .IR <complex.h> ), | |
238 | which in general are not required to return errors by C99 | |
77d824ca | 239 | and POSIX.1. |
88fb3501 MK |
240 | |
241 | The | |
242 | .BR gcc (1) | |
243 | .I "-fno-math-errno" | |
244 | option causes the executable to employ implementations of some | |
245 | mathematical functions that are faster than the standard | |
246 | implementations, but do not set | |
247 | .I errno | |
248 | on error. | |
249 | (The | |
250 | .BR gcc (1) | |
251 | .I "-ffast-math" | |
252 | option also enables | |
253 | .IR "-fno-math-errno" .) | |
254 | An error can still be tested for using | |
255 | .BR fetestexcept (3). | |
88fb3501 MK |
256 | .SH SEE ALSO |
257 | .BR gcc (1), | |
258 | .BR errno (3), | |
259 | .BR fenv (3), | |
260 | .BR fpclassify (3), | |
261 | .BR INFINITY (3), | |
262 | .BR isgreater (3), | |
263 | .BR matherr (3), | |
264 | .BR nan (3) | |
173fe7e7 | 265 | |
88fb3501 | 266 | .I "info libc" |