diff options
Diffstat (limited to 'man7/math_error.7')
| -rw-r--r-- | man7/math_error.7 | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/man7/math_error.7 b/man7/math_error.7 new file mode 100644 index 0000000..d3b3c1a --- /dev/null +++ b/man7/math_error.7 @@ -0,0 +1,246 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH math_error 7 2023-05-03 "Linux man-pages 6.05.01" +.SH NAME +math_error \- detecting errors from mathematical functions +.SH SYNOPSIS +.nf +.B #include <math.h> +.B #include <errno.h> +.B #include <fenv.h> +.fi +.SH DESCRIPTION +When an error occurs, +most library functions indicate this fact by returning a special value +(e.g., \-1 or NULL). +Because they typically return a floating-point number, +the mathematical functions declared in +.I <math.h> +indicate an error using other mechanisms. +There are two error-reporting mechanisms: +the older one sets +.IR errno ; +the newer one uses the floating-point exception mechanism (the use of +.BR feclearexcept (3) +and +.BR fetestexcept (3), +as outlined below) +described in +.BR fenv (3). +.PP +A portable program that needs to check for an error from a mathematical +function should set +.I errno +to zero, and make the following call +.PP +.in +4n +.EX +feclearexcept(FE_ALL_EXCEPT); +.EE +.in +.PP +before calling a mathematical function. +.PP +Upon return from the mathematical function, if +.I errno +is nonzero, or the following call (see +.BR fenv (3)) +returns nonzero +.PP +.in +4n +.EX +fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | + FE_UNDERFLOW); +.EE +.in +.PP +.\" enum +.\" { +.\" FE_INVALID = 0x01, +.\" __FE_DENORM = 0x02, +.\" FE_DIVBYZERO = 0x04, +.\" FE_OVERFLOW = 0x08, +.\" FE_UNDERFLOW = 0x10, +.\" FE_INEXACT = 0x20 +.\" }; +then an error occurred in the mathematical function. +.PP +The error conditions that can occur for mathematical functions +are described below. +.SS Domain error +A +.I domain error +occurs when a mathematical function is supplied with an argument whose +value falls outside the domain for which the function +is defined (e.g., giving a negative argument to +.BR log (3)). +When a domain error occurs, +math functions commonly return a NaN +(though some functions return a different value in this case); +.I errno +is set to +.BR EDOM , +and an "invalid" +.RB ( FE_INVALID ) +floating-point exception is raised. +.SS Pole error +A +.I pole error +occurs when the mathematical result of a function is an exact infinity +(e.g., the logarithm of 0 is negative infinity). +When a pole error occurs, +the function returns the (signed) value +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +depending on whether the function result type is +.IR double , +.IR float , +or +.IR "long double" . +The sign of the result is that which is mathematically correct for +the function. +.I errno +is set to +.BR ERANGE , +and a "divide-by-zero" +.RB ( FE_DIVBYZERO ) +floating-point exception is raised. +.SS Range error +A +.I range error +occurs when the magnitude of the function result means that it +cannot be represented in the result type of the function. +The return value of the function depends on whether the range error +was an overflow or an underflow. +.PP +A floating result +.I overflows +if the result is finite, +but is too large to represented in the result type. +When an overflow occurs, +the function returns the value +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +depending on whether the function result type is +.IR double , +.IR float , +or +.IR "long double" . +.I errno +is set to +.BR ERANGE , +and an "overflow" +.RB ( FE_OVERFLOW ) +floating-point exception is raised. +.PP +A floating result +.I underflows +if the result is too small to be represented in the result type. +If an underflow occurs, +a mathematical function typically returns 0.0 +(C99 says a function shall return "an implementation-defined value +whose magnitude is no greater than the smallest normalized +positive number in the specified type"). +.I errno +may be set to +.BR ERANGE , +and an "underflow" +.RB ( FE_UNDERFLOW ) +floating-point exception may be raised. +.PP +Some functions deliver a range error if the supplied argument value, +or the correct function result, would be +.IR subnormal . +A subnormal value is one that is nonzero, +but with a magnitude that is so small that +it can't be presented in normalized form +(i.e., with a 1 in the most significant bit of the significand). +The representation of a subnormal number will contain one +or more leading zeros in the significand. +.SH NOTES +The +.I math_errhandling +identifier specified by C99 and POSIX.1 is not supported by glibc. +.\" See CONFORMANCE in the glibc 2.8 (and earlier) source. +This identifier is supposed to indicate which of the two +error-notification mechanisms +.RI ( errno , +exceptions retrievable via +.BR fetestexcept (3)) +is in use. +The standards require that at least one be in use, +but permit both to be available. +The current (glibc 2.8) situation under glibc is messy. +Most (but not all) functions raise exceptions on errors. +Some also set +.IR errno . +A few functions set +.IR errno , +but don't raise an exception. +A very few functions do neither. +See the individual manual pages for details. +.PP +To avoid the complexities of using +.I errno +and +.BR fetestexcept (3) +for error checking, +it is often advised that one should instead check for bad argument +values before each call. +.\" http://www.securecoding.cert.org/confluence/display/seccode/FLP32-C.+Prevent+or+detect+domain+and+range+errors+in+math+functions +For example, the following code ensures that +.BR log (3)'s +argument is not a NaN and is not zero (a pole error) or +less than zero (a domain error): +.PP +.in +4n +.EX +double x, r; +\& +if (isnan(x) || islessequal(x, 0)) { + /* Deal with NaN / pole error / domain error */ +} +\& +r = log(x); +.EE +.in +.PP +The discussion on this page does not apply to the complex +mathematical functions (i.e., those declared by +.IR <complex.h> ), +which in general are not required to return errors by C99 +and POSIX.1. +.PP +The +.BR gcc (1) +.I "\-fno\-math\-errno" +option causes the executable to employ implementations of some +mathematical functions that are faster than the standard +implementations, but do not set +.I errno +on error. +(The +.BR gcc (1) +.I "\-ffast\-math" +option also enables +.IR "\-fno\-math\-errno" .) +An error can still be tested for using +.BR fetestexcept (3). +.SH SEE ALSO +.BR gcc (1), +.BR errno (3), +.BR fenv (3), +.BR fpclassify (3), +.BR INFINITY (3), +.BR isgreater (3), +.BR matherr (3), +.BR nan (3) +.PP +.I "info libc" |