FPGETMASK(3) BSD Programmer's Manual FPGETMASK(3)NAME
fpgetmask, fpgetround, fpgetsticky, fpsetmask, fpsetround, fpsetsticky -
manipulate IEEE floating point exceptions and modes
SYNOPSIS
#include <ieeefp.h>
fp_except
fpgetmask(void);
fp_rnd
fpgetround(void);
fp_except
fpgetsticky(void);
fp_except
fpsetmask(fp_except);
fp_rnd
fpsetround(fp_rnd);
fp_except
fpsetsticky(fp_except);
DESCRIPTION
These functions provide a means to manipulate IEEE 754 floating point ex-
ceptions and modes. The IEEE standard for floating point arithmetic de-
scribes a number of exceptions and rounding modes; check the standard for
details.
The IEEE 754 exceptions are handled using an integral type named
fp_except, which may have any of five named bits set:
FP_X_IMP The result of a floating point operation was imprecise; the
format could not represent the result exactly. Since many
floating point numbers can't be represented exactly in the
IEEE format (or sometimes any finite format), this exception
is a frequent one.
FP_X_INV An invalid floating point operation occurred. There are a va-
riety of ways to provoke this exception, some of them imple-
mentation-dependent. Typically the floating point registers
were manipulated incorrectly, or arithmetic on special values
was attempted incorrectly, such as multiplying infinity by ze-
ro.
FP_X_DZ A floating point operation divided by zero.
FP_X_OFL The result of a floating point operation couldn't be stored
accurately because its magnitude was too great to be repre-
sented.
FP_X_UFL The result of a floating point operation couldn't be stored
accurately because its magnitude was too small to be repre-
sented.
Rounding modes are handled using an integral type named fp_rnd. When a
floating point result can't be represented exactly because the format
doesn't have enough (perhaps infinite) bits of precision, one of four
things will be done to the result, depending on the rounding mode:
FP_RM Round toward negative infinity.
FP_RN Round to nearest or even.
FP_RP Round toward positive infinity.
FP_RZ Truncate toward zero.
By default, all IEEE exceptions are ``masked''; that is to say, special
values such as Inf (infinity) or NaN (not a number) are produced. The
only portable way in which a program can observe and manipulate excep-
tions and set rounding modes is with the following functions.
The fpsetmask() function is the only portable way to enable floating
point exceptions. If you enable an exception with fpsetmask() and a
floating point operation causes that exception, your program will receive
a SIGFPE signal (see sigaction(2)). Bits that are set enable exceptions,
while cleared bits disable exceptions. The fpsetmask() function returns
the previous exception mask. The fpgetmask() function returns a mask of
the currently enabled floating point exceptions without altering them.
The fpgetsticky() function returns the mask of `sticky' floating point
status bits. When an operation fails, regardless of whether an exception
is enabled, the particular failure is marked in the sticky bit mask using
the same bit as the corresponding exception. Thus you can find out how
an Inf or a NaN was generated, or how an exception was generated. You
must clear the sticky bits after every failed operation in order to get a
reliable report for the next failure. The fpsetsticky() function sets
the `sticky' floating point status bits, and returns the previous float-
ing point status bits.
The fpgetround() function returns the current rounding mode. The
fpsetround() function sets the rounding mode and returns the previous
rounding mode.
STANDARDS
The IEEE functions were written to conform to the description in the Sys-
tem V Release 4 API.
BUGS
Although every modern architecture implements IEEE 754 arithmetic, not
all of the old ones do. Thus these functions are technically machine-de-
pendent.
BSDI BSD/OS October 25, 1995 2