20. Arithmetic Functions

This chapter contains information about functions for doing basic arithmetic operations, such as splitting a float into its integer and fractional parts or retrieving the imaginary part of a complex value. These functions are declared in the header files `math.h' and `complex.h'.

20.1 Integers

The C language defines several integer data types: integer, short integer, long integer, and character, all in both signed and unsigned varieties. The GNU C compiler extends the language to contain long long integers as well.

The C integer types were intended to allow code to be portable among machines with different inherent data sizes (word sizes), so each type may have different ranges on different machines. The problem with this is that a program often needs to be written for a particular range of integers, and sometimes must be written for a particular size of storage, regardless of what machine the program runs on.

To address this problem, the GNU C library contains C type definitions you can use to declare integers that meet your exact needs. Because the GNU C library header files are customized to a specific machine, your program source code doesn't have to be.

These typedefs are in `stdint.h'.

If you require that an integer be represented in exactly N bits, use one of the following types, with the obvious mapping to bit size and signedness:

• int8_t
• int16_t
• int32_t
• int64_t
• uint8_t
• uint16_t
• uint32_t
• uint64_t

If your C compiler and target machine do not allow integers of a certain size, the corresponding above type does not exist.

If you don't need a specific storage size, but want the smallest data structure with at least N bits, use one of these:

• int_least8_t
• int_least16_t
• int_least32_t
• int_least64_t
• uint_least8_t
• uint_least16_t
• uint_least32_t
• uint_least64_t

If you don't need a specific storage size, but want the data structure that allows the fastest access while having at least N bits (and among data structures with the same access speed, the smallest one), use one of these:

• int_fast8_t
• int_fast16_t
• int_fast32_t
• int_fast64_t
• uint_fast8_t
• uint_fast16_t
• uint_fast32_t
• uint_fast64_t

If you want an integer with the widest range possible on the platform on which it is being used, use one of the following. If you use these, you should write code that takes into account the variable size and range of the integer.

• intmax_t
• uintmax_t

The GNU C library also provides macros that tell you the maximum and minimum possible values for each integer data type. The macro names follow these examples: INT32_MAX, UINT8_MAX, INT_FAST32_MIN, INT_LEAST64_MIN, UINTMAX_MAX, INTMAX_MAX, INTMAX_MIN. Note that there are no macros for unsigned integer minima. These are always zero.

There are similar macros for use with C's built in integer types which should come with your C compiler. These are described in A.5 Data Type Measurements.

Don't forget you can use the C sizeof function with any of these data types to get the number of bytes of storage each uses.

20.2 Integer Division

This section describes functions for performing integer division. These functions are redundant when GNU CC is used, because in GNU C the `/' operator always rounds towards zero. But in other C implementations, `/' may round differently with negative arguments. div and ldiv are useful because they specify how to round the quotient: towards zero. The remainder has the same sign as the numerator.

These functions are specified to return a result r such that the value r.quot*denominator + r.rem equals numerator.

To use these facilities, you should include the header file `stdlib.h' in your program.

Data Type: div_t

This is a structure type used to hold the result returned by the div function. It has the following members:

int quot

The quotient from the division.

int rem

The remainder from the division.

Function: div_t div (int numerator, int denominator)

This function div computes the quotient and remainder from the division of numerator by denominator, returning the result in a structure of type div_t.

If the result cannot be represented (as in a division by zero), the behavior is undefined.

Here is an example, albeit not a very useful one.

div_t result; result = div (20, -6);

Now result.quot is -3 and result.rem is 2.

Data Type: ldiv_t

This is a structure type used to hold the result returned by the ldiv function. It has the following members:

long int quot

The quotient from the division.

long int rem

The remainder from the division.

(This is identical to div_t except that the components are of type long int rather than int.)

Function: ldiv_t ldiv (long int numerator, long int denominator)

The ldiv function is similar to div, except that the arguments are of type long int and the result is returned as a structure of type ldiv_t.

Data Type: lldiv_t

This is a structure type used to hold the result returned by the lldiv function. It has the following members:

long long int quot

The quotient from the division.

long long int rem

The remainder from the division.

(This is identical to div_t except that the components are of type long long int rather than int.)

Function: lldiv_t lldiv (long long int numerator, long long int denominator)

The lldiv function is like the div function, but the arguments are of type long long int and the result is returned as a structure of type lldiv_t.

The lldiv function was added in ISO C99.

Data Type: imaxdiv_t

This is a structure type used to hold the result returned by the imaxdiv function. It has the following members:

intmax_t quot

The quotient from the division.

intmax_t rem

The remainder from the division.

(This is identical to div_t except that the components are of type intmax_t rather than int.)

See 20.1 Integers for a description of the intmax_t type.

Function: imaxdiv_t imaxdiv (intmax_t numerator, intmax_t denominator)

The imaxdiv function is like the div function, but the arguments are of type intmax_t and the result is returned as a structure of type imaxdiv_t.

See 20.1 Integers for a description of the intmax_t type.

The imaxdiv function was added in ISO C99.

20.3 Floating Point Numbers

Most computer hardware has support for two different kinds of numbers: integers () and floating-point numbers. Floating-point numbers have three parts: the mantissa, the exponent, and the sign bit. The real number represented by a floating-point value is given by where is the sign bit, the exponent, and the mantissa. See section A.5.3.1 Floating Point Representation Concepts, for details. (It is possible to have a different base for the exponent, but all modern hardware uses .)

Floating-point numbers can represent a finite subset of the real numbers. While this subset is large enough for most purposes, it is important to remember that the only reals that can be represented exactly are rational numbers that have a terminating binary expansion shorter than the width of the mantissa. Even simple fractions such as can only be approximated by floating point.

Mathematical operations and functions frequently need to produce values that are not representable. Often these values can be approximated closely enough for practical purposes, but sometimes they can't. Historically there was no way to tell when the results of a calculation were inaccurate. Modern computers implement the IEEE 754 standard for numerical computations, which defines a framework for indicating to the program when the results of calculation are not trustworthy. This framework consists of a set of exceptions that indicate why a result could not be represented, and the special values infinity and not a number (NaN).

20.4 Floating-Point Number Classification Functions

ISO C99 defines macros that let you determine what sort of floating-point number a variable holds.

Macro: int fpclassify (float-type x)

This is a generic macro which works on all floating-point types and which returns a value of type int. The possible values are:

FP_NAN

The floating-point number x is "Not a Number" (see section 20.5.2 Infinity and NaN)

FP_INFINITE

The value of x is either plus or minus infinity (see section 20.5.2 Infinity and NaN)

FP_ZERO

The value of x is zero. In floating-point formats like IEEE 754, where zero can be signed, this value is also returned if x is negative zero.

FP_SUBNORMAL

Numbers whose absolute value is too small to be represented in the normal format are represented in an alternate, denormalized format (see section A.5.3.1 Floating Point Representation Concepts). This format is less precise but can represent values closer to zero. fpclassify returns this value for values of x in this alternate format.

FP_NORMAL

This value is returned for all other values of x. It indicates that there is nothing special about the number.

fpclassify is most useful if more than one property of a number must be tested. There are more specific macros which only test one property at a time. Generally these macros execute faster than fpclassify, since there is special hardware support for them. You should therefore use the specific macros whenever possible.

Macro: int isfinite (float-type x)

This macro returns a nonzero value if x is finite: not plus or minus infinity, and not NaN. It is equivalent to

(fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)

isfinite is implemented as a macro which accepts any floating-point type.

Macro: int isnormal (float-type x)

This macro returns a nonzero value if x is finite and normalized. It is equivalent to

(fpclassify (x) == FP_NORMAL)

Macro: int isnan (float-type x)

This macro returns a nonzero value if x is NaN. It is equivalent to

(fpclassify (x) == FP_NAN)

Another set of floating-point classification functions was provided by BSD. The GNU C library also supports these functions; however, we recommend that you use the ISO C99 macros in new code. Those are standard and will be available more widely. Also, since they are macros, you do not have to worry about the type of their argument.

Function: int isinf (double x)

Function: int isinff (float x)

Function: int isinfl (long double x)

This function returns -1 if x represents negative infinity, 1 if x represents positive infinity, and 0 otherwise.

Function: int isnan (double x)

Function: int isnanf (float x)

Function: int isnanl (long double x)

This function returns a nonzero value if x is a "not a number" value, and zero otherwise.

Note: The isnan macro defined by ISO C99 overrides the BSD function. This is normally not a problem, because the two routines behave identically. However, if you really need to get the BSD function for some reason, you can write

(isnan) (x)

Function: int finite (double x)

Function: int finitef (float x)

Function: int finitel (long double x)

This function returns a nonzero value if x is finite or a "not a number" value, and zero otherwise.

Portability Note: The functions listed in this section are BSD extensions.

20.5 Errors in Floating-Point Calculations

20.5.1 FP Exceptions

The IEEE 754 standard defines five exceptions that can occur during a calculation. Each corresponds to a particular sort of error, such as overflow.

When exceptions occur (when exceptions are raised, in the language of the standard), one of two things can happen. By default the exception is simply noted in the floating-point status word, and the program continues as if nothing had happened. The operation produces a default value, which depends on the exception (see the table below). Your program can check the status word to find out which exceptions happened.

Alternatively, you can enable traps for exceptions. In that case, when an exception is raised, your program will receive the SIGFPE signal. The default action for this signal is to terminate the program. See section 24. Signal Handling, for how you can change the effect of the signal.

In the System V math library, the user-defined function matherr is called when certain exceptions occur inside math library functions. However, the Unix98 standard deprecates this interface. We support it for historical compatibility, but recommend that you do not use it in new programs.

The exceptions defined in IEEE 754 are:

`Invalid Operation'

