```1`MATH_ERROR(7)              Linux Programmer's Manual             MATH_ERROR(7)`
2
3
4
```

## NAME

```6`       math_error - detecting errors from mathematical functions`
7
```

## SYNOPSIS

```9`       #include <math.h>`
10`       #include <errno.h>`
11`       #include <fenv.h>`
12
```

## DESCRIPTION

```14`       When  an  error  occurs,  most  library functions indicate this fact by`
15`       returning a special value (e.g., -1 or NULL).  Because  they  typically`
16`       return  a floating-point number, the mathematical functions declared in`
17`       <math.h> indicate an error  using  other  mechanisms.   There  are  two`
18`       error-reporting  mechanisms:  the  older  one sets errno; the newer one`
19`       uses the floating-point exception  mechanism  (the  use  of  feclearex‐`
20`       cept(3) and fetestexcept(3), as outlined below) described in fenv(3).`
21
22`       A portable program that needs to check for an error from a mathematical`
23`       function should set errno to zero, and make the following call`
24
25`           feclearexcept(FE_ALL_EXCEPT);`
26
27`       before calling a mathematical function.`
28
29`       Upon return from the mathematical function, if errno is nonzero, or the`
30`       following call (see fenv(3)) returns nonzero`
31
32`           fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW |`
33`                        FE_UNDERFLOW);`
34
35`       then an error occurred in the mathematical function.`
36
37`       The  error  conditions  that  can  occur for mathematical functions are`
38`       described below.`
39
40`   Domain error`
41`       A domain error occurs when a mathematical function is supplied with  an`
42`       argument whose value falls outside the domain for which the function is`
43`       defined (e.g., giving a negative argument to log(3)).   When  a  domain`
44`       error  occurs,  math functions commonly return a NaN (though some func‐`
45`       tions return a different value in this case); errno is set to EDOM, and`
46`       an "invalid" (FE_INVALID) floating-point exception is raised.`
47
48`   Pole error`
49`       A  pole  error  occurs when the mathematical result of a function is an`
50`       exact infinity (e.g., the logarithm of 0 is negative infinity).  When a`
51`       pole  error  occurs,  the function returns the (signed) value HUGE_VAL,`
52`       HUGE_VALF, or HUGE_VALL, depending on whether the function result  type`
53`       is double, float, or long double.  The sign of the result is that which`
54`       is mathematically correct for the function.  errno is  set  to  ERANGE,`
55`       and  a  "divide-by-zero"  (FE_DIVBYZERO)  floating-point  exception  is`
56`       raised.`
57
58`   Range error`
59`       A range error occurs when the magnitude of the  function  result  means`
60`       that  it cannot be represented in the result type of the function.  The`
61`       return value of the function depends on whether the range error was  an`
62`       overflow or an underflow.`
63
64`       A  floating  result overflows if the result is finite, but is too large`
65`       to represented in the result type.  When an overflow occurs, the  func‐`
66`       tion  returns the value HUGE_VAL, HUGE_VALF, or HUGE_VALL, depending on`
67`       whether the function result type is  double,  float,  or  long  double.`
68`       errno  is set to ERANGE, and an "overflow" (FE_OVERFLOW) floating-point`
69`       exception is raised.`
70
71`       A floating result underflows if the result is too small  to  be  repre‐`
72`       sented  in  the  result  type.   If an underflow occurs, a mathematical`
73`       function typically returns 0.0 (C99 says a function  shall  return  "an`
74`       implementation-defined  value  whose  magnitude  is no greater than the`
75`       smallest normalized positive number in the specified type").  errno may`
76`       be  set  to  ERANGE,  and  an  "overflow" (FE_UNDERFLOW) floating-point`
77`       exception may be raised.`
78
79`       Some functions deliver a range error if the supplied argument value, or`
80`       the  correct function result, would be subnormal.  A subnormal value is`
81`       one that is nonzero, but with a magnitude that  is  so  small  that  it`
82`       can't  be presented in normalized form (i.e., with a 1 in the most sig‐`
83`       nificant bit of the significand).  The representation  of  a  subnormal`
84`       number will contain one or more leading zeros in the significand.`
85
```
```87`       The  math_errhandling  identifier  specified  by C99 and POSIX.1 is not`
88`       supported by glibc.  This identifier is supposed to indicate  which  of`
89`       the  two  error-notification  mechanisms (errno, exceptions retrievable`
90`       via fettestexcept(3)) is in use.  The standards require that  at  least`
91`       one  be  in use, but permit both to be available.  The current (version`
92`       2.8) situation under glibc is messy.   Most  (but  not  all)  functions`
93`       raise  exceptions on errors.  Some also set errno.  A few functions set`
94`       errno, but don't raise an exception.  A very few functions do  neither.`
95`       See the individual manual pages for details.`
96
97`       To  avoid the complexities of using errno and fetestexcept(3) for error`
98`       checking, it is often advised that one should  instead  check  for  bad`
99`       argument  values  before  each  call.   For example, the following code`
100`       ensures that log(3)'s argument is not a NaN and is  not  zero  (a  pole`
101`       error) or less than zero (a domain error):`
102
103`           double x, r;`
104
105`           if (isnan(x) || islessequal(x, 0)) {`
106`               /* Deal with NaN / pole error / domain error */`
107`           }`
108
109`           r = log(x);`
110
111`       The  discussion on this page does not apply to the complex mathematical`
112`       functions (i.e., those declared by <complex.h>), which in  general  are`
113`       not required to return errors by C99 and POSIX.1.`
114
115`       The  gcc(1)  -fno-math-errno  option  causes  the  executable to employ`
116`       implementations of some mathematical functions that are faster than the`
117`       standard  implementations,  but do not set errno on error.  (The gcc(1)`
118`       -ffast-math option also enables -fno-math-errno.)  An error  can  still`
119`       be tested for using fetestexcept(3).`
120
```

```122`       gcc(1),  errno(3),  fenv(3),  fpclassify(3), INFINITY(3), isgreater(3),`
123`       matherr(3), nan(3)`
124
125`       info libc`
126
```

## COLOPHON

```128`       This page is part of release 4.15 of the Linux  man-pages  project.   A`
129`       description  of  the project, information about reporting bugs, and the`
130`       latest    version    of    this    page,    can     be     found     at`
131`       https://www.kernel.org/doc/man-pages/.`
132
133
134
135`Linux                             2017-09-15                     MATH_ERROR(7)`
```