# MATH_ERROR

NAMESYNOPSIS

DESCRIPTION

NOTES

SEE ALSO

COLOPHON

## NAME

math_error − detecting errors from mathematical functions

## SYNOPSIS

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

## DESCRIPTION

When an error
occurs, most library functions indicate this fact by
returning a special value (e.g., −1 or NULL). Because
they typically return a floating-point number, the
mathematical functions declared in *<math.h>*
indicate an error using other mechanisms. 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).

A portable
program that needs to check for an error from a mathematical
function should set *errno* to zero, and make the
following call

feclearexcept(FE_ALL_EXCEPT);

before calling a mathematical function.

Upon return
from the mathematical function, if *errno* is nonzero,
or the following call (see fenv(3)) returns
nonzero

fetestexcept(FE_INVALID
| FE_DIVBYZERO | FE_OVERFLOW |

FE_UNDERFLOW);

then an error occurred in the mathematical function.

The error conditions that can occur for mathematical functions are described below.

**Domain
error**

A *domain error* occurs when a mathematical function is
supplied with an argument whose value falls outside the
domain for which the function is defined (e.g., giving a
negative argument to log(3)). When a domain error
occurs, math functions commonly return a NaN (though some
functions return a different value in this case);
*errno* is set to **EDOM**, and an
"invalid" (**FE_INVALID**) floating-point
exception is raised.

**Pole
error**

A *pole error* occurs when the mathematical result of a
function is an exact infinity (e.g., the logarithm of 0 is
negative infinity). 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**, and a "divide-by-zero"
(**FE_DIVBYZERO**) floating-point exception is
raised.

**Range
error**

A *range error* occurs when the magnitude of the
function result means that it cannot be represented in the
result type of the function. The return value of the
function depends on whether the range error was an overflow
or an underflow.

A floating
result *overflows* if the result is finite, but is too
large to 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**,
and an "overflow" (**FE_OVERFLOW**)
floating-point exception is raised.

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"). *errno*
may be set to **ERANGE**, and an "overflow"
(**FE_UNDERFLOW**) floating-point exception may be
raised.

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
that is so small that it can’t be presented 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.

## NOTES

The
*math_errhandling* identifier specified by C99 and
POSIX.1-2001 is not supported by glibc. This identifier is
supposed to indicate which of the two error-notification
mechanisms (*errno*, exceptions retrievable via
**fettestexcept**(3)) is in use. The standards require
that at least one be in use, but permit both to be
available. The current (version 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.

To avoid the
complexities of using *errno* and
fetestexcept(3) for error checking, it is often
advised that one should instead check for bad argument
values before each call. 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);

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-2001.

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*.) 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*

## COLOPHON

This page is
part of release 3.69 of the Linux *man-pages* project.
A description of the project, information about reporting
bugs, and the latest version of this page, can be found at
http://www.kernel.org/doc/man−pages/.

## More Linux Commands

manpages/XpGetDocumentData.3x.html**XpGetDocumentData(3x) - Creates and initializes a new print **

XpGetDocumentData registers callbacks that allow a consumer to continuously retrieve document data generated in the X Print Server by a separate producer, where

manpages/mysqld_multi.1.html**mysqld_multi(1) - manage multiple MySQL servers (Man Page)**

mysqld_multi is designed to manage several mysqld processes that listen for connections on different Unix socket files and TCP/IP ports. It can start or stop se

manpages/perltodo.1.html**perltodo(1) - Perl TO-DO List (Commands - Linux man page)...**

This is a list of wishes for Perl. The most up to date version of this file is at <http://perl5.git.perl.org/perl.git/blob_plain/HEAD:/pod/perltodo.pod> The tas

manpages/aio.7.html**aio(7) - POSIX asynchronous I/O overview - Linux man page...**

The POSIX asynchronous I/O (AIO) interface allows applications to initiate one or more I/O operations that are performed asynchronously (i.e., in the background

manpages/form_driver.3form.html**form_driver(3form) - command-processing loop of the form sys**

Once a form has been posted (displayed), you should funnel input events to it through form_driver. This routine has three major input cases: * The input is a fo

manpages/pam_umask.8.html**pam_umask(8) - PAM module to set the file mode creation mask**

pam_umask is a PAM module to set the file mode creation mask of the current environment. The umask affects the default permissions assigned to newly created fil

manpages/XcmsQueryBlack.3.html**XcmsQueryBlack(3) - obtain black, blue, green, red, and whit**

The XcmsQueryBlack function returns the color specification in the specified target format for zero-intensity red, green, and blue. The XcmsQueryBlue function r

manpages/ber_get_bitstring.3.html**ber_get_bitstring(3) - OpenLDAP LBER simplified Basic Encodi**

These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is

manpages/XtNameToWidget.3.html**XtNameToWidget(3) - translating strings to widgets or widget**

The XtNameToWidget function looks for a widget whose name is the first component in the specified names and that is a pop-up child of reference (or a normal chi

manpages/sane-epson.5.html**sane-epson(5) - SANE backend for EPSON scanners (Man Page)**

The sane-epson library implements a SANE (Scanner Access Now Easy) backend that provides access to Epson flatbed scanners. Some functions of this backend should

manpages/mrand48_r.3.html**mrand48_r(3) - generate uniformly distributed pseudo-random **

These functions are the reentrant analogs of the functions described in drand48(3). Instead of modifying the global random generator state, they use the supplie

manpages/mib2c-update.1.html**mib2c-update(1) - script to merge custom code into updated m**

Use mib2c-update to generate your mib2c code templates, and it will track the original code and the changes you make to the code. If the mib2c template changes