This exception is raised if the given operands are invalid for the operation to be performed. Examples are (see IEEE 754, section 7):

1. Addition or subtraction: . (But ).
2. Multiplication: .
3. Division: or .
4. Remainder: REM , where is zero or is infinite.
5. Square root if the operand is less then zero. More generally, any mathematical function evaluated outside its domain produces this exception.
6. Conversion of a floating-point number to an integer or decimal string, when the number cannot be represented in the target format (due to overflow, infinity, or NaN).
7. Conversion of an unrecognizable input string.
8. Comparison via predicates involving or , when one or other of the operands is NaN. You can prevent this exception by using the unordered comparison functions instead; see 20.8.6 Floating-Point Comparison Functions.

If the exception does not trap, the result of the operation is NaN.

`Division by Zero'

This exception is raised when a finite nonzero number is divided by zero. If no trap occurs the result is either or , depending on the signs of the operands.

`Overflow'

This exception is raised whenever the result cannot be represented as a finite value in the precision format of the destination. If no trap occurs the result depends on the sign of the intermediate result and the current rounding mode (IEEE 754, section 7.3):

1. Round to nearest carries all overflows to with the sign of the intermediate result.
2. Round toward carries all overflows to the largest representable finite number with the sign of the intermediate result.
3. Round toward carries positive overflows to the largest representable finite number and negative overflows to .

4. Round toward carries negative overflows to the most negative representable finite number and positive overflows to .

Whenever the overflow exception is raised, the inexact exception is also raised.

`Underflow'

The underflow exception is raised when an intermediate result is too small to be calculated accurately, or if the operation's result rounded to the destination precision is too small to be normalized.

When no trap is installed for the underflow exception, underflow is signaled (via the underflow flag) only when both tininess and loss of accuracy have been detected. If no trap handler is installed the operation continues with an imprecise small value, or zero if the destination precision cannot hold the small exact result.

`Inexact'

This exception is signalled if a rounded result is not exact (such as when calculating the square root of two) or a result overflows without an overflow trap.

20.5.2 Infinity and NaN

IEEE 754 floating point numbers can represent positive or negative infinity, and NaN (not a number). These three values arise from calculations whose result is undefined or cannot be represented accurately. You can also deliberately set a floating-point variable to any of them, which is sometimes useful. Some examples of calculations that produce infinity or NaN:

When a calculation produces any of these values, an exception also occurs; see 20.5.1 FP Exceptions.

The basic operations and math functions all accept infinity and NaN and produce sensible output. Infinities propagate through calculations as one would expect: for example, , , atan . NaN, on the other hand, infects any calculation that involves it. Unless the calculation would produce the same result no matter what real value replaced NaN, the result is NaN.

In comparison operations, positive infinity is larger than all values except itself and NaN, and negative infinity is smaller than all values except itself and NaN. NaN is unordered: it is not equal to, greater than, or less than anything, including itself. x == x is false if the value of x is NaN. You can use this to test whether a value is NaN or not, but the recommended way to test for NaN is with the isnan function (see section 20.4 Floating-Point Number Classification Functions). In addition, <, >, <=, and >= will raise an exception when applied to NaNs.

