.TH FPCLASSIFY 3 "April 2010" "NEWLIB" "NEWLIB"
.SH NAME

1.31 `fpclassify', `isfinite', `isinf', `isnan', and `isnormal'-floating-point classification macros; `finite', `finitef', `isinf', `isinff', `isnan', `isnanf'-test for exceptional numbers

.SH SYNOPSIS
     [C99 standard macros:]
     #include <math.h>
     int fpclassify(real-floating X);
     int isfinite(real-floating X);
     int isinf(real-floating X);
     int isnan(real-floating X);
     int isnormal(real-floating X);

     [Archaic SUSv2 functions:]
     #include <ieeefp.h>
     int isnan(double ARG);
     int isinf(double ARG);
     int finite(double ARG);
     int isnanf(float ARG);
     int isinff(float ARG);
     int finitef(float ARG);
.SH DESCRIPTION
`fpclassify', `isfinite', `isinf', `isnan', and `isnormal' are macros
defined for use in classifying floating-point numbers.  This is a help
because of special "values" like NaN and infinities.  In the synopses
shown, "real-floating" indicates that the argument is an expression of
real floating type.  These function-like macros are C99 and
POSIX-compliant, and should be used instead of the now-archaic SUSv2
functions.

   The `fpclassify' macro classifies its argument value as NaN,
infinite, normal, subnormal, zero, or into another
implementation-defined category.  First, an argument represented in a
format wider than its semantic type is converted to its semantic type.
Then classification is based on the type of the argument.  The
`fpclassify' macro returns the value of the number classification macro
appropriate to the value of its argument:

`FP_INFINITE'
     X is either plus or minus infinity;

`FP_NAN'
     X is "Not A Number" (plus or minus);

`FP_NORMAL'
     X is a "normal" number (i.e. is none of the other special forms);

`FP_SUBNORMAL'
     X is too small be stored as a regular normalized number (i.e. loss
     of precision is likely); or

`FP_ZERO'
     X is 0 (either plus or minus).

   The "`is'" set of macros provide a useful set of shorthand ways for
classifying floating-point numbers, providing the following equivalent
relations:

``isfinite'(X)'
     returns non-zero if X is finite.  (It is equivalent to
     (`fpclassify'(X) != FP_INFINITE  &&  `fpclassify'(X) != FP_NAN).)

``isinf'(X)'
     returns non-zero if X is infinite.  (It is equivalent to
     (`fpclassify'(X) == FP_INFINITE).)

``isnan'(X)'
     returns non-zero if X is NaN.  (It is equivalent to
     (`fpclassify'(X) == FP_NAN).)

``isnormal'(X)'
     returns non-zero if X is normal.  (It is equivalent to
     (`fpclassify'(X) == FP_NORMAL).)

   The archaic SUSv2 functions provide information on the floating-point
argument supplied.

   There are five major number formats ("exponent" referring to the
biased exponent in the binary-encoded number):
`zero'
     A number which contains all zero bits, excluding the sign bit.

`subnormal'
     A number with a zero exponent but a nonzero fraction.

`normal'
     A number with an exponent and a fraction.

`infinity'
     A number with an all 1's exponent and a zero fraction.

`NAN'
     A number with an all 1's exponent and a nonzero fraction.


   `isnan' returns 1 if the argument is a nan. `isinf' returns 1 if the
argument is infinity.  `finite' returns 1 if the argument is zero,
subnormal or normal.  The `isnanf', `isinff' and `finitef' functions
perform the same operations as their `isnan', `isinf' and `finite'
counterparts, but on single-precision floating-point numbers.

   It should be noted that the C99 standard dictates that `isnan' and
`isinf' are macros that operate on multiple types of floating-point.
The SUSv2 standard declares `isnan' as a function taking double.
Newlib has decided to declare them both as macros in math.h and as
functions in ieeefp.h to maintain backward compatibility.

.SH RETURNS
The fpclassify macro returns the value corresponding to the appropriate
FP_ macro.
The isfinite macro returns nonzero if X is finite, else 0.
The isinf macro returns nonzero if X is infinite, else 0.
The isnan macro returns nonzero if X is an NaN, else 0.
The isnormal macro returns nonzero if X has a normal value, else 0.

.SH PORTABILITY
math.h macros are C99, POSIX.

   ieeefp.h funtions are outdated and should be avoided.

.SH "SEE ALSO"
.B fpclassify
is part of the
.B 
library.
The full documentation for
.B 
is maintained as a Texinfo manual.  If 
.B info
and
.B 
are properly installed at your site, the command
.IP
.B info 
.PP
will give you access to the complete manual.
