Document: WG14 N1319


Adding EPOLE to math library functions


Submitter: Fred Tydeman (USA)
Submission Date: 2008-07-13
Related WG14 documents: N748, Defect Report 331
Other documents: LIA-1 (ISO/IEC 10967-1:1994), LIA-2 (ISO/IEC 10967-2:2001), LIA-3 (ISO/IEC 10967-3:2006), POSIX, IEEE-754
Subject: Adding EPOLE to math library functions

Some error conditions for some of the math functions (for example log(0.0)) have been contraversial in the past in that some implementations claimed that they were domain errors, while others claimed that they were range errors. They truely are their own class of error and should be treated as such.

IEEE-754 has the divide-by-zero exception to cover these cases.

LIA-1 has undefined for both invalid (0.0/0.0) and divide-by-zero (1.0/0.0). But, it is planned to split this into invalid and infinitary (as per LIA-2 and LIA-3, when LIA-1 is revised in 2008).

LIA-2, came after LIA-1, split undefined into invalid (0.0/0.0, log(negative)) and infinitary (1.0/0.0, log(0.0)).

LIA-3, came after LIA-2, has invalid and infinitary.

POSIX (IEEE P1003.1 draft 5, 2008) has Domain error, Pole error, and Range error. So, they have already split this class of error out of domain and/or range error. So, for example, atanh() has pole error, domain error, and range error.

An alternate spelling is ESING (for singularity).

Existing implementations: matherr(). Some systems that support AT&T SVID "trap" handlers for math function errors support domain, range (overflow and underflow), singularity, and (total and partial) loss of accuracy errors.

Changes to C1x

Add to 7.5 Errors <errno.h>, paragraph 2: EPOLE

Add to 7.12.1 Treatment of error conditions, a paragraph between 2 and 3.

Similarly, a pole error (also known as singularity or infinitary) occurs if the mathematical function has an exact infinite result as the finite input argument(s) are approached in the limit (for example log(0.0)). The description of each function lists any required pole errors; an implementation may define additional pole errors, provided that such errors are consistent with the mathematical definition of the function. On a pole error, the function returns an implementation-defined value; if the integer expression math_errhandling & MATH_ERRNO is nonzero, the integer expression errno acquires the value EPOLE; if the integer expression math_errhandling & MATH_ERREXCEPT is nonzero, the "divide-by-zero" floating-point exception is raised.

Remove 'or if the matematical result is an exact infinity from finite arguments (for example log(0.0)),' from paragraph 4.

Remove 'the "divide-by-zero" floating-point exception is raised if the mathematical result is an exact infinity and' from paragraph 4, and also 'otherwise' at the end of the same sentance.

Change 'range error' to 'pole error' in the following sections:

7.12.5.3 atanh

7.12.6.5 ilogb -- needs total rework: 0 => pole; inf => range; NaN => domain

7.12.6.7 log -- remove 'may occur'

7.12.6.8 log10 -- remove 'may occur'

7.12.6.8 log10 -- remove 'may occur'

7.12.6.9 log1p -- remove 'may occur'

7.12.6.10 log2 -- remove 'may occur'

7.12.6.11 logb -- also remove 'domain error or'

7.12.7.4 pow -- change 'domain error or range error' to 'pole error'; leave other range errors alone. [make sure matches F.9.4.4]

7.12.8.3 lgamma -- change 'domain error or range error' to 'pole error'; leave other range errors alone.

7.12.8.4 tgamma -- change 'domain error or range error' to 'pole error'; leave other range errors alone.

J.3.12 Library functions

Add bullet: The values returned by the mathematics functions on pole errors (7.12.1).

Add EPOLE macro to index.

Add error, pole to index.

Add pole error to index.