Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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"