From 7f3caba522f4d24764f29d83aa2de9198bb7f01c Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 24 May 2024 06:52:22 +0200 Subject: Adding upstream version 6.8. Signed-off-by: Daniel Baumann --- man7/math_error.7 | 246 ------------------------------------------------------ 1 file changed, 246 deletions(-) delete mode 100644 man7/math_error.7 (limited to 'man7/math_error.7') diff --git a/man7/math_error.7 b/man7/math_error.7 deleted file mode 100644 index 6fdff9a..0000000 --- a/man7/math_error.7 +++ /dev/null @@ -1,246 +0,0 @@ -.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk -.\" -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH math_error 7 2023-10-31 "Linux man-pages 6.7" -.SH NAME -math_error \- detecting errors from mathematical functions -.SH SYNOPSIS -.nf -.B #include -.B #include -.B #include -.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 -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). -.P -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 -.P -.in +4n -.EX -feclearexcept(FE_ALL_EXCEPT); -.EE -.in -.P -before calling a mathematical function. -.P -Upon return from the mathematical function, if -.I errno -is nonzero, or the following call (see -.BR fenv (3)) -returns nonzero -.P -.in +4n -.EX -fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | - FE_UNDERFLOW); -.EE -.in -.P -.\" 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. -.P -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. -.P -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. -.P -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. -.P -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. -.P -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): -.P -.in +4n -.EX -double x, r; -\& -if (isnan(x) || islessequal(x, 0)) { - /* Deal with NaN / pole error / domain error */ -} -\& -r = log(x); -.EE -.in -.P -The discussion on this page does not apply to the complex -mathematical functions (i.e., those declared by -.IR ), -which in general are not required to return errors by C99 -and POSIX.1. -.P -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) -.P -.I "info libc" -- cgit v1.2.3