This is the mail archive of the
`libc-alpha@sourceware.org`
mailing list for the glibc project.

Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
---|---|---|

Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |

Other format: | [Raw text] |

*From*: "Joseph S. Myers" <joseph at codesourcery dot com>*To*: <libc-alpha at sourceware dot org>*Cc*: <mtk dot manpages at gmail dot com>*Date*: Thu, 28 Nov 2013 01:43:48 +0000*Subject*: Document some libm error handling intents*Authentication-results*: sourceware.org; auth=none

This patch documents certain intents regarding libm error handling that have previously been mentioned on this list without getting any objections as far as I can tell: * When matherr is used, exceptions may not be raised (because the matherr mechanism predates exceptions). See <https://sourceware.org/ml/libc-alpha/2013-04/msg00767.html>. This makes bugs 6805 and 6806 INVALID. (Actually, I expect exceptions would in fact get raised in all except those particular Bessel function TLOSS cases.) Note that this patch doesn't document the need to set _LIB_VERSION to use matherr - it leaves that undocumented. And of course it doesn't rule out deprecating the whole matherr / _LIB_VERSION mechanism so new binaries can't use it (subject to finding a new solution for -lieee, probably no-errno versions of functions used when compiling with -fno-math-errno). * The intent for setting errno on overflow and underflow is only for overflow to infinity and underflow to zero, not for other overflow cases (in non-default rounding modes) and underflow to subnormals (or, in corner cases, to the least normal). See <https://sourceware.org/ml/libc-alpha/2013-11/msg00626.html>. This makes bugs 6785 and 6795 INVALID, as erf and hypot can never underflow to zero. 2013-11-28 Joseph Myers <joseph@codesourcery.com> * manual/arith.texi (FP Exceptions): Document that exceptions may not be raised when matherr is used. (Math Error Reporting): Document overflow in directed rounding modes. Document that errno may not be set when finite values are returned on overflow. Document intent to set errno on underflow only for underflow to zero. diff --git a/manual/arith.texi b/manual/arith.texi index 85aa197..9cd6127 100644 --- a/manual/arith.texi +++ b/manual/arith.texi @@ -497,7 +497,8 @@ In the System V math library, the user-defined function @code{matherr} is called when certain exceptions occur inside math library functions. However, the Unix98 standard deprecates this interface. We support it for historical compatibility, but recommend that you do not use it in -new programs. +new programs. When this interface is used, exceptions may not be +raised. @noindent The exceptions defined in @w{IEEE 754} are: @@ -806,7 +807,8 @@ an integer. Do not attempt to modify an @code{fexcept_t} variable. Many of the math functions are defined only over a subset of the real or complex numbers. Even if they are mathematically defined, their result may be larger or smaller than the range representable by their return -type. These are known as @dfn{domain errors}, @dfn{overflows}, and +type without loss of accuracy. These are known as @dfn{domain errors}, +@dfn{overflows}, and @dfn{underflows}, respectively. Math functions do several things when one of these errors occurs. In this manual we will refer to the complete response as @dfn{signalling} a domain error, overflow, or @@ -816,11 +818,20 @@ When a math function suffers a domain error, it raises the invalid exception and returns NaN. It also sets @var{errno} to @code{EDOM}; this is for compatibility with old systems that do not support @w{IEEE 754} exception handling. Likewise, when overflow occurs, math -functions raise the overflow exception and return @math{@infinity{}} or -@math{-@infinity{}} as appropriate. They also set @var{errno} to -@code{ERANGE}. When underflow occurs, the underflow exception is -raised, and zero (appropriately signed) is returned. @var{errno} may be -set to @code{ERANGE}, but this is not guaranteed. +functions raise the overflow exception and, in the default rounding +mode, return @math{@infinity{}} or @math{-@infinity{}} as appropriate +(in other rounding modes, the largest finite value of the appropriate +sign is returned when appropriate for that rounding mode). They also +set @var{errno} to @code{ERANGE} if returning @math{@infinity{}} or +@math{-@infinity{}}; @var{errno} may or may not be set to +@code{ERANGE} when a finite value is returned on overflow. When +underflow occurs, the underflow exception is raised, and zero +(appropriately signed) or a subnormal value, as appropriate for the +mathematical result of the function and the rounding mode, is +returned. @var{errno} may be set to @code{ERANGE}, but this is not +guaranteed; it is intended that @theglibc{} should set it when the +underflow is to an appropriately signed zero, but not necessarily for +other underflows. Some of the math functions are defined mathematically to result in a complex value over parts of their domains. The most familiar example of -- Joseph S. Myers joseph@codesourcery.com

**Follow-Ups**:**Re: Document some libm error handling intents***From:*Andreas Jaeger

Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
---|---|---|

Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |