math_error(7)

okay bestie, buckle up 💖 this is math_error(7), from the Miscellaneous Information Manual, section 7. it's the page that tells you how the math girlies signal that something went wrong. no cap, you need this. 🌸

💖 NAME 💖

math_error — detecting errors from mathematical functions 🚨

---

🦋 SYNOPSIS 🦋

#include <math.h>
#include <errno.h>
#include <fenv.h>

---

✨ DESCRIPTION ✨

so here's the tea 🫖 — when an error happens, most library functions just tell you by returning a special value (like -1 or NULL, iconic behaviour honestly). but the mathematical functions declared in <math.h> can't really do that, because they're out here returning floating-point numbers. so they use other mechanisms to spill the bad news.

there are two error-reporting mechanisms:

• the older one sets errno 👵
• the newer one uses the floating-point exception mechanism (the use of feclearexcept(3) and fetestexcept(3), as outlined below) described in fenv(3) ✨

if you want a portable program that actually checks for errors from a mathematical function, do this: set errno to zero, and make this call

feclearexcept(FE_ALL_EXCEPT);

before you call the mathematical function. yes, before. don't skip this step, it's giving pre-game ritual. 💅

then, once the mathematical function returns, if errno is nonzero, or the following call (see fenv(3)) returns nonzero

fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW |
             FE_UNDERFLOW);

then bestie… an error occurred in the mathematical function. 😭

the error conditions that can occur are described below. let's get into it.

---

🌀 Domain error

a domain error happens when a mathematical function gets an argument whose value falls outside the domain for which the function is defined (e.g., giving a negative argument to log(3) — rude, honestly).

when a domain error occurs:

• math functions commonly return a NaN (though some functions return a different value in this case, so don't @ me)
• errno is set to EDOM
• an "invalid" (FE_INVALID) floating-point exception is raised 🚫

⚡ Pole error

a pole error happens when the mathematical result of a function is an exact infinity (e.g., the logarithm of 0 is negative infinity — the math really said "no ❤️").

when a pole error occurs:

• the function returns the (signed) value HUGE_VAL, HUGE_VALF, or HUGE_VALL, depending on whether the function result type is double, float, or long double
• the sign of the result is that which is mathematically correct for the function ✨
• errno is set to ERANGE
• a "divide-by-zero" (FE_DIVBYZERO) floating-point exception is raised ➗

🌊 Range error

a range error happens when the magnitude of the function result means it literally cannot be represented in the result type of the function. and the return value depends on whether it was an overflow or an underflow — two very different girls. 💅

overflow: a floating result overflows if the result is finite, but is too large to be represented in the result type. when an overflow occurs:

• the function returns the value HUGE_VAL, HUGE_VALF, or HUGE_VALL, depending on whether the function result type is double, float, or long double
• errno is set to ERANGE
• an "overflow" (FE_OVERFLOW) floating-point exception is raised 🔥

underflow: a floating result 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" (yes that's a direct quote, she's verbose but she's right)
• errno may be set to ERANGE
• an "underflow" (FE_UNDERFLOW) floating-point exception may be raised 🫧

also some functions deliver a range error if the supplied argument value, or the correct function result, would be subnormal. a subnormal value is one that is nonzero, but with a magnitude so small it can't be represented 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. tiny. microscopic. a little baby number. 🐣

---

📝 NOTES 📝

okay this is the messy part and honestly the way that glibc handles this is stressful. 😭

the math_errhandling identifier specified by C99 and POSIX.1 is not supported by glibc. this identifier is supposed to indicate which of the two error-notification mechanisms (errno, exceptions retrievable via 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 errno
• a few functions set errno, but don't raise an exception
• a very few functions do neither 🙈

see the individual manual pages for details. iykyk.

---

so, to avoid the complexities of using errno and fetestexcept(3) for error checking, it is often advised that you should instead just check for bad argument values before each call. so valid of them, honestly. for example, the following code ensures that log(3)'s argument is not a NaN and is not zero (a pole error) or less than zero (a domain error):

double x, r;

if (isnan(x) || islessequal(x, 0)) {
    /* Deal with NaN / pole error / domain error */
}

r = log(x);

gorgeous. protective. main character energy. 👑

heads up bestie: the discussion on this page does not apply to the complex mathematical functions (i.e., those declared by <complex.h>), which in general are not required to return errors by C99 and POSIX.1.

also!! the gcc(1) -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 errno on error. (the gcc(1) -ffast-math option also enables -fno-math-errno.) but don't worry — an error can still be tested for using fetestexcept(3). 🫶

---

👀 SEE ALSO 👀

• gcc(1)
• errno(3)
• fenv(3)
• fpclassify(3)
• INFINITY(3)
• isgreater(3)
• matherr(3)
• nan(3)

info libc

---

and that's the whole page, bestie 💖 you're officially fluent in floating-point feelings. this was brought to you by Linux man-pages 6.20, dated 2025-05-17 — so yeah, that's the version, that's the date, slay. 🌈✨🎀