Section The C Standard, 7.12.1 of the C Standard [ISO/IEC 9899:20112024], defines two three types of errors that relate specifically to math functions in math.h
: <math.h>
. Paragraph 2 states
A A domain error occurs if an input argument is outside the domain over which the mathematical function is defined.A range error
Paragraph 3 states
A pole error (also known as a singularity or infinitary) occurs if the mathematical function has an exact infinite result as the finite input argument(s) are approached in the limit.
Paragraph 4 states
arange error occurs if and only if the result overflows or underflows result of the function cannot be represented in an object of the specified type, due to extreme magnitude.
An example of a domain error is the square root of a negative number, such as sqrt(-1.0)
, which has no meaning in real arithmetic.
...
Contrastingly, 10 raised to the 1-millionth power, pow(10., 1e6)
,
...
cannot be represented in
...
many floating-point
...
implementations because of the limited range of the type double
and consequently constitutes a range error.
...
In both cases, the function will return some value, but the value returned is not the correct result of the computation. An example of a pole error is log(0.0)
, which results in negative infinity.
Programmers can prevent domain and pole errors Domain errors can be prevented by carefully bounds-checking the arguments before calling mathematical functions and taking alternative action if the bounds are violated.
...
The following table lists the double
forms of standard mathematical functions, along with any checks that should be performed on their performed to ensure a proper input domain, and indicates if whether they can also throw result in range or pole errors, as reported by the C Standard. If a function has a specific domain over Both float
and long double
forms of these functions also exist but are omitted from the table for brevity. If a function has a specific domain over which it is defined, the programmer should must check its input values, and if a function throws range errors, the programmer should detect if a range error occurs. The programmer must also check for range errors where they might occur. The standard math functions not listed in this table, such as atanfabs()
, have no domain restrictions and do not throw range cannot result in range or pole errors.
Function | Domain | Range | Pole |
---|---|---|---|
|
| No | No | |
asin(x) | -1 <= x && x <= 1 |
Yes | No | ||
atan(x) | None | Yes | No |
|
x != 0 || y != 0
| No | No |
|
|
Yes | No | ||
asinh(x) | None | Yes | No |
|
|
Yes | Yes |
| None |
Yes |
No | |
| None |
Yes |
No | |
| None |
Yes |
No | ||
|
| No |
Yes | ||
|
| No |
Yes |
|
| Yes | No | |
logb(x) | x != 0 | Yes |
Yes |
|
None |
Yes | No |
| None |
Yes |
No | ||
|
| Yes |
Yes | |
|
|
No | No | ||
erf(x) | None | Yes | No |
| None |
Yes |
No | |
|
|
| Yes |
Yes | |
| None |
Yes |
No |
|
y != 0
no
|
|
none
|
| Yes | No |
| None | Yes | No |
| None |
Yes |
No | |
| None |
Yes |
No |
Domain and Pole Checking
The most reliable way to handle domain and pole errors is to prevent them by checking arguments beforehand, as in the following templateexemplar:
Code Block |
---|
ifdouble safe_sqrt(/*double argumentsx) will{ cause aif domain(x error< */0) { fprintf(stderr, "sqrt requires a nonnegative argument"); /* handleHandle domain / pole error */ } else { return /* perform computation */sqrt (x); } |
Range Checking
Range errors cannot usually be preventedProgrammers usually cannot prevent range errors, so the most reliable way to handle range errors them is to detect when they have occurred and act accordingly.
The exact treatment of error conditions from math functions is quite complicated. Section tedious. The C Standard, 7.12.1 of the C Standard paragraph 5 [ISO/IEC 9899:20112024], defines the following behavior for floating-point overflow:
A floating result overflows if the magnitude of the mathematical result is finite but so large that the mathematical result cannot be represented without extraordinary roundoff error in an object of the specified typea finite result value with ordinary accuracy would have magnitude (absolute value) too large for the representation with full precision in the specified type. A result that is exactly an infinity does not overflow. If a floating result overflows and default rounding is in effect, then the function returns the value of the macro HUGE_VAL, HUGE_VALF, or HUGE_VALL according to the return type, with the same sign as the correct value of the function; if the integer expression however, for the types with reduced-precision representations of numbers beyond the overflow threshold, the function may return a representation of the result with less than full precision for the type. If a floating resultoverflowsanddefaultroundingisineffectandtheintegerexpressionmath_errhandling & MATH_ERRNO is nonzero, then the integer expression errno acquires the value ERANGE; if . If a floating result overflows, and the integer expression math_errhandling & MATH_ERREXCEPT is nonzero, the ‘‘overflow’’ the "overflow" floating-point exception is raised (regardless of whether default rounding is in effect).
It is best preferable not to check for errors by comparing the returned value against HUGE_VAL
or 0
for several reasons:
- These are, in general, valid (albeit unlikely) data values.
- Making such tests requires detailed knowledge of the various error returns for each math function.
- There are three different possibilities, -Multiple results aside from
HUGE_VAL
, and0
are possible, andHUGE_VAL
, and you programmers must know which are possible in each case. - Different versions of the library have differed varied in their error-return behavior.
It is also difficult can be unreliable to check for math errors using errno
because an implementation might not set it errno
. For real functions, the programmer can tell whether determines if the implementation sets errno
by checking whether math_errhandling & MATH_ERRNO
is nonzero. For complex functions, the
The C Standard, Section 7.3.2, simply states that "an , paragraph 1 [ISO/IEC 9899:2024], states:
an implementation may set
errno
but is not required to
...
.
The obsolete System V Interface Definition, Third Edition (SVID3) , [UNIX 1992] provides more control over the treatment of errors in the math library. The user programmer can provide define a function named matherr()
that is invoked if errors occur in a math function. This function can print diagnostics, terminate the execution, or specify the desired return value. The matherr()
function has not been adopted by C or POSIX, so its use it is not generally portable.
The following error-handing template uses C Standard functions for floating-point errors when the C macro math_errhandling
is defined and indicates that they should be used; otherwise, it examines errno
.:
Code Block |
---|
#include <math.h> #if defined(math_errhandling) \ && (math_errhandling & MATH_ERREXCEPT)#include <fenv.h> #include <fenv<errno.h> #endif /* ... */ #if defined(math_errhandling) \ && (math_errhandling & MATH_ERREXCEPT) /* Use to call a math function and check errors */ { #pragma STDC FENV_ACCESS ON if (math_errhandling & MATH_ERREXCEPT) { feclearexcept(FE_ALL_EXCEPT); #endif } errno = 0; /* callCall the math function */ #if !defined if ((math_errhandling) \ || (math_errhandling & MATH_ERRNO) if && (errno != 0) { /* handleHandle range error */ } #endif #if defined(math_errhandling) \ && } else if ((math_errhandling & MATH_ERREXCEPT) if (fetestexcept(FE_INVALID && fetestexcept(FE_INVALID | FE_DIVBYZERO | | FE_OVERFLOW FE_OVERFLOW | FE_UNDERFLOW) != 0) { /* handleHandle range error */ } #endif} |
See FLP03-C. Detect and handle floating-point errors for more details on how to detect floating-point errors. Anchor
sqrt(x)
Noncompliant Code Example
The following noncompliant code determines the square root of x
.
Code Block | ||||
---|---|---|---|---|
| ||||
double x;
double result;
result = sqrt(x);
|
However, this code may produce a domain error if x
is negative.
Compliant Solution
Since this function has domain errors but no range errors, bounds checking can be used to prevent domain errors.
Code Block | ||||
---|---|---|---|---|
| ||||
double x;
double result;
if (isless(x, 0)) {
/* handle domain error */
}
result = sqrt(x);
|
...
Subnormal Numbers
A subnormal number is a nonzero number that does not use all of its precision bits [IEEE 754 2006]. These numbers can be used to represent values that are closer to 0 than the smallest normal number (one that uses all of its precision bits). However, the asin()
, asinh()
, atan()
, atanh()
, and erf()
functions may produce range errors, specifically when passed a subnormal number. When evaluated with a subnormal number, these functions can produce an inexact, subnormal value, which is an underflow error.
The C Standard, 7.12.1, paragraph 6 [ISO/IEC 9899:2024], defines the following behavior for floating-point underflow:
The result underflows if a nonzero result value with ordinary accuracy would have magnitude (absolute value) less than the minimum normalized number in the type; however a zero result that is specified to be an exact zero does not underflow. Also, a result with ordinary accuracy and the magnitude of the minimum normalized number may underflow.269) If the result underflows, the function returns an implementation-defined value whose magnitude is no greater than the smallest normalized positive number in the specified type; if the integer expression math_errhandling & MATH_ERRNO is nonzero, whether errno acquires the value ERANGE is implementation-defined; if the integer expression math_errhandling & MATH_ERREXCEPT s nonzero, whether the"underflow" floating-point exception is raised is implementation-defined.
Implementations that support floating-point arithmetic but do not support subnormal numbers, such as IBM S/360 hex floating-point or nonconforming IEEE-754 implementations that skip subnormals (or support them by flushing them to zero), can return a range error when calling one of the following families of functions with the following arguments:
fmod
((min+subnorm), min)
remainder
((min+
), min)subnorm
remquo
((min+
), min, quo)subnorm
where min
is the minimum value for the corresponding floating point type and subnorm
is a subnormal value.
If Annex F is supported and subnormal results are supported, the returned value is exact and a range error cannot occur. The C Standard, F.10.7.1 paragraph 2 [ISO/IEC 9899:2024], specifies the following for the fmod()
, remainder()
, and remquo()
functions:
When subnormal results are supported, the returned value is exact and is independent of the current rounding direction mode.
Annex F, subclause F.10.7.2, paragraph 2, and subclause F.10.7.3, paragraph 2, of the C Standard identify when subnormal results are supported.
Noncompliant Code Example (sqrt()
)
This noncompliant code example determines the square root of x
:
Code Block | ||||
---|---|---|---|---|
| ||||
#include <math.h>
void func(double x) {
double result;
result = sqrt(x);
} |
However, this code may produce a domain error if x
is negative.
Compliant Solution (sqrt()
)
Because this function has domain errors but no range errors, bounds checking can be used to prevent domain errors:
Code Block | ||||
---|---|---|---|---|
| ||||
#include <math.h>
void func(double x) {
double result;
if (isless(x, 0.0)) {
/* Handle domain error */
}
result = sqrt(x);
} |
Noncompliant Code Example (sinh()
, Range Errors)
This noncompliant code example determines the hyperbolic sine of x
:
Code Block | ||||
---|---|---|---|---|
| ||||
#include <math.h>
void func(double x) {
double result;
result = sinh(x);
} |
This code may produce a range error if x
has a very large magnitude.
Compliant Solution (sinh()
, Range Errors)
Because this function has no domain errors but may have range errors, the programmer must detect a range error and act accordingly:
Code Block | ||||
---|---|---|---|---|
| ||||
#include <math.h>
#include <fenv.h>
#include <errno.h>
void func(double x) {
double result;
{
#pragma STDC FENV_ACCESS ON
if (math_errhandling & MATH_ERREXCEPT) {
feclearexcept(FE_ALL_EXCEPT);
}
errno = 0;
result = sinh(x);
if ((math_errhandling & MATH_ERRNO) && errno != 0) {
/* Handle range error */
} else if ((math_errhandling & MATH_ERREXCEPT) &&
fetestexcept(FE_INVALID | FE_DIVBYZERO |
FE_OVERFLOW | FE_UNDERFLOW) != 0) {
/* Handle range error */
}
}
/* Use result... */
} |
Noncompliant Code Example (pow()
)
This noncompliant code example raises x
to the power of y
:
Code Block | ||||
---|---|---|---|---|
| ||||
#include <math.h>
void func(double x, double y) {
double result;
result = pow(x, y);
} |
This code may produce a domain error if x
is negative and y
is not an integer value or if x
is 0 and y
is 0. A domain error or pole error may occur if x
is 0 and y
is negative, and a range error may occur if the result cannot be represented as a double
.
Compliant Solution (pow()
)
Because the pow()
function can produce domain errors, pole errors, and range errors, the programmer must first check that x
and y
lie within the proper domain and do not generate a pole error and then detect whether a range error occurs and act accordingly:
Code Block | ||||
---|---|---|---|---|
| ||||
#include <math.h>
#include <fenv.h>
#include <errno.h>
void func(double x, double y) {
double result;
if (((x == 0.0f) && islessequal(y, 0.0)) || isless(x, 0.0)) {
/* Handle domain or pole error */
}
{
#pragma STDC FENV_ACCESS ON
if (math_errhandling & MATH_ERREXCEPT) {
feclearexcept(FE_ALL_EXCEPT);
}
errno = 0;
result = pow(x, y);
if ((math_errhandling & MATH_ERRNO) && errno != 0) {
/* Handle range error */
} else if ((math_errhandling & MATH_ERREXCEPT) &&
fetestexcept(FE_INVALID | FE_DIVBYZERO |
FE_OVERFLOW | FE_UNDERFLOW) != 0) {
/* Handle range error */
}
}
/* Use result... */
} |
Noncompliant Code Example (asin()
, Subnormal Number)
This noncompliant code example determines the inverse sine of x
:
Code Block | ||||
---|---|---|---|---|
| ||||
#include <math.h>
void func(float x) {
float result = asin(x);
/* ... */
} |
Compliant Solution (asin()
, Subnormal Number)
Because this function has no domain errors but may have range errors, the programmer must detect a range error and act accordingly:
Code Block | ||||
---|---|---|---|---|
| ||||
#include <math.h>
#include <fenv.h>
#include <errno.h>
void func(float x) {
float result;
{
#pragma STDC FENV_ACCESS ON
if (math_errhandling & MATH_ERREXCEPT) {
feclearexcept(FE_ALL_EXCEPT);
}
errno = 0;
result = asin(x);
if ((math_errhandling & MATH_ERRNO) && errno != 0) {
/* Handle range error */
} else if ((math_errhandling & MATH_ERREXCEPT) &&
fetestexcept(FE_INVALID | FE_DIVBYZERO |
FE_OVERFLOW | FE_UNDERFLOW) != 0) {
/* Handle range error */
}
}
/* Use result... */
} |
Risk Assessment
Failure to prevent or detect domain and range errors in math functions may cause unexpected results.
Rule | Severity | Likelihood | Remediation Cost | Priority | Level |
---|---|---|---|---|---|
FLP32-C | Medium | Probable | Medium | P8 | L2 |
Automated Detection
Tool | Version | Checker | Description | ||||||
---|---|---|---|---|---|---|---|---|---|
Astrée |
| stdlib-limits | Partially checked | ||||||
Axivion Bauhaus Suite |
| CertC-FLP32 | Partially implemented | ||||||
CodeSonar |
| MATH.DOMAIN.ATAN MATH.DOMAIN.TOOHIGH MATH.DOMAIN.TOOLOW MATH.DOMAIN MATH.RANGE MATH.RANGE.GAMMA MATH.DOMAIN.LOG MATH.RANGE.LOG MATH.DOMAIN.FE_INVALID MATH.DOMAIN.POW MATH.RANGE.COSH.TOOHIGH MATH.RANGE.COSH.TOOLOW MATH.DOMAIN.SQRT | Arctangent Domain Error Argument Too High Argument Too Low Floating Point Domain Error Floating Point Range Error Gamma on Zero Logarithm on Negative Value Logarithm on Zero Raises FE_INVALID Undefined Power of Zero cosh on High Number cosh on Low Number sqrt on Negative Value | ||||||
Helix QAC |
| C5025 C++5033 | |||||||
Parasoft C/C++test |
| CERT_C-FLP32-a | Validate values passed to library functions | ||||||
PC-lint Plus |
| 2423 | Partially supported: reports domain errors for functions with the Semantics *dom_1, *dom_lt0, or *dom_lt1, including standard library math functions | ||||||
Polyspace Bug Finder |
| CERT-C: Rule FLP32-C | Checks for invalid use of standard library floating point routine (rule fully covered) | ||||||
RuleChecker |
| stdlib-limits | Partially checked | ||||||
TrustInSoft Analyzer |
| out-of-range argument | Partially verified. |
Related Vulnerabilities
Search for vulnerabilities resulting from the violation of this rule on the CERT website.
Related Guidelines
Key here (explains table format and definitions)
Taxonomy | Taxonomy item | Relationship |
---|---|---|
CERT C Secure Coding Standard | FLP03-C. Detect and handle floating-point errors | Prior to 2018-01-12: CERT: Unspecified Relationship |
CWE 2.11 | CWE-682, Incorrect Calculation | 2017-07-07: CERT: Rule subset of CWE |
CERT-CWE Mapping Notes
Key here for mapping notes
CWE-391 and FLP32-C
Intersection( CWE-391, FLP32-C) =
- Failure to detect range errors in floating-point calculations
CWE-391 - FLP32-C
- Failure to detect errors in functions besides floating-point calculations
FLP32-C – CWE-391 =
- Failure to detect domain errors in floating-point calculations
CWE-682 and FLP32-C
Independent( INT34-C, FLP32-C, INT33-C) CWE-682 = Union( FLP32-C, list) where list =
- Incorrect calculations that do not involve floating-point range errors
Bibliography
[ISO/IEC 9899:2024] | 7.3.2, "Conventions" |
[IEEE 754 2006 ] |
...
cosh(x)
, sinh(x)
Noncompliant Code Example (Range Errors)
This noncompliant code example determines the hyperbolic cosine of x
.
Code Block | ||||
---|---|---|---|---|
| ||||
double x;
double result;
result = cosh(x);
|
This code may produce a range error if x
has a very large magnitude.
Compliant Solution
Since this function has no domain errors but may have range errors, the programmer must detect a range error and act accordingly.
Code Block | ||||
---|---|---|---|---|
| ||||
#include <math.h>
#if defined(math_errhandling) \
&& (math_errhandling & MATH_ERREXCEPT)
#include <fenv.h>
#endif
/* ... */
#if defined(math_errhandling) \
&& (math_errhandling & MATH_ERREXCEPT)
feclearexcept(FE_ALL_EXCEPT);
#endif
errno = 0;
double x;
double result;
result = sinh(x);
#if !defined(math_errhandling) \
|| (math_errhandling & MATH_ERRNO)
if (errno != 0) {
/* handle range error */
}
#endif
#if defined(math_errhandling) \
&& (math_errhandling & MATH_ERREXCEPT)
if (fetestexcept(FE_INVALID
| FE_DIVBYZERO
| FE_OVERFLOW
| FE_UNDERFLOW) != 0)
{
/* handle range error */
}
#endif
|
...
pow(x, y)
Noncompliant Code Example
The following noncompliant code raises x
to the power of y
.
Code Block | ||||
---|---|---|---|---|
| ||||
double x;
double y;
double result;
result = pow(x, y);
|
However, this code may produce a domain error if x
is negative and y
is not an integer or if x
is zero and y
is zero. A domain error or range error may occur if x
is zero and y
is negative, and a range error may occur if the result cannot be represented as a double
.
Compliant Solution
Since the pow()
function can produce both domain errors and range errors, the programmer must first check that x
and y
lie within the proper domain, then detect if a range error occurs and act accordingly.
Code Block | ||||
---|---|---|---|---|
| ||||
#include <math.h>
#if defined(math_errhandling) \
&& (math_errhandling & MATH_ERREXCEPT)
#include <fenv.h>
#endif
/* ... */
#if defined(math_errhandling) \
&& (math_errhandling & MATH_ERREXCEPT)
feclearexcept(FE_ALL_EXCEPT);
#endif
errno = 0;
/* call the function */
double x;
double y;
double result;
if (((x == 0.f) && islessequal(y, 0)) || (isless(x, 0))) {
/* handle domain error */
}
result = pow(x, y);
#if !defined(math_errhandling) \
|| (math_errhandling & MATH_ERRNO)
if (errno != 0) {
/* handle range error */
}
#endif
#if defined(math_errhandling) \
&& (math_errhandling & MATH_ERREXCEPT)
if (fetestexcept(FE_INVALID
| FE_DIVBYZERO
| FE_OVERFLOW
| FE_UNDERFLOW) != 0)
{
/* handle range error */
}
#endif
|
Risk Assessment
Failure to prevent or detect domain and range errors in math functions may result in unexpected results.
Rule | Severity | Likelihood | Remediation Cost | Priority | Level |
---|---|---|---|---|---|
FLP32-C | medium | probable | medium | P8 | L2 |
Automated Detection
Tool | Version | Checker | Description |
---|---|---|---|
Fortify SCA | 5.0 |
| Can detect violations of this rule with CERT C Rule Pack. |
Related Vulnerabilities
Search for vulnerabilities resulting from the violation of this rule on the CERT website.
Related Guidelines
CERT C++ Secure Coding Standard | FLP32-CPP. Prevent or detect domain and range errors in math functions |
MITRE CWE | CWE-682, Incorrect calculation |
Bibliography
complex.h
>"Section 7.12, "Mathematics <
math.h
>"[Plum 1985] | Rule 2-2 |
[Plum 1989] | Topic 2.10, "conv—Conversions and Overflow" |
...
[UNIX 1992] | System V Interface Definition (SVID3) |
...