`math.h' defines macros that allow you to explicitly set a variable to infinity or NaN.

Macro: float INFINITY

An expression representing positive infinity. It is equal to the value produced by mathematical operations like 1.0 / 0.0. -INFINITY represents negative infinity.

You can test whether a floating-point value is infinite by comparing it to this macro. However, this is not recommended; you should use the isfinite macro instead. See section 20.4 Floating-Point Number Classification Functions.

This macro was introduced in the ISO C99 standard.

Macro: float NAN

An expression representing a value which is "not a number". This macro is a GNU extension, available only on machines that support the "not a number" value--that is to say, on all machines that support IEEE floating point.

You can steaibc_20.html#SEC410">20.5.2 Infinity and NaN)

FP_ZERO

The value of x is zero. In floating-point formats like IEEE 754, where zero can be signed, this value is also returned if x is negative zero.

FP_SUBNORMAL

Numbers whose absolute value is too small to be represented in the normal format are represented in an alternate, denormalized format (see section A.5.3.1 Floating Point Representation Concepts). This format is less precise but can represent values closer to zero. fpclassify returns this value for values of x in this alternate format.

FP_NORMAL

This value is returned for all other values of x. It indicates that there is nothing special about the number.

fpclassify is most useful if more than one property of a number must be tested. There are more specific macros which only test one property at a time. Generally these macros execute faster than fpclassify, since there is special hardware support for them. You should therefore use the specific macros whenever possible.

Macro: int isfinite (float-type x)

This macro returns a nonzero value if x is finite: not plus or minus infinity, and not NaN. It is equivalent to

(fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)

isfinite is implemented as a macro which accepts any floating-point type.

Macro: int isnormal (float-type x)

This macro returns a nonzero value if x is finite and normalized. It is equivalent to

(fpclassify (x) == FP_NORMAL)

Macro: int isnan (float-type x)

This macro returns a nonzero value if x is NaN. It is equivalent to

(fpclassify (x) == FP_NAN)

Another set of floating-point classification functions was provided by BSD. The GNU C library also supports these functions; however, we recommend that you use the ISO C99 macros in new code. Those are standard and will be available more widely. Also, since they are macros, you do not have to worry about the type of their argument.

Function: int isinf (double x)

Function: int isinff (float x)

Function: int isinfl (long double x)

This function returns -1 if x represents negative infinity, 1 if x represents positive infinity, and 0 otherwise.

Function: int isnan (double x)

Function: int isnanf (float x)

Function: int isnanl (long double x)

This function returns a nonzero value if x is a "not a number" value, and zero otherwise.

Note: The isnan macro defined by ISO C99 overrides the BSD function. This is normally not a problem, because the two routines behave identically. However, if you really need to get the BSD function for some reason, you can write

(isnan) (x)

Function: int finite (double x)

Function: int finitef (float x)

Function: int finitel (long double x)

This function returns a nonzero value if x is finite or a "not a number" value, and zero otherwise.

Portability Note: The functions listed in this section are BSD extensions.

20.5 Errors in Floating-Point Calculations

20.5.1 FP Exceptions

The IEEE 754 standard defines five exceptions that can occur during a calculation. Each corresponds to a particular sort of error, such as overflow.

When exceptions occur (when exceptions are raised, in the language of the standard), one of two things can happen. By default the exception is simply noted in the floating-point status word, and the program continues as if nothing had happened. The operation produces a default value, which depends on the exception (see the table below). Your program can check the status word to find out which exceptions happened.

Alternatively, you can enable traps for exceptions. In that case, when an exception is raised, your program will receive the SIGFPE signal. The default action for this signal is to terminate the program. See section 24. Signal Handling, for how you can change the effect of the signal.

In the System V math library, the user-defined function matherr is called when certain exceptions occur inside math library functions. However, the Unix98 standard deprecates this interface. We support it for historical compatibility, but recommend that you do not use it in new programs.

The exceptions defined in IEEE 754 are:

`Invalid Operation'

This exception is raised if the given operands are invalid for the operation to be performed. Examples are (see IEEE 754, section 7):

1. Addition or subtraction: . (But ).
2. Multiplication: .
3. Division: or .
4. Remainder: REM , where is zero or is infinite.
5. Square root if the operand is less then zero. More generally, any mathematical function evaluated outside its domain produces this exception.
6. Conversion of a floating-point number to an integer or decimal string, when the number cannot be represented in the target format (due to overflow, infinity, or NaN).
7. Conversion of an unrecognizable input string.
8. Comparison via predicates involving or , when one or other of the operands is NaN. You can prevent this exception by using the unordered comparison functions instead; see 20.8.6 Floating-Point Comparison Functions.

If the exception does not trap, the result of the operation is NaN.

`Division by Zero'

This exception is raised when a finite nonzero number is divided by zero. If no trap occurs the result is either or , depending on the signs of the operands.

`Overflow'

This exception is raised whenever the result cannot be represented as a finite value in the precision format of the destination. If no trap occurs the result depends on the sign of the intermediate result and the current rounding mode (IEEE 754, section 7.3):

1. Round to nearest carries all overflows to with the sign of the intermediate result.
2. Round toward carries all overflows to the largest representable finite number with the sign of the intermediate result.
3. Round toward carries positive overflows to the largest representable finite number and negative overflows to .

4. Round toward carries negative overflows to the most negative representable finite number and positive overflows to .

Whenever the overflow exception is raised, the inexact exception is also raised.

`Underflow'

The underflow exception is raised when an intermediate result is too small to be calculated accurately, or if the operation's result rounded to the destination precision is too small to be normalized.

When no trap is installed for the underflow exception, underflow is signaled (via the underflow flag) only when both tininess and loss of accuracy have been detected. If no trap handler is installed the operation continues with an imprecise small value, or zero if the destination precision cannot hold the small exact result.

`Inexact'

This exception is signalled if a rounded result is not exact (such as when calculating the square root of two) or a result overflows without an overflow trap.

20.5.2 Infinity and NaN

IEEE 754 floating point numbers can represent positive or negative infinity, and NaN (not a number). These three values arise from calculations whose result is undefined or cannot be represented accurately. You can also deliberately set a floating-point variable to any of them, which is sometimes useful. Some examples of calculations that produce infinity or NaN:

When a calculation produces any of these values, an exception also occurs; see 20.5.1 FP Exceptions.

The basic operations and math functions all accept infinity and NaN and produce sensible output. Infinities propagate through calculations as one would expect: for example, , , atan . NaN, on the other hand, infects any calculation that involves it. Unless the calculation would produce the same result no matter what real value replaced NaN, the result is NaN.

In comparison operations, positive infinity is larger than all values except itself and NaN, and negative infinity is smaller than all values except itself and NaN. NaN is unordered: it is not equal to, greater than, or less than anything, including itself. x == x is false if the value of x is NaN. You can use this to test whether a value is NaN or not, but the recommended way to test for NaN is with the isnan function (see section 20.4 Floating-Point Number Classification Functions). In addition, <, >, <=, and >= will raise an exception when applied to NaNs.

`math.h' defines macros that allow you to explicitly set a variable to infinity or NaN.

Macro: float INFINITY

An expression representing positive infinity. It is equal to the value produced by mathematical operations like 1.0 / 0.0. -INFINITY represents negative infinity.

You can test whether a floating-point value is infinite by comparing it to this macro. However, this is not recommended; you should use the isfinite macro instead. See section 20.4 Floating-Point Number Classification Functions.

This macro was introduced in the ISO C99 standard.

Macro: float NAN

An expression representing a value which is "not a number". This macro is a GNU extension, available only on machines that support the "not a number" value--that is to say, on all machines that support IEEE floating point.

You can steaibc_20.html#SEC410">20.5.2 Infinity and NaN)

FP_ZERO

The value of x is zero. In floating-point formats like IEEE 754, where zero can be signed, this value is also returned if x is negative zero.

FP_SUBNORMAL

Numbers whose absolute value is too small to be represented in the normal format are represented in an alternate, denormalized format (see section A.5.3.1 Floating Point Representation Concepts). This format is less precise but can represent values closer to zero. fpclassify returns this value for values of x in this alternate format.

FP_NORMAL

This value is returned for all other values of x. It indicates that there is nothing special about the number.

fpclassify is most useful if more than one property of a number must be tested. There are more specific macros which only test one property at a time. Generally these macros execute faster than fpclassify, since there is special hardware support for them. You should therefore use the specific macros whenever possible.

Macro: int isfinite (float-type x)

This macro returns a nonzero value if x is finite: not plus or minus infinity, and not NaN. It is equivalent to

(fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)

isfinite is implemented as a macro which accepts any floating-point type.

Macro: int isnormal (float-type x)

This macro returns a nonzero value if x is finite and normalized. It is equivalent to

(fpclassify (x) == FP_NORMAL)

Macro: int isnan (float-type x)

This macro returns a nonzero value if x is NaN. It is equivalent to

(fpclassify (x) == FP_NAN)

Another set of floating-point classification functions was provided by BSD. The GNU C library also supports these functions; however, we recommend that you use the ISO C99 macros in new code. Those are standard and will be available more widely. Also, since they are macros, you do not have to worry about the type of their argument.

Function: int isinf (double x)

Function: int isinff (float x)

Function: int isinfl (long double x)

This function returns -1 if x represents negative infinity, 1 if x represents positive infinity, and 0 otherwise.

Function: int isnan (double x)

Function: int isnanf (float x)

Function: int isnanl (long double x)

This function returns a nonzero value if x is a "not a number" value, and zero otherwise.

Note: The isnan macro defined by ISO C99 overrides the BSD function. This is normally not a problem, because the two routines behave identically. However, if you really need to get the BSD function for some reason, you can write

(isnan) (x)

Function: int finite (double x)

Function: int finitef (float x)

Function: int finitel (long double x)

This function returns a nonzero value if x is finite or a "not a number" value, and zero otherwise.

Portability Note: The functions listed in this section are BSD extensions.

20.5 Errors in Floating-Point Calculations

20.5.1 FP Exceptions

The IEEE 754 standard defines five exceptions that can occur during a calculation. Each corresponds to a particular sort of error, such as overflow.

When exceptions occur (when exceptions are raised, in the language of the standard), one of two things can happen. By default the exception is simply noted in the floating-point status word, and the program continues as if nothing had happened. The operation produces a default value, which depends on the exception (see the table below). Your program can check the status word to find out which exceptions happened.

Alternatively, you can enable traps for exceptions. In that case, when an exception is raised, your program will receive the SIGFPE signal. The default action for this signal is to terminate the program. See section 24. Signal Handling, for how you can change the effect of the signal.

In the System V math library, the user-defined function matherr is called when certain exceptions occur inside math library functions. However, the Unix98 standard deprecates this interface. We support it for historical compatibility, but recommend that you do not use it in new programs.

The exceptions defined in IEEE 754 are:

`Invalid Operation'

This exception is raised if the given operands are invalid for the operation to be performed. Examples are (see IEEE 754, section 7):

1. Addition or subtraction: . (But ).
2. Multiplication: .
3. Division: or .
4. Remainder: REM , where is zero or is infinite.
5. Square root if the operand is less then zero. More generally, any mathematical function evaluated outside its domain produces this exception.
6. Conversion of a floating-point number to an integer or decimal string, when the number cannot be represented in the target format (due to overflow, infinity, or NaN).
7. Conversion of an unrecognizable input string.
8. Comparison via predicates involving or , when one or other of the operands is NaN. You can prevent this exception by using the unordered comparison functions instead; see 20.8.6 Floating-Point Comparison Functions.

If the exception does not trap, the result of the operation is NaN.

`Division by Zero'

This exception is raised when a finite nonzero number is divided by zero. If no trap occurs the result is either or , depending on the signs of the operands.

`Overflow'

This exception is raised whenever the result cannot be represented as a finite value in the precision format of the destination. If no trap occurs the result depends on the sign of the intermediate result and the current rounding mode (IEEE 754, section 7.3):

1. Round to nearest carries all overflows to with the sign of the intermediate result.
2. Round toward carries all overflows to the largest representable finite number with the sign of the intermediate result.
3. Round toward carries positive overflows to the largest representable finite number and negative overflows to .

4. Round toward carries negative overflows to the most negative representable finite number and positive overflows to .

Whenever the overflow exception is raised, the inexact exception is also raised.

`Underflow'

The underflow exception is raised when an intermediate result is too small to be calculated accurately, or if the operation's result rounded to the destination precision is too small to be normalized.

When no trap is installed for the underflow exception, underflow is signaled (via the underflow flag) only when both tininess and loss of accuracy have been detected. If no trap handler is installed the operation continues with an imprecise small value, or zero if the destination precision cannot hold the small exact result.

`Inexact'

This exception is signalled if a rounded result is not exact (such as when calculating the square root of two) or a result overflows without an overflow trap.

20.5.2 Infinity and NaN

IEEE 754 floating point numbers can represent positive or negative infinity, and NaN (not a number). These three values arise from calculations whose result is undefined or cannot be represented accurately. You can also deliberately set a floating-point variable to any of them, which is sometimes useful. Some examples of calculations that produce infinity or NaN:

When a calculation produces any of these values, an exception also occurs; see 20.5.1 FP Exceptions.

The basic operations and math functions all accept infinity and NaN and produce sensible output. Infinities propagate through calculations as one would expect: for example, , , atan . NaN, on the other hand, infects any calculation that involves it. Unless the calculation would produce the same result no matter what real value replaced NaN, the result is NaN.

In comparison operations, positive infinity is larger than all values except itself and NaN, and negative infinity is smaller than all values except itself and NaN. NaN is unordered: it is not equal to, greater than, or less than anything, including itself. x == x is false if the value of x is NaN. You can use this to test whether a value is NaN or not, but the recommended way to test for NaN is with the isnan function (see section 20.4 Floating-Point Number Classification Functions). In addition, <, >, <=, and >= will raise an exception when applied to NaNs.

`math.h' defines macros that allow you to explicitly set a variable to infinity or NaN.

Macro: float INFINITY

An expression representing positive infinity. It is equal to the value produced by mathematical operations like 1.0 / 0.0. -INFINITY represents negative infinity.

You can test whether a floating-point value is infinite by comparing it to this macro. However, this is not recommended; you should use the isfinite macro instead. See section 20.4 Floating-Point Number Classification Functions.

This macro was introduced in the ISO C99 standard.

Macro: float NAN

An expression representing a value which is "not a number". This macro is a GNU extension, available only on machines that support the "not a number" value--that is to say, on all machines that support IEEE floating point.

You can steaibc_20.html#SEC410">20.5.2 Infinity and NaN)

FP_ZERO

The value of x is zero. In floating-point formats like IEEE 754, where zero can be signed, this value is also returned if x is negative zero.

FP_SUBNORMAL

Numbers whose absolute value is too small to be represented in the normal format are represented in an alternate, denormalized format (see section A.5.3.1 Floating Point Representation Concepts). This format is less precise but can represent values closer to zero. fpclassify returns this value for values of x in this alternate format.

FP_NORMAL

This value is returned for all other values of x. It indicates that there is nothing special about the number.

fpclassify is most useful if more than one property of a number must be tested. There are more specific macros which only test one property at a time. Generally these macros execute faster than fpclassify, since there is special hardware support for them. You should therefore use the specific macros whenever possible.

Macro: int isfinite (float-type x)

This macro returns a nonzero value if x is finite: not plus or minus infinity, and not NaN. It is equivalent to

(fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)

isfinite is implemented as a macro which accepts any floating-point type.

Macro: int isnormal (float-type x)

This macro returns a nonzero value if x is finite and normalized. It is equivalent to

(fpclassify (x) == FP_NORMAL)

Macro: int isnan (float-type x)

This macro returns a nonzero value if x is NaN. It is equivalent to

(fpclassify (x) == FP_NAN)

Another set of floating-point classification functions was provided by BSD. The GNU C library also supports these functions; however, we recommend that you use the ISO C99 macros in new code. Those are standard and will be available more widely. Also, since they are macros, you do not have to worry about the type of their argument.

Function: int isinf (double x)

Function: int isinff (float x)

Function: int isinfl (long double x)

This function returns -1 if x represents negative infinity, 1 if x represents positive infinity, and 0 otherwise.

Function: int isnan (double x)

Function: int isnanf (float x)

Function: int isnanl (long double x)

This function returns a nonzero value if x is a "not a number" value, and zero otherwise.

Note: The isnan macro defined by ISO C99 overrides the BSD function. This is normally not a problem, because the two routines behave identically. However, if you really need to get the BSD function for some reason, you can write

(isnan) (x)

Function: int finite (double x)

Function: int finitef (float x)

Function: int finitel (long double x)

This function returns a nonzero value if x is finite or a "not a number" value, and zero otherwise.

Portability Note: The functions listed in this section are BSD extensions.

20.5 Errors in Floating-Point Calculations

20.5.1 FP Exceptions

The IEEE 754 standard defines five exceptions that can occur during a calculation. Each corresponds to a particular sort of error, such as overflow.

When exceptions occur (when exceptions are raised, in the language of the standard), one of two things can happen. By default the exception is simply noted in the floating-point status word, and the program continues as if nothing had happened. The operation produces a default value, which depends on the exception (see the table below). Your program can check the status word to find out which exceptions happened.

Alternatively, you can enable traps for exceptions. In that case, when an exception is raised, your program will receive the SIGFPE signal. The default action for this signal is to terminate the program. See section 24. Signal Handling, for how you can change the effect of the signal.

In the System V math library, the user-defined function matherr is called when certain exceptions occur inside math library functions. However, the Unix98 standard deprecates this interface. We support it for historical compatibility, but recommend that you do not use it in new programs.

The exceptions defined in IEEE 754 are:

`Invalid Operation'

This exception is raised if the given operands are invalid for the operation to be performed. Examples are (see IEEE 754, section 7):

1. Addition or subtraction: . (But ).
2. Multiplication: .
3. Division: or .
4. Remainder: REM , where is zero or is infinite.
5. Square root if the operand is less then zero. More generally, any mathematical function evaluated outside its domain produces this exception.
6. Conversion of a floating-point number to an integer or decimal string, when the number cannot be represented in the target format (due to overflow, infinity, or NaN).
7. Conversion of an unrecognizable input string.
8. Comparison via predicates involving or , when one or other of the operands is NaN. You can prevent this exception by using the unordered comparison functions instead; see 20.8.6 Floating-Point Comparison Functions.

If the exception does not trap, the result of the operation is NaN.

`Division by Zero'

This exception is raised when a finite nonzero number is divided by zero. If no trap occurs the result is either or , depending on the signs of the operands.

`Overflow'

This exception is raised whenever the result cannot be represented as a finite value in the precision format of the destination. If no trap occurs the result depends on the sign of the intermediate result and the current rounding mode (IEEE 754, section 7.3):

1. Round to nearest carries all overflows to with the sign of the intermediate result.
2. Round toward carries all overflows to the largest representable finite number with the sign of the intermediate result.
3. Round toward carries positive overflows to the largest representable finite number and negative overflows to .

4. Round toward carries negative overflows to the most negative representable finite number and positive overflows to .

Whenever the overflow exception is raised, the inexact exception is also raised.

`Underflow'

The underflow exception is raised when an intermediate result is too small to be calculated accurately, or if the operation's result rounded to the destination precision is too small to be normalized.

When no trap is installed for the underflow exception, underflow is signaled (via the underflow flag) only when both tininess and loss of accuracy have been detected. If no trap handler is installed the operation continues with an imprecise small value, or zero if the destination precision cannot hold the small exact result.

`Inexact'

This exception is signalled if a rounded result is not exact (such as when calculating the square root of two) or a result overflows without an overflow trap.

20.5.2 Infinity and NaN

IEEE 754 floating point numbers can represent positive or negative infinity, and NaN (not a number). These three values arise from calculations whose result is undefined or cannot be represented accurately. You can also deliberately set a floating-point variable to any of them, which is sometimes useful. Some examples of calculations that produce infinity or NaN:

When a calculation produces any of these values, an exception also occurs; see 20.5.1 FP Exceptions.

The basic operations and math functions all accept infinity and NaN and produce sensible output. Infinities propagate through calculations as one would expect: for example, , , atan . NaN, on the other hand, infects any calculation that involves it. Unless the calculation would produce the same result no matter what real value replaced NaN, the result is NaN.

In comparison operations, positive infinity is larger than all values except itself and NaN, and negative infinity is smaller than all values except itself and NaN. NaN is unordered: it is not equal to, greater than, or less than anything, including itself. x == x is false if the value of x is NaN. You can use this to test whether a value is NaN or not, but the recommended way to test for NaN is with the isnan function (see section 20.4 Floating-Point Number Classification Functions). In addition, <, >, <=, and >= will raise an exception when applied to NaNs.

`math.h' defines macros that allow you to explicitly set a variable to infinity or NaN.

Macro: float INFINITY

An expression representing positive infinity. It is equal to the value produced by mathematical operations like 1.0 / 0.0. -INFINITY represents negative infinity.

You can test whether a floating-point value is infinite by comparing it to this macro. However, this is not recommended; you should use the isfinite macro instead. See section 20.4 Floating-Point Number Classification Functions.

This macro was introduced in the ISO C99 standard.

Macro: float NAN

An expression representing a value which is "not a number". This macro is a GNU extension, available only on machines that support the "not a number" value--that is to say, on all machines that support IEEE floating point.

You can steaibc_20.html#SEC410">20.5.2 Infinity and NaN)

FP_ZERO

The value of x is zero. In floating-point formats like IEEE 754, where zero can be signed, this value is also returned if x is negative zero.

FP_SUBNORMAL

Numbers whose absolute value is too small to be represented in the normal format are represented in an alternate, denormalized format (see section A.5.3.1 Floating Point Representation Concepts). This format is less precise but can represent values closer to zero. fpclassify returns this value for values of x in this alternate format.

FP_NORMAL

This value is returned for all other values of x. It indicates that there is nothing special about the number.

fpclassify is most useful if more than one property of a number must be tested. There are more specific macros which only test one property at a time. Generally these macros execute faster than fpclassify, since there is special hardware support for them. You should therefore use the specific macros whenever possible.

Macro: int isfinite (float-type x)

This macro returns a nonzero value if x is finite: not plus or minus infinity, and not NaN. It is equivalent to

(fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)

isfinite is implemented as a macro which accepts any floating-point type.

Macro: int isnormal (float-type x)

This macro returns a nonzero value if x is finite and normalized. It is equivalent to

(fpclassify (x) == FP_NORMAL)

Macro: int isnan (float-type x)

This macro returns a nonzero value if x is NaN. It is equivalent to

(fpclassify (x) == FP_NAN)

Another set of floating-point classification functions was provided by BSD. The GNU C library also supports these functions; however, we recommend that you use the ISO C99 macros in new code. Those are standard and will be available more widely. Also, since they are macros, you do not have to worry about the type of their argument.

Function: int isinf (double x)

Function: int isinff (float x)

Function: int isinfl (long double x)

This function returns -1 if x represents negative infinity, 1 if x represents positive infinity, and 0 otherwise.

Function: int isnan (double x)

Function: int isnanf (float x)

Function: int isnanl (long double x)

This function returns a nonzero value if x is a "not a number" value, and zero otherwise.

Note: The isnan macro defined by ISO C99 overrides the BSD function. This is normally not a problem, because the two routines behave identically. However, if you really need to get the BSD function for some reason, you can write

(isnan) (x)

Function: int finite (double x)

Function: int finitef (float x)

Function: int finitel (long double x)

This function returns a nonzero value if x is finite or a "not a number" value, and zero otherwise.

Portability Note: The functions listed in this section are BSD extensions.

20.5 Errors in Floating-Point Calculations

20.5.1 FP Exceptions

The IEEE 754 standard defines five exceptions that can occur during a calculation. Each corresponds to a particular sort of error, such as overflow.

When exceptions occur (when exceptions are raised, in the language of the standard), one of two things can happen. By default the exception is simply noted in the floating-point status word, and the program continues as if nothing had happened. The operation produces a default value, which depends on the exception (see the table below). Your program can check the status word to find out which exceptions happened.

Alternatively, you can enable traps for exceptions. In that case, when an exception is raised, your program will receive the SIGFPE signal. The default action for this signal is to terminate the program. See section 24. Signal Handling, for how you can change the effect of the signal.

In the System V math library, the user-defined function matherr is called when certain exceptions occur inside math library functions. However, the Unix98 standard deprecates this interface. We support it for historical compatibility, but recommend that you do not use it in new programs.

The exceptions defined in IEEE 754 are:

`Invalid Operation'

This exception is raised if the given operands are invalid for the operation to be performed. Examples are (see IEEE 754, section 7):

1. Addition or subtraction: . (But ).
2. Multiplication: .
3. Division: or .
4. Remainder: REM , where is zero or is infinite.
5. Square root if the operand is less then zero. More generally, any mathematical function evaluated outside its domain produces this exception.
6. Conversion of a floating-point number to an integer or decimal string, when the number cannot be represented in the target format (due to overflow, infinity, or NaN).
7. Conversion of an unrecognizable input string.
8. Comparison via predicates involving or , when one or other of the operands is NaN. You can prevent this exception by using the unordered comparison functions instead; see 20.8.6 Floating-Point Comparison Functions.

If the exception does not trap, the result of the operation is NaN.

`Division by Zero'

This exception is raised when a finite nonzero number is divided by zero. If no trap occurs the result is either or , depending on the signs of the operands.

`Overflow'

This exception is raised whenever the result cannot be represented as a finite value in the precision format of the destination. If no trap occurs the result depends on the sign of the intermediate result and the current rounding mode (IEEE 754, section 7.3):

1. Round to nearest carries all overflows to with the sign of the intermediate result.
2. Round toward carries all overflows to the largest representable finite number with the sign of the intermediate result.
3. Round toward carries positive overflows to the largest representable finite number and negative overflows to .

4. Round toward carries negative overflows to the most negative representable finite number and positive overflows to .

Whenever the overflow exception is raised, the inexact exception is also raised.

`Underflow'

The underflow exception is raised when an intermediate result is too small to be calculated accurately, or if the operation's result rounded to the destination precision is too small to be normalized.

When no trap is installed for the underflow exception, underflow is signaled (via the underflow flag) only when both tininess and loss of accuracy have been detected. If no trap handler is installed the operation continues with an imprecise small value, or zero if the destination precision cannot hold the small exact result.

`Inexact'

This exception is signalled if a rounded result is not exact (such as when calculating the square root of two) or a result overflows without an overflow trap.

20.5.2 Infinity and NaN

IEEE 754 floating point numbers can represent positive or negative infinity, and NaN (not a number). These three values arise from calculations whose result is undefined or cannot be represented accurately. You can also deliberately set a floating-point variable to any of them, which is sometimes useful. Some examples of calculations that produce infinity or NaN:

When a calculation produces any of these values, an exception also occurs; see 20.5.1 FP Exceptions.

The basic operations and math functions all accept infinity and NaN and produce sensible output. Infinities propagate through calculations as one would expect: for example, , , atan . NaN, on the other hand, infects any calculation that involves it. Unless the calculation would produce the same result no matter what real value replaced NaN, the result is NaN.

In comparison operations, positive infinity is larger than all values except itself and NaN, and negative infinity is smaller than all values except itself and NaN. NaN is unordered: it is not equal to, greater than, or less than anything, including itself. x == x is false if the value of x is NaN. You can use this to test whether a value is NaN or not, but the recommended way to test for NaN is with the isnan function (see section 20.4 Floating-Point Number Classification Functions). In addition, <, >, <=, and >= will raise an exception when applied to NaNs.

`math.h' defines macros that allow you to explicitly set a variable to infinity or NaN.

Macro: float INFINITY

An expression representing positive infinity. It is equal to the value produced by mathematical operations like 1.0 / 0.0. -INFINITY represents negative infinity.

You can test whether a floating-point value is infinite by comparing it to this macro. However, this is not recommended; you should use the isfinite macro instead. See section 20.4 Floating-Point Number Classification Functions.

This macro was introduced in the ISO C99 standard.

Macro: float NAN

An expression representing a value which is "not a number". This macro is a GNU extension, available only on machines that support the "not a number" value--that is to say, on all machines that support IEEE floating point.

You can steaibc_20.html#SEC410">20.5.2 Infinity and NaN)

FP_ZERO

The value of x is zero. In floating-point formats like IEEE 754, where zero can be signed, this value is also returned if x is negative zero.

FP_SUBNORMAL

Numbers whose absolute value is too small to be represented in the normal format are represented in an alternate, denormalized format (see section A.5.3.1 Floating Point Representation Concepts). This format is less precise but can represent values closer to zero. fpclassify returns this value for values of x in this alternate format.

FP_NORMAL

This value is returned for all other values of x. It indicates that there is nothing special about the number.

fpclassify is most useful if more than one property of a number must be tested. There are more specific macros which only test one property at a time. Generally these macros execute faster than fpclassify, since there is special hardware support for them. You should therefore use the specific macros whenever possible.

Macro: int isfinite (float-type x)

This macro returns a nonzero value if x is finite: not plus or minus infinity, and not NaN. It is equivalent to

(fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)

isfinite is implemented as a macro which accepts any floating-point type.

Macro: int isnormal (float-type x)

This macro returns a nonzero value if x is finite and normalized. It is equivalent to

(fpclassify (x) == FP_NORMAL)

Macro: int isnan (float-type x)

This macro returns a nonzero value if x is NaN. It is equivalent to

(fpclassify (x) == FP_NAN)

Another set of floating-point classification functions was provided by BSD. The GNU C library also supports these functions; however, we recommend that you use the ISO C99 macros in new code. Those are standard and will be available more widely. Also, since they are macros, you do not have to worry about the type of their argument.

Function: int isinf (double x)

Function: int isinff (float x)

Function: int isinfl (long double x)

This function returns -1 if x represents negative infinity, 1 if x represents positive infinity, and 0 otherwise.

Function: int isnan (double x)

Function: int isnanf (float x)

Function: int isnanl (long double x)

This function returns a nonzero value if x is a "not a number" value, and zero otherwise.

Note: The isnan macro defined by ISO C99 overrides the BSD function. This is normally not a problem, because the two routines behave identically. However, if you really need to get the BSD function for some reason, you can write

(isnan) (x)

Function: int finite (double x)

Function: int finitef (float x)

Function: int finitel (long double x)

This function returns a nonzero value if x is finite or a "not a number" value, and zero otherwise.

Portability Note: The functions listed in this section are BSD extensions.

20.5 Errors in Floating-Point Calculations

20.5.1 FP Exceptions

The IEEE 754 standard defines five exceptions that can occur during a calculation. Each corresponds to a particular sort of error, such as overflow.

When exceptions occur (when exceptions are raised, in the language of the standard), one of two things can happen. By default the exception is simply noted in the floating-point status word, and the program continues as if nothing had happened. The operation produces a default value, which depends on the exception (see the table below). Your program can check the status word to find out which exceptions happened.

Alternatively, you can enable traps for exceptions. In that case, when an exception is raised, your program will receive the SIGFPE signal. The default action for this signal is to terminate the program. See section 24. Signal Handling, for how you can change the effect of the signal.

In the System V math library, the user-defined function matherr is called when certain exceptions occur inside math library functions. However, the Unix98 standard deprecates this interface. We support it for historical compatibility, but recommend that you do not use it in new programs.

The exceptions defined in IEEE 754 are:

`Invalid Operation'

This exception is raised if the given operands are invalid for the operation to be performed. Examples are (see IEEE 754, section 7):

1. Addition or subtraction: . (But ).
2. Multiplication: .
3. Division: or .
4. Remainder: REM , where is zero or is infinite.
5. Square root if the operand is less then zero. More generally, any mathematical function evaluated outside its domain produces this exception.
6. Conversion of a floating-point number to an integer or decimal string, when the number cannot be represented in the target format (due to overflow, infinity, or NaN).
7. Conversion of an unrecognizable input string.
8. Comparison via predicates involving or , when one or other of the operands is NaN. You can prevent this exception by using the unordered comparison functions instead; see 20.8.6 Floating-Point Comparison Functions.

If the exception does not trap, the result of the operation is NaN.

`Division by Zero'

This exception is raised when a finite nonzero number is divided by zero. If no trap occurs the result is either or , depending on the signs of the operands.

`Overflow'

This exception is raised whenever the result cannot be represented as a finite value in the precision format of the destination. If no trap occurs the result depends on the sign of the intermediate result and the current rounding mode (IEEE 754, section 7.3):

1. Round to nearest carries all overflows to with the sign of the intermediate result.
2. Round toward carries all overflows to the largest representable finite number with the sign of the intermediate result.
3. Round toward carries positive overflows to the largest representable finite number and negative overflows to .

4. Round toward carries negative overflows to the most negative representable finite number and positive overflows to .

Whenever the overflow exception is raised, the inexact exception is also raised.

`Underflow'

The underflow exception is raised when an intermediate result is too small to be calculated accurately, or if the operation's result rounded to the destination precision is too small to be normalized.

When no trap is installed for the underflow exception, underflow is signaled (via the underflow flag) only when both tininess and loss of accuracy have been detected. If no trap handler is installed the operation continues with an imprecise small value, or zero if the destination precision cannot hold the small exact result.

`Inexact'

This exception is signalled if a rounded result is not exact (such as when calculating the square root of two) or a result overflows without an overflow trap.

20.5.2 Infinity and NaN

IEEE 754 floating point numbers can represent positive or negative infinity, and NaN (not a number). These three values arise from calculations whose result is undefined or cannot be represented accurately. You can also deliberately set a floating-point variable to any of them, which is sometimes useful. Some examples of calculations that produce infinity or NaN:

When a calculation produces any of these values, an exception also occurs; see 20.5.1 FP Exceptions.

The basic operations and math functions all accept infinity and NaN and produce sensible output. Infinities propagate through calculations as one would expect: for example, , , atan . NaN, on the other hand, infects any calculation that involves it. Unless the calculation would produce the same result no matter what real value replaced NaN, the result is NaN.

In comparison operations, positive infinity is larger than all values except itself and NaN, and negative infinity is smaller than all values except itself and NaN. NaN is unordered: it is not equal to, greater than, or less than anything, including itself. x == x is false if the value of x is NaN. You can use this to test whether a value is NaN or not, but the recommended way to test for NaN is with the isnan function (see section 20.4 Floating-Point Number Classification Functions). In addition, <, >, <=, and >= will raise an exception when applied to NaNs.

`math.h' defines macros that allow you to explicitly set a variable to infinity or NaN.

Macro: float INFINITY

An expression representing positive infinity. It is equal to the value produced by mathematical operations like 1.0 / 0.0. -INFINITY represents negative infinity.

You can test whether a floating-point value is infinite by comparing it to this macro. However, this is not recommended; you should use the isfinite macro instead. See section 20.4 Floating-Point Number Classification Functions.

This macro was introduced in the ISO C99 standard.

Macro: float NAN

An expression representing a value which is "not a number". This macro is a GNU extension, available only on machines that support the "not a number" value--that is to say, on all machines that support IEEE floating point.

You can steaibc_20.html#SEC410">20.5.2 Infinity and NaN)

FP_ZERO

The value of x is zero. In floating-point formats like IEEE 754, where zero can be signed, this value is also returned if x is negative zero.

FP_SUBNORMAL

Numbers whose absolute value is too small to be represented in the normal format are represented in an alternate, denormalized format (see section A.5.3.1 Floating Point Representation Concepts). This format is less precise but can represent values closer to zero. fpclassify returns this value for values of x in this alternate format.

FP_NORMAL

This value is returned for all other values of x. It indicates that there is nothing special about the number.

fpclassify is most useful if more than one property of a number must be tested. There are more specific macros which only test one property at a time. Generally these macros execute faster than fpclassify, since there is special hardware support for them. You should therefore use the specific macros whenever possible.

Macro: int isfinite (float-type x)

This macro returns a nonzero value if x is finite: not plus or minus infinity, and not NaN. It is equivalent to

(fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)

isfinite is implemented as a macro which accepts any floating-point type.

Macro: int isnormal (float-type x)

This macro returns a nonzero value if x is finite and normalized. It is equivalent to

(fpclassify (x) == FP_NORMAL)

Macro: int isnan (float-type x)

This macro returns a nonzero value if x is NaN. It is equivalent to

(fpclassify (x) == FP_NAN)

Another set of floating-point classification functions was provided by BSD. The GNU C library also supports these functions; however, we recommend that you use the ISO C99 macros in new code. Those are standard and will be available more widely. Also, since they are macros, you do not have to worry about the type of their argument.

Function: int isinf (double x)

Function: int isinff (float x)

Function: int isinfl (long double x)

This function returns -1 if x represents negative infinity, 1 if x represents positive infinity, and 0 otherwise.

Function: int isnan (double x)

Function: int isnanf (float x)

Function: int isnanl (long double x)

This function returns a nonzero value if x is a "not a number" value, and zero otherwise.

Note: The isnan macro defined by ISO C99 overrides the BSD function. This is normally not a problem, because the two routines behave identically. However, if you really need to get the BSD function for some reason, you can write

(isnan) (x)

Function: int finite (double x)

Function: int finitef (float x)

Function: int finitel (long double x)

This function returns a nonzero value if x is finite or a "not a number" value, and zero otherwise.

Portability Note: The functions listed in this section are BSD extensions.

20.5 Errors in Floating-Point Calculations

20.5.1 FP Exceptions

The IEEE 754 standard defines five exceptions that can occur during a calculation. Each corresponds to a particular sort of error, such as overflow.

When exceptions occur (when exceptions are raised, in the language of the standard), one of two things can happen. By default the exception is simply noted in the floating-point status word, and the program continues as if nothing had happened. The operation produces a default value, which depends on the exception (see the table below). Your program can check the status word to find out which exceptions happened.

Alternatively, you can enable traps for exceptions. In that case, when an exception is raised, your program will receive the SIGFPE signal. The default action for this signal is to terminate the program. See section 24. Signal Handling, for how you can change the effect of the signal.

In the System V math library, the user-defined function matherr is called when certain exceptions occur inside math library functions. However, the Unix98 standard deprecates this interface. We support it for historical compatibility, but recommend that you do not use it in new programs.

The exceptions defined in IEEE 754 are:

`Invalid Operation'

This exception is raised if the given operands are invalid for the operation to be performed. Examples are (see IEEE 754, section 7):

1. Addition or subtraction: . (But ).
2. Multiplication: .
3. Division: or .
4. Remainder: REM , where is zero or is infinite.
5. Square root if the operand is less then zero. More generally, any mathematical function evaluated outside its domain produces this exception.
6. Conversion of a floating-point number to an integer or decimal string, when the number cannot be represented in the target format (due to overflow, infinity, or NaN).
7. Conversion of an unrecognizable input string.
8. Comparison via predicates involving or , when one or other of the operands is NaN. You can prevent this exception by using the unordered comparison functions instead; see 20.8.6 Floating-Point Comparison Functions.

If the exception does not trap, the result of the operation is NaN.

`Division by Zero'

This exception is raised when a finite nonzero number is divided by zero. If no trap occurs the result is either or , depending on the signs of the operands.

`Overflow'

This exception is raised whenever the result cannot be represented as a finite value in the precision format of the destination. If no trap occurs the result depends on the sign of the intermediate result and the current rounding mode (IEEE 754, section 7.3):

1. Round to nearest carries all overflows to with the sign of the intermediate result.
2. Round toward carries all overflows to the largest representable finite number with the sign of the intermediate result.
3. Round toward carries positive overflows to the largest representable finite number and negative overflows to .

4. Round toward carries negative overflows to the most negative representable finite number and positive overflows to .

Whenever the overflow exception is raised, the inexact exception is also raised.

`Underflow'

The underflow exception is raised when an intermediate result is too small to be calculated accurately, or if the operation's result rounded to the destination precision is too small to be normalized.

When no trap is installed for the underflow exception, underflow is signaled (via the underflow flag) only when both tininess and loss of accuracy have been detected. If no trap handler is installed the operation continues with an imprecise small value, or zero if the destination precision cannot hold the small exact result.

`Inexact'

This exception is signalled if a rounded result is not exact (such as when calculating the square root of two) or a result overflows without an overflow trap.

20.5.2 Infinity and NaN

IEEE 754 floating point numbers can represent positive or negative infinity, and NaN (not a number). These three values arise from calculations whose result is undefined or cannot be represented accurately. You can also deliberately set a floating-point variable to any of them, which is sometimes useful. Some examples of calculations that produce infinity or NaN:

When a calculation produces any of these values, an exception also occurs; see 20.5.1 FP Exceptions.

The basic operations and math functions all accept infinity and NaN and produce sensible output. Infinities propagate through calculations as one would expect: for example, , , atan . NaN, on the other hand, infects any calculation that involves it. Unless the calculation would produce the same result no matter what real value replaced NaN, the result is NaN.

In comparison operations, positive infinity is larger than all values except itself and NaN, and negative infinity is smaller than all values except itself and NaN. NaN is unordered: it is not equal to, greater than, or less than anything, including itself. x == x is false if the value of x is NaN. You can use this to test whether a value is NaN or not, but the recommended way to test for NaN is with the isnan function (see section 20.4 Floating-Point Number Classification Functions). In addition, <, >, <=, and >= will raise an exception when applied to NaNs.

`math.h' defines macros that allow you to explicitly set a variable to infinity or NaN.

Macro: float INFINITY

An expression representing positive infinity. It is equal to the value produced by mathematical operations like 1.0 / 0.0. -INFINITY represents negative infinity.

You can test whether a floating-point value is infinite by comparing it to this macro. However, this is not recommended; you should use the isfinite macro instead. See section 20.4 Floating-Point Number Classification Functions.

This macro was introduced in the ISO C99 standard.

Macro: float NAN

An expression representing a value which is "not a number". This macro is a GNU extension, available only on machines that support the "not a number" value--that is to say, on all machines that support IEEE floating point.

You can steaibc_20.html#SEC410">20.5.2 Infinity and NaN)

FP_ZERO

The value of x is zero. In floating-point formats like IEEE 754, where zero can be signed, this value is also returned if x is negative zero.

FP_SUBNORMAL

Numbers whose absolute value is too small to be represented in the normal format are represented in an alternate, denormalized format (see section A.5.3.1 Floating Point Representation Concepts). This format is less precise but can represent values closer to zero. fpclassify returns this value for values of x in this alternate format.

FP_NORMAL

This value is returned for all other values of x. It indicates that there is nothing special about the number.

fpclassify is most useful if more than one property of a number must be tested. There are more specific macros which only test one property at a time. Generally these macros execute faster than fpclassify, since there is special hardware support for them. You should therefore use the specific macros whenever possible.

Macro: int isfinite (float-type x)

This macro returns a nonzero value if x is finite: not plus or minus infinity, and not NaN. It is equivalent to

(fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)

isfinite is implemented as a macro which accepts any floating-point type.

Macro: int isnormal (float-type x)

This macro returns a nonzero value if x is finite and normalized. It is equivalent to

(fpclassify (x) == FP_NORMAL)

Macro: int isnan (float-type x)

This macro returns a nonzero value if x is NaN. It is equivalent to

(fpclassify (x) == FP_NAN)

Another set of floating-point classification functions was provided by BSD. The GNU C library also supports these functions; however, we recommend that you use the ISO C99 macros in new code. Those are standard and will be available more widely. Also, since they are macros, you do not have to worry about the type of their argument.

Function: int isinf (double x)

Function: int isinff (float x)

Function: int isinfl (long double x)

This function returns -1 if x represents negative infinity, 1 if x represents positive infinity, and 0 otherwise.

Function: int isnan (double x)

Function: int isnanf (float x)

Function: int isnanl (long double x)

This function returns a nonzero value if x is a "not a number" value, and zero otherwise.

Note: The isnan macro defined by ISO C99 overrides the BSD function. This is normally not a problem, because the two routines behave identically. However, if you really need to get the BSD function for some reason, you can write

(isnan) (x)

Function: int finite (double x)

Function: int finitef (float x)

Function: int finitel (long double x)

This function returns a nonzero value if x is finite or a "not a number" value, and zero otherwise.

Portability Note: The functions listed in this section are BSD extensions.

20.5 Errors in Floating-Point Calculations