This chapter describes IEEE floating point exceptions and shows how to detect, locate, and handle them.

The floating point environment provided by the Sun Studio compilers and the Solaris OS on SPARC® based systems and x86 based systems supports all of the exception handling facilities required by the IEEE standard as well as many of the recommended optional facilities. One objective of these facilities is explained in the IEEE 854 Standard (IEEE 854, page 18):

... to minimize for users the complications arising from exceptional conditions. The arithmetic system is intended to continue to function on a computation as long as possible, handling unusual situations with reasonable default responses, including setting appropriate flags.

To achieve this objective, the standards specify default results for exceptional operations and require that an implementation provide status flags, which can be sensed, set, or cleared by a user, to indicate that exceptions have occurred. The standards also recommend that an implementation provide a means for a program to trap (i.e., interrupt normal control flow) when an exception occurs. The program can optionally supply a trap handler that handles the exception in an appropriate manner, for example by providing an alternate result for the exceptional operation and resuming execution. This chapter lists the exceptions defined by IEEE 754 along with their default results and describes the features of the floating point environment that support status flags, trapping, and exception handling. (Some information in this chapter pertains specifically to the Solaris 10 OS and not to earlier versions of the Solaris OS.)

4.1 What Is an Exception?

It is hard to define exceptions. To quote W. Kahan,

An arithmetic exception arises when an attempted atomic arithmetic operation has no result that would be acceptable universally. The meanings of atomic and acceptable vary with time and place. (See Handling Arithmetic Exceptions by W. Kahan.)

For example, an exception arises when a program attempts to take the square root of a negative number. (This example is one case of an invalidoperation exception.) When such an exception occurs, the system responds in one of two ways:

If the exception's trap is disabled (the default case), the system records the fact that the exception occurred and continues executing the program using the default result specified by IEEE 754 for the excepting operation.

If the exception's trap is enabled, the system generates a SIGFPE signal. If the program has installed a SIGFPE signal handler, the system transfers control to that handler; otherwise, the program aborts.

IEEE 754 defines five basic types of floating point exceptions: invalid operation, division by zero, overflow, underflow and inexact. The first three (invalid, division, and overflow) are sometimes collectively called common exceptions. These exceptions can seldom be ignored when they occur. ieee_handler(3m) gives an easy way to trap on common exceptions only. The other two exceptions (underflow and inexact) are seen more often--in fact, most floating point operations incur the inexact exception--and they can usually, though not always, be safely ignored.

TABLE 4-1 condenses information found in IEEE Standard 754. It describes the five floating point exceptions and the default response of an IEEE arithmetic environment when these exceptions are raised.

TABLE 4-1 IEEE Floating Point Exceptions

IEEE

Exception

Reason Why This Arises

Example

Default Result When

Trap is Disabled

Invalid operation

An operand is invalid for the operation about to be performed.

(On x86, this exception is also raised when the floating point stack underflows or overflows, though that is not part of the IEEE standard.)

0 ×

0 ⁄ 0

⁄

x REM 0

Square root of negative operand

Any operation with a signaling

NaN operand

Unordered comparison

(see note 1)

Invalid conversion (see note 2)

Quiet NaN

Division by zero

An exact infinite result is produced by an operation on finite operands.

x ⁄ 0 for finite, nonzero x

log(0)

Correctly signed infinity

Overflow

The correctly rounded result would be larger in magnitude than the largest finite number representable in the destination format (i.e., the exponent range is exceeded).

Double precision:

DBL_MAX + 1.0e294

exp(709.8)

Single precision:

(float)DBL_MAX

FLT_MAX + 1.0e32

expf(88.8)

Depends on rounding mode (RM), and the sign of the intermediate result:

RM + -

RN + -

RZ +max -max

R- +max -

R+ + -max

Underflow

Either the exact result or the correctly rounded result would be smaller in magnitude than the smallest normal number representable in the destination format (see note 3).

Double precision:

nextafter(min_normal,-)

nextafter(min_subnormal,-)

DBL_MIN ⁄3.0

exp(-708.5)

Single precision:

(float)DBL_MIN

nextafterf(FLT_MIN, -)

expf(-87.4)

Subnormal or zero

Inexact

The rounded result of a valid operation is different from the infinitely precise result. (Most floating point operations raise this exception.)

2.0 / 3.0

(float)1.12345678

log(1.1)

DBL_MAX + DBL_MAX,
when no overflow trap

The result of the operation (rounded, overflowed, or underflowed)

4.1.1 Notes for Table 4-1

1. Unordered comparison: Any pair of floating point values can be compared, even if they are not of the same format. Four mutually exclusive relations are possible: less than, greater than, equal, or unordered. Unordered means that at least one of the operands is a NaN (not a number).

Every NaN compares "unordered" with everything, including itself. TABLE 4-2 shows which predicates cause the invalid operation exception when the relation is unordered.

TABLE 4-2 Unordered Comparisons

Predicates

Invalid Exception

math

c, c++

f95

(if unordered)

=

==

.EQ.

no

!=

.NE.

no

>

>

.GT.

yes

>=

.GE.

yes

<

<

.LT.

yes

<=

.LE.

yes

2. Invalid conversion: Attempt to convert NaN or infinity to an integer, or integer overflow on conversion from floating point format.

3. The smallest normal numbers representable in the IEEE single, double, and extended formats are 2-126, 2-1022, and 2-16382, respectively. See Chapter 2 for a description of the IEEE floating point formats.

The x86 floating point environment provides another exception not mentioned in the IEEE standards: the denormal operand exception. This exception is raised whenever a floating point operation is performed on a subnormal number.

Exceptions are prioritized in the following order: invalid (highest priority), overflow, division, underflow, inexact (lowest priority). On x86 based systems, the denormal operand exception has the lowest priority of all.

The only combinations of standard exceptions that can occur simultaneously in a single operation are overflow with inexact and underflow with inexact. On x86 based systems, the denormal operand exception can occur with any of the five standard exceptions. If trapping on overflow, underflow, and inexact is enabled, the overflow and underflow traps take precedence over the inexact trap; they all take precedence over a denormal operand trap on x86 based systems.

4.2 Detecting Exceptions

As required by the IEEE standard, the floating point environments on SPARC based systems and x86 based systems provide status flags that record the occurrence of floating point exceptions. A program can test these flags to determine which exceptions have occurred. The flags can also be explicitly set and cleared. The ieee_flags function provides one way to access these flags. In programs written in C or C++, the C99 floating point environment functions provide another.

On SPARC based systems, each exception has two flags associated with it, current and accrued. The current exception flags always indicate the exceptions raised by the last floating point instruction to complete execution. These flags are also accumulated (i.e., "or"-ed) into the accrued exception flags thereby providing a record of all untrapped exceptions that have occurred since the program began execution or since the accrued flags were last cleared by the program. (When a floating point instruction incurs a trapped exception, the current exception flag corresponding to the exception that caused the trap is set, but the accrued flags are unchanged.) Both the current and accrued exception flags are contained in the floating point status register, %fsr.

On x86 based systems, the floating point status word (SW) provides flags for accrued exceptions as well as flags for the status of the floating point stack. On x86 based systems that support SSE2 instructions, the MXCSR register contains flags that record accrued exceptions raised by those instructions.

4.2.1 ieee_flags(3m)

The syntax for a call to ieee_flags(3m) is:

i = ieee_flags(action, mode, in, out);

A program can test, set, or clear the accrued exception status flags using the ieee_flags function by supplying the string "exception" as the second argument. For example, to clear the overflow exception flag from Fortran, write:

character*8 out

call ieee_flags('clear', 'exception', 'overflow', out)

To determine whether an exception has occurred from C or C++, use:

i = ieee_flags("get", "exception", in, out);

When the action is "get", the string returned in out is:

"not available" -- if information on exceptions is not available

"" (an empty string) -- if there are no accrued exceptions or, in the case of x86, the denormal operand is the only accrued exception

the name of the exception named in the third argument, in, if that exception has occurred

otherwise, the name of the highest priority exception that has occurred.

For example, in the Fortran call:

character*8 out

i = ieee_flags('get', 'exception', 'division', out)

the string returned in out is "division" if the division-by-zero exception has occurred; otherwise it is the name of the highest priority exception that has occurred. Note that in is ignored unless it names a particular exception; for example, the argument "all" is ignored in the C call:

i = ieee_flags("get", "exception", "all", out);

Besides returning the name of an exception in out, ieee_flags returns an integer value that combines all of the exception flags currently raised. This value is the bitwise "or" of all the accrued exception flags, where each flag is represented by a single bit as shown in TABLE 4-3. The positions of the bits corresponding to each exception are given by the fp_exception_type values defined in the file sys/ieeefp.h. (Note that these bit positions are machine-dependent and need not be contiguous.)

TABLE 4-3 Exception Bits

Exception

Bit Position

Accrued Exception Bit

invalid

fp_invalid

i & (1 << fp_invalid)

overflow

fp_overflow

i & (1 << fp_overflow)

division

fp_division

i & (1 << fp_division)

underflow

fp_underflow

i & (1 << fp_underflow)

inexact

fp_inexact

i & (1 << fp_inexact)

denormalized

fp_denormalized

i & (1 << fp_denormalized) (x86 only)

This fragment of a C or C++ program shows one way to decode the return value.

/*

* Decode integer that describes all accrued exceptions.

* fp_inexact etc. are defined in <sys/ieeefp.h>

*/

char *out;

int invalid, division, overflow, underflow, inexact;

code = ieee_flags("get", "exception", "", &out);

printf ("out is %s, code is %d, in hex: 0x%08X\n",

out, code, code);

inexact = (code >> fp_inexact) & 0x1;

division = (code >> fp_division) & 0x1;

underflow = (code >> fp_underflow) & 0x1;

overflow = (code >> fp_overflow) & 0x1;

invalid = (code >> fp_invalid) & 0x1;

printf("%d %d %d %d %d \n", invalid, division, overflow,

underflow, inexact);

4.2.2 C99 Exception Flag Functions

C/C++ programs can test, set, and clear the floating point exception flags using the C99 floating point environment functions. The header file fenv.h defines five macros corresponding to the five standard exceptions: FE_INEXACT, FE_UNDERFLOW, FE_OVERFLOW, FE_DIVBYZERO, and FE_INVALID. It also defines the macro FE_ALL_EXCEPT to be the bitwise "or" of all five exception macros. These macros can be combined to test or clear any subset of the exception flags or raise any combination of exceptions. The following examples show the use of these macros with several of the C99 floating point environment functions; see the feclearexcept(3M) manual page for more information.

Note - For consistent behavior, do not use both the C99 floating point environment functions and extensions in libm and the ieee_flags and ieee_handler functions in libsunmath in the same program.

To clear all five exception flags:

feclearexcept(FE_ALL_EXCEPT);

To test whether the invalid operation or division by zero flags have been raised:

int i;

i = fetestexcept(FE_INVALID | FE_DIVBYZERO);

if (i & FE_INVALID)

/* invalid flag was raised */

else if (i & FE_DIVBYZERO)

/* division by zero flag was raised */

To simulate raising an overflow exception (note that this will provoke a trap if the overflow trap is enabled):

feraiseexcept(FE_OVERFLOW);

The fegetexceptflag and fesetexceptflag functions provide a way to save and restore a subset of the flags. The next example shows one way to use these functions.

fexcept_t flags;

/* save the underflow, overflow, and inexact flags */

fegetexceptflag(&flags, FE_UNDERFLOW | FE_OVERFLOW | FE_INEXACT);

/* clear these flags */

feclearexcept(FE_UNDERFLOW | FE_OVERFLOW | FE_INEXACT);

/* do a computation that can underflow or overflow */

...

/* check for underflow or overflow */

if (fetestexcept(FE_UNDERFLOW | FE_OVERFLOW) != 0) {

...

}

/* restore the underflow, overflow, and inexact flags */

fesetexceptflag(&flags, FE_UNDERFLOW | FE_OVERFLOW, | FE_INEXACT);

4.3 Locating an Exception

Often, programmers do not write programs with exceptions in mind, so when an exception is detected, the first question asked is: Where did the exception occur? One way to locate where an exception occurs is to test the exception flags at various points throughout a program, but to isolate an exception precisely by this approach can require many tests and carry a significant overhead.

An easier way to determine where an exception occurs is to enable its trap. When an exception whose trap is enabled occurs, the operating system notifies the program by sending a SIGFPE signal (see the signal(5) manual page). Thus, by enabling trapping for an exception, you can determine where the exception occurs either by running under a debugger and stopping on receipt of a SIGFPE signal or by establishing a SIGFPE handler that prints the address of the instruction where the exception occurred. Note that trapping must be enabled for an exception to generate a SIGFPE signal; when trapping is disabled and an exception occurs, the corresponding flag is set and execution continues with the default result specified in TABLE 4-1, but no signal is delivered.

4.3.1 Using the Debugger to Locate an Exception

This section gives examples showing how to use dbx to investigate the cause of a floating point exception and locate the instruction that raised it. Recall that in order to use the source-level debugging features of dbx, programs should be compiled with the -g flag. Refer to the Debugging a Program Withdbxmanual for more information.

Consider the following C program:

#include <stdio.h>

#include <math.h>

double sqrtm1(double x)

{

return sqrt(x) - 1.0;

}

int main(void)

{

double x, y;

x = -4.2;

y = sqrtm1(x);

printf("%g %g\n", x, y);

return 0;

}

Compiling and running this program produces:

-4.2 NaN

The appearance of a NaN in the output suggests that an invalid operation exception might have occurred. To determine whether this is the case, you can recompile with the -ftrap option to enable trapping on invalid operations and use dbx to run the program and stop when a SIGFPE signal is delivered. Alternatively, you can use dbx without recompiling the program by linking with a startup routine that enables the invalid operation trap or by manually enabling the trap.

4.3.1.1 Using dbx to Locate the Instruction Causing an Exception

The simplest way to locate the code that causes a floating point exception is to recompile with the -g and -ftrap flags and then use dbx to track down the location where the exception occurs. First, recompile the program as follows:

example% cc -g -ftrap=invalid ex.c -lm

Compiling with -g allows you to use the source-level debugging features of dbx. Specifying -ftrap=invalid causes the program to run with trapping enabled for invalid operation exceptions. Next, invoke dbx, issue the catchfpe command to stop when a SIGFPE is issued, and run the program. On SPARC based systems, the result resembles this:

example% dbx a.out

Reading a.out

... etc.

(dbx) catch fpe

(dbx) run

Running: a.out

(process id 2532)

signal FPE (invalid floating point operation) in __sqrt at 0xff36b3c4

0xff36b3c4: __sqrt+0x003c: be __sqrt+0x98

Current function is sqrtm1

6 return sqrt(x) - 1.0;

(dbx) print x

x = -4.2

(dbx)

The output shows that the exception occurred in the sqrtm1 function as a result of attempting to take the square root of a negative number.

You can also use dbx to identify the cause of an exception in code that has not been compiled with -g (such as a library routine). In this case, dbx will not be able to give the source file and line number, but it can show the instruction that raised the exception. Again, the first step is to recompile the main program with -ftrap:

example% cc -ftrap=invalid ex.c -lm

Now invoke dbx, use the catchfpe command, and run the program. When an invalid operation exception occurs, dbx stops at an instruction following the one that caused the exception. To find the instruction that caused the exception, disassemble several instructions and look for the last floating point instruction prior to the instruction at which dbx has stopped. On SPARC based systems, the result might resemble the following transcript.

example% dbx a.out

Reading a.out

... etc.

(dbx) catch fpe

(dbx) run

Running: a.out

(process id 2532)

signal FPE (invalid floating point operation) in __sqrt at 0xff2886f0

0xff2886f0: __sqrt+0x0050: btst %o5, %o2

(dbx) dis __sqrt+0x40/4

0xff2886e0: __sqrt+0x0040: sub %g1, %o2, %o4

0xff2886e4: __sqrt+0x0044: srlx %o4, 63, %o3

0xff2886e8: __sqrt+0x0048: xor %o3, 1, %o2

0xff2886ec: __sqrt+0x004c: fsqrtd %f2, %f0

(dbx) print $f2f3

$f2f3 = -4.2

(dbx)

The output shows that the exception was caused by an fsqrtd instruction. Examining the source register shows that the exception was a result of attempting to take the square root of a negative number.

On x86 based systems, because instructions do not have a fixed length, finding the correct address from which to disassemble the code might involve some trial and error. In this example, the exception occurs close to the beginning of a function, so we can disassemble from there. (Note that this output assumes the program has been compiled with the -xlibmil flag.) The following might be a typical result.

example% dbx a.out

Reading a.out

... etc.

(dbx) catch fpe

(dbx) run

Running: a.out

(process id 2532)

signal FPE (invalid floating point operation) in sqrtm1 at 0x80506bf

0x080506bf: sqrtm1+0x001f: fstpl 0xfffffff0(%ebp)

(dbx) dis sqrtm1+0x16/5

0x080506b6: sqrtm1+0x0016: pushl %eax

0x080506b7: sqrtm1+0x0017: fldl (%esp)

0x080506ba: sqrtm1+0x001a: fsqrt

0x080506bc: sqrtm1+0x001c: addl $0x00000008,%esp

0x080506bf: sqrtm1+0x001f: fstpl 0xfffffff0(%ebp)

(dbx) print $st0

$st0 = -4.20000000000000017763568394002504647e+00

(dbx)

The output reveals that the exception was caused by a fsqrt instruction; examination of the floating point registers reveals that the exception was a result of attempting to take the square root of a negative number.

4.3.1.2 Enabling Traps Without Recompilation

In the preceding examples, trapping on invalid operation exceptions was enabled by recompiling the main subprogram with the -ftrap flag. In some cases, recompiling the main program might not be possible, so you might need to resort to other means to enable trapping. There are several ways to do this.

When you are using dbx, you can enable traps manually by directly modifying the floating point status register. This can be somewhat tricky because the operating system does not enable the floating point unit until the first time it is used within a program, at which point the floating point state is initialized with all traps disabled. Thus, you cannot manually enable trapping until after the program has executed at least one floating point instruction. In our example, the floating point unit has already been accessed by the time the sqrtm1 function is called, so we can set a breakpoint on entry to that function, enable trapping on invalid operation exceptions, instruct dbx to stop on the receipt of a SIGFPE signal, and continue execution. On SPARC based systems, the steps are as follows (note the use of the assign command to modify the %fsr to enable trapping on invalid operation exceptions):

example% dbx a.out

Reading a.out

... etc.

(dbx) stop in sqrtm1

dbx: warning: 'sqrtm1' has no debugger info -- will trigger on first instruction

(2) stop in sqrtm1

(dbx) run

Running: a.out

(process id 23086)

stopped in sqrtm1 at 0x106d8

0x000106d8: sqrtm1 : save %sp, -0x70, %sp

(dbx) assign $fsr=0x08000000

dbx: warning: unknown language, 'c' assumed

(dbx) catch fpe

(dbx) cont

signal FPE (invalid floating point operation) in __sqrt at 0xff36b3c4

0xff36b3c4: __sqrt+0x003c: be __sqrt+0x98

(dbx)

On x86 based systems, the same process might look like this:

example% dbx a.out

Reading a.out

... etc.

(dbx) stop in sqrtm1

dbx: warning: 'sqrtm1' has no debugger info -- will trigger on first instruction

(2) stop in sqrtm1

(dbx) run

Running: a.out

(process id 25055)

stopped in sqrtm1 at 0x80506b0

0x080506b0: sqrtm1 : pushl %ebp

(dbx) assign $fctrl=0x137e

dbx: warning: unknown language, 'c' assumed

(dbx) catch fpe

(dbx) cont

signal FPE (invalid floating point operation) in sqrtm1 at 0x8050696

0x08050696: sqrtm1+0x0016: fstpl -16(%ebp)

(dbx)

In the example above, the assign command unmasks (that is, enables trapping on) the invalid operation exception in the floating point control word. If a program uses SSE2 instructions, you must unmask exceptions in the MXCSR register to enable trapping on exceptions raised by those instructions.

You can also enable trapping without recompiling the main program or using dbx by establishing an initialization routine that enables traps. (This might be useful, for example, if you want to abort the program when an exception occurs without running under a debugger.) There are two ways to establish such a routine.

If the object files and libraries that comprise the program are available, you can enable trapping by relinking the program with an appropriate initialization routine. First, create a C source file similar to the following:

#include <ieeefp.h>

#pragma init (trapinvalid)

void trapinvalid()

{

/* FP_X_INV et al are defined in ieeefp.h */

fpsetmask(FP_X_INV);

}

Now compile this file to create an object file and link the original program with this object file:

example% cc -c init.c

example% cc ex.o init.o -lm

example% a.out

Arithmetic Exception

If relinking is not possible but the program has been dynamically linked, you can enable trapping by using the shared object preloading facility of the runtime linker. To do this on SPARC based systems, create the same C source file as above, but compile as follows:

example% cc -Kpic -G -ztext init.c -o init.so -lc

Now to enable trapping, add the path name of the init.so object to the list of preloaded shared objects specified by the environment variable LD_PRELOAD, for example:

example% env LD_PRELOAD=./init.so a.out

Arithmetic Exception

See the Linker and Libraries Guide for more information about creating and preloading shared objects.

In principle, you can change the way any floating point control modes are initialized by preloading a shared object as described above. Note, though, that initialization routines in shared objects, whether preloaded or explicitly linked, are executed by the runtime linker before it passes control to the startup code that is part of the main executable. The startup code then establishes any nondefault modes selected via the -ftrap, -fround, -fns (SPARC), or -fprecision (x86) compiler flags, executes any initialization routines that are part of the main executable (including those that are statically linked), and finally passes control to the main program. Therefore, on SPARC (i) any floating point control modes established by initialization routines in shared objects, such as the traps enabled in the example above, will remain in effect throughout the execution of the program unless they are overridden; (ii) any nondefault modes selected via the compiler flags will override modes established by initialization routines in shared objects (but default modes selected via compiler flags will not override previously established modes); and (iii) any modes established either by initialization routines that are part of the main executable or by the main program itself will override both.

On x86 based systems, the situation is slightly more complicated. In general, the startup code automatically supplied by the compiler resets all floating point modes to the default by calling the __fpstart routine (found in the standard C library, libc) before establishing any nondefault modes selected by the -fround, -ftrap, or -fprecision flags and passing control to the main program. As a consequence, in order to enable trapping (or change any other default floating point mode) on x86 based systems by preloading a shared object with an initialization routine, you must override the __fpstart routine so that it does not reset the default floating point modes. The substitute __fpstart routine should still perform the rest of the initialization functions that the standard routine does, however. The following code shows one way to do this. This code assumes that the host platform is running the Solaris 10 OS.

#include <ieeefp.h>

#include <sys/sysi86.h>

#pragma init (trapinvalid)

void trapinvalid()

{

/* FP_X_INV et al are defined in ieeefp.h */

fpsetmask(FP_X_INV);

}

extern int __fltrounds(), __flt_rounds;

extern int _fp_hw, _sse_hw;

void __fpstart()

{

/* perform the same floating point initializations as

the standard __fpstart() function but leave all

floating point modes as is */

__flt_rounds = __fltrounds();

(void) sysi86(SI86FPHW, &_fp_hw);

/* set the following variable to 1 instead if the host

platform supports SSE2 instructions */

_sse_hw = 0;

}

4.3.2 Using a Signal Handler to Locate an Exception

The previous section presented several methods for enabling trapping at the outset of a program in order to locate the first occurrence of an exception. In contrast, you can isolate any particular occurrence of an exception by enabling trapping within the program itself. If you enable trapping but do not install a SIGFPE handler, the program will abort on the next occurrence of the trapped exception. Alternatively, if you install a SIGFPE handler, the next occurrence of the trapped exception will cause the system to transfer control to the handler, which can then print diagnostic information, such as the address of the instruction where the exception occurred, and either abort or resume execution. (In order to resume execution with any prospect for a meaningful outcome, the handler might need to supply a result for the exceptional operation as described in the next section.)

You can use ieee_handler to simultaneously enable trapping on any of the five IEEE floating point exceptions and either request that the program abort when the specified exception occurs or establish a SIGFPE handler. You can also install a SIGFPE handler using one of the lower-level functions sigfpe(3), signal(3c), or sigaction(2); however, these functions do not enable trapping as ieee_handler does. (Remember that a floating point exception triggers a SIGFPE signal only when its trap is enabled.)

4.3.2.1 ieee_handler (3m)

The syntax of a call to ieee_handler is:

i = ieee_handler(action, exception, handler)

The two input parameters action and exception are strings. The third input parameter, handler, is of type sigfpe_handler_type, which is defined in floatingpoint.h.

The three input parameters can take the following values:

Input Parameter

C or C++ Type

Possible Value

action

char *

get, set, clear

exception

char *

invalid, division, overflow,

underflow, inexact,

all, common

handler

sigfpe_handler_type

user-defined routine

SIGFPE_DEFAULT

SIGFPE_IGNORE

SIGFPE_ABORT

When the requested action is "set", ieee_handler establishes the handling function specified by handler for the exceptions named by exception. The handling function can be SIGFPE_DEFAULT or SIGFPE_IGNORE, both of which select the default IEEE behavior, SIGFPE_ABORT, which causes the program to abort on the occurrence of any of the named exceptions, or the address of a user-supplied subroutine, which causes that subroutine to be invoked (with the parameters described in the sigaction(2) manual page for a signal handler installed with the SA_SIGINFO flag set) when any of the named exceptions occurs. If the handler is SIGFPE_DEFAULT or SIGFPE_IGNORE, ieee_handler also disables trapping on the specified exceptions; for any other handler, ieee_handler enables trapping. (On x86 platforms, the floating point hardware traps whenever an exception's trap is enabled and its corresponding flag is raised. Therefore, to avoid spurious traps, a program should clear the flag for each specified exception before calling ieee_handler to enable trapping.)

When the requested action is "clear", ieee_handler revokes whatever handling function is currently installed for the specified exception and disables its trap. (This is the same as "set"ting SIGFPE_DEFAULT.) The third parameter is ignored when action is "clear".

For both the "set" and "clear" actions, ieee_handler returns 0 if the requested action is available and a nonzero value otherwise.

When the requested action is "get", ieee_handler returns the address of the handler currently installed for the specified exception (or SIGFPE_DEFAULT, if no handler is installed).

The following examples show a few code fragments illustrating the use of ieee_handler. This C code causes the program to abort on division by zero:

4.3.2.2 Reporting an Exception From a Signal Handler

When a SIGFPE handler installed via ieee_handler is invoked, the operating system provides additional information indicating the type of exception that occurred, the address of the instruction that caused it, and the contents of the machine's integer and floating point registers. The handler can examine this information and print a message identifying the exception and the location at which it occurred.

To access the information supplied by the system, declare the handler as follows. The remainder of this chapter presents sample code in C; see Appendix A for examples of SIGFPE handlers in Fortran.

#include <siginfo.h>

#include <ucontext.h>

void handler(int sig, siginfo_t *sip, ucontext_t *uap)

{

...

}

When the handler is invoked, the sig parameter contains the number of the signal that was sent. Signal numbers are defined in sys/signal.h; the SIGFPE signal number is 8.

The sip parameter points to a structure that records additional information about the signal. For a SIGFPE signal, the relevant members of this structure are sip->si_code and sip->si_addr (see sys/siginfo.h). The significance of these members depends on the system and on what event triggered the SIGFPE signal.

The sip->si_code member is one of the SIGFPE signal types listed in TABLE 4-4. (The tokens shown are defined in sys/machsig.h.)

TABLE 4-4 Types for Arithmetic Exceptions

SIGFPE Type

IEEE Type

FPE_INTDIV

FPE_INTOVF

FPE_FLTRES

inexact

FPE_FLTDIV

division

FPE_FLTUND

underflow

FPE_FLTINV

invalid

FPE_FLTOVF

overflow

As the table shows, each type of IEEE floating point exception has a corresponding SIGFPE signal type. Integer division by zero (FPE_INTDIV) and integer overflow (FPE_INTOVF) are also included among the SIGFPE types, but because they are not IEEE floating point exceptions you cannot install handlers for them via ieee_handler. (You can install handlers for these SIGFPE types via sigfpe(3); note, though, that integer overflow is ignored by default on all SPARC and x86 platforms. Special instructions can cause the delivery of a SIGFPE signal of type FPE_INTOVF, but Sun compilers do not generate these instructions.)

For a SIGFPE signal corresponding to an IEEE floating point exception, the sip->si_code member indicates which exception occurred. (On x86 based systems, it actually indicates the highest priority unmasked exception whose flag is raised. This is normally the same as the exception that last occurred.) The sip->si_addr member holds the address of the instruction that caused the exception on SPARC based systems, and on x86 based systems it holds the address of the instruction at which the trap was taken (usually the next floating point instruction following the one that caused the exception).

Finally, the uap parameter points to a structure that records the state of the system at the time the trap was taken. The contents of this structure are system-dependent; see sys/reg.h for definitions of some of its members.

Using the information provided by the operating system, we can write a SIGFPE handler that reports the type of exception that occurred and the address of the instruction that caused it. CODE EXAMPLE 4-1 shows such a handler.

CODE EXAMPLE 4-1 SIGFPE Handler

#include <stdio.h>

#include <sys/ieeefp.h>

#include <sunmath.h>

#include <siginfo.h>

#include <ucontext.h>

void handler(int sig, siginfo_t *sip, ucontext_t *uap)

{

unsigned code, addr;

code = sip->si_code;

addr = (unsigned) sip->si_addr;

fprintf(stderr, "fp exception %x at address %x\n", code,

addr);

}

int main()

{

double x;

/* trap on common floating point exceptions */

if (ieee_handler("set", "common", handler) != 0)

printf("Did not set exception handler\n");

/* cause an underflow exception (will not be reported) */

x = min_normal();

printf("min_normal = %g\n", x);

x = x / 13.0;

printf("min_normal / 13.0 = %g\n", x);

/* cause an overflow exception (will be reported) */

x = max_normal();

printf("max_normal = %g\n", x);

x = x * x;

printf("max_normal * max_normal = %g\n", x);

ieee_retrospective(stderr);

return 0;

}

On SPARC systems, the output from this program resembles the following:

min_normal = 2.22507e-308

min_normal / 13.0 = 1.7116e-309

max_normal = 1.79769e+308

fp exception 4 at address 10d0c

max_normal * max_normal = 1.79769e+308

Note: IEEE floating-point exception flags raised:

Inexact; Underflow;

IEEE floating-point exception traps enabled:

overflow; division by zero; invalid operation;

See the Numerical Computation Guide, ieee_flags(3M), ieee_handler(3M)

On x86 platforms, the operating system saves a copy of the accrued exception flags and then clears them before invoking a SIGFPE handler. Unless the handler takes steps to preserve them, the accrued flags are lost once the handler returns. Thus, the output from the preceding program does not indicate that an underflow exception was raised.

min_normal = 2.22507e-308

min_normal / 13.0 = 1.7116e-309

max_normal = 1.79769e+308

fp exception 4 at address 8048fe6

max_normal * max_normal = 1.79769e+308

Note: IEEE floating-point exception traps enabled:

overflow; division by zero; invalid operation;

See the Numerical Computation Guide, ieee_handler(3M)

In most cases, the instruction that causes the exception does not deliver the IEEE default result when trapping is enabled: in the preceding outputs, the value reported for max_normal*max_normal is not the default result for an operation that overflows (i.e., a correctly signed infinity). In general, a SIGFPE handler must supply a result for an operation that causes a trapped exception in order to continue the computation with meaningful values. See Handling Exceptions for one way to do this.

4.3.3 Using libm Exception Handling Extensions to Locate an Exception

C/C++ programs can use the exception handling extensions to the C99 floating point environment functions in libm to locate exceptions in several ways. These extensions include functions that can establish handlers and simultaneously enable traps, just as ieee_handler does, but they provide more flexibility. They also support logging of retrospective diagnostic messages regarding floating point exceptions to a selected file.

4.3.3.1 fex_set_handling(3m)

The fex_set_handling function allows you to select one of several options, or modes, for handling each type of floating point exception. The syntax of a call to fex_set_handling is:

ret = fex_set_handling(ex, mode, handler);

The ex argument specifies the set of exceptions to which the call applies. It must be a bitwise "or" of the values listed in the first column of TABLE 4-5. (These values are defined in fenv.h.)

FEX_NOHANDLER mode is equivalent to enabling the exception's trap without providing a handler. When an exception occurs, the system transfers control to a previously installed SIGFPE handler, if present, or aborts.

FEX_ABORT mode causes the program to call abort(3c) when the exception occurs.

FEX_SIGNAL installs the handling function specified by the handler argument for the indicated exceptions. When any of these exceptions occurs, the handler is invoked with the same arguments as if it had been installed by ieee_handler.

FEX_CUSTOM installs the handling function specified by handler for the indicated exceptions. Unlike FEX_SIGNAL mode, when an exception occurs, the handler is invoked with a simplified argument list. The arguments consist of an integer whose value is one of the values listed in TABLE 4-5 and a pointer to a structure that records additional information about the operation that caused the exception. The contents of this structure are described in the next section and in the fex_set_handling(3m) manual page.

Note that the handler parameter is ignored if the specified mode is FEX_NONSTOP, FEX_NOHANDLER, or FEX_ABORT. fex_set_handling returns a nonzero value if the specified mode is established for the indicated exceptions, and returns zero otherwise. (In the examples below, the return value is ignored.)

The following examples suggest ways to use fex_set_handling to locate certain types of exceptions. To abort on a 0/0 exception:

fex_set_handling(FEX_INV_ZDZ, FEX_ABORT, NULL);

To install a SIGFPE handler for overflow and division by zero:

fex_set_handling(FEX_OVERFLOW | FEX_DIVBYZERO, FEX_SIGNAL, handler);

In the previous example, the handler function could print the diagnostic information supplied via the sip parameter to a SIGFPE handler, as shown in the previous subsection. By contrast, the following example prints the information about the exception that is supplied to a handler installed in FEX_CUSTOM mode. (See the fex_set_handling(3m) manual page for more information.)

The handler in the preceding example reports the type of exception that occurred, the type of operation that caused it, and the operands. It does not indicate where the exception occurred. To find out where the exception occurred, you can use retrospective diagnostics.

4.3.3.2 Retrospective Diagnostics

Another way to locate an exception using the libm exception handling extensions is to enable logging of retrospective diagnostic messages regarding floating point exceptions. When you enable logging of retrospective diagnostics, the system records information about certain exceptions. This information includes the type of exception, the address of the instruction that caused it, the manner in which it will be handled, and a stack trace similar to that produced by a debugger. (The stack trace recorded with a retrospective diagnostic message contains only instruction addresses and function names; for additional debugging information such as line numbers, source file names, and argument values, you must use a debugger.)

The log of retrospective diagnostics does not contain information about every single exception that occurs; if it did, a typical log would be huge, and it would be impossible to isolate unusual exceptions. Instead, the logging mechanism eliminates redundant messages. A message is considered redundant under either of two circumstances:

The same exception has been previously logged at the same location (i.e., with the same instruction address and stack trace), or

FEX_NONSTOP mode is in effect for the exception and its flag has been previously raised.

In particular, in most programs, only the first occurrence of each type of exception will be logged. (When FEX_NONSTOP handling mode is in effect for an exception, clearing its flag via any of the C99 floating point environment functions allows the next occurrence of that exception to be logged, provided it does not occur at a location at which it was previously logged.)

To enable logging, use the fex_set_log function to specify the file to which messages should be delivered. For example, to log messages to the standard error file, use:

fex_set_log(stderr);

CODE EXAMPLE 4-3 combines logging of retrospective diagnostics with the shared object preloading facility illustrated in the previous section. By creating the following C source file, compiling it to a shared object, preloading the shared object by supplying its path name in the LD_PRELOAD environment variable, and specifying the names of one or more exceptions (separated by commas) in the FTRAP environment variable, you can simultaneously abort the program on the specified exceptions and obtain retrospective diagnostic output showing where each exception occurs.

The preceding output shows that the invalid operation exception was raised as a result of a square root operation in the routine sqrtm1.

(As noted above, to enable trapping from an initialization routine in a shared object on x86 platforms, you must override the standard __fpstart routine.)

Appendix A gives more examples showing typical log outputs. For general information, see the fex_set_log(3m) man page.

4.4 Handling Exceptions

Historically, most numerical software has been written without regard to exceptions (for a variety of reasons), and many programmers have become accustomed to environments in which exceptions cause a program to abort immediately. Now, some high-quality software packages such as LAPACK are being carefully designed to avoid exceptions such as division by zero and invalid operations and to scale their inputs aggressively to preclude overflow and potentially harmful underflow. Neither of these approaches to dealing with exceptions is appropriate in every situation. However, ignoring exceptions can pose problems when one person writes a program or subroutine that is intended to be used by someone else (perhaps someone who does not have access to the source code), and attempting to avoid all exceptions can require many defensive tests and branches and carry a significant cost (see Demmel and Li, "Faster Numerical Algorithms via Exception Handling," IEEE Trans. Comput. 43 (1994), pp. 983-992.)

The default exception response, status flags, and optional trapping facility of IEEE arithmetic are intended to provide a third alternative: continuing a computation in the presence of exceptions and either detecting them after the fact or intercepting and handling them as they occur. As described above, ieee_flags or the C99 floating point environment functions can be used to detect exceptions after the fact, and ieee_handler or fex_set_handling can be used to enable trapping and install a handler to intercept exceptions as they occur. In order to continue the computation, however, the IEEE standard recommends that a trap handler be able to provide a result for the operation that incurred an exception. A SIGFPE handler installed via ieee_handler or fex_set_handling in FEX_SIGNAL mode can accomplish this using the uap parameter supplied to a signal handler by the Solaris operating environment. An FEX_CUSTOM mode handler installed via fex_set_handling can provide a result using the info parameter supplied to such a handler.

Recall that a SIGFPE signal handler can be declared in C as follows:

#include <siginfo.h>

#include <ucontext.h>

void handler(int sig, siginfo_t *sip, ucontext_t *uap)

{

...

}

When a SIGFPE signal handler is invoked as a result of a trapped floating point exception, the uap parameter points to a data structure that contains a copy of the machine's integer and floating point registers as well as other system-dependent information describing the exception. If the signal handler returns normally, the saved data are restored and the program resumes execution at the point at which the trap was taken. Thus, by accessing and decoding the information in the data structure that describes the exception and possibly modifying the saved data, a SIGFPE handler can substitute a user-supplied value for the result of an exceptional operation and continue computation.

An FEX_CUSTOM mode handler can be declared as follows:

#include <fenv.h>

void handler(int ex, fex_info_t *info)

{

...

}

When a FEX_CUSTOM handler is invoked, the ex parameter indicates which type of exception occurred (it is one of the values listed in TABLE 4-5) and the info parameter points to a data structure that contains more information about the exception. Specifically, this structure contains a code representing the arithmetic operation that caused the exception and structures recording the operands, if they are available. It also contains a structure recording the default result that would have been substituted if the exception were not trapped and an integer value holding the bitwise "or" of the exception flags that would have accrued. The handler can modify the latter members of the structure to substitute a different result or change the set of flags that are accrued. (Note that if the handler returns without modifying these data, the program will continue with the default untrapped result and flags just as if the exception were not trapped.)

As an illustration, the following section shows how to substitute a scaled result for an operation that underflows or overflows. See Appendix A for further examples.

4.4.0.1 Substituting IEEE Trapped Under/Overflow Results

The IEEE standard recommends that when underflow and overflow are trapped, the system should provide a way for a trap handler to substitute an exponent-wrapped result, i.e., a value that agrees with what would have been the rounded result of the operation that underflowed or overflowed except that the exponent is wrapped around the end of its usual range, thereby effectively scaling the result by a power of two. The scale factor is chosen to map underflowed and overflowed results as nearly as possible to the middle of the exponent range so that subsequent computations will be less likely to underflow or overflow further. By keeping track of the number of underflows and overflows that occur, a program can scale the final result to compensate for the exponent wrapping. This under/overflow "counting mode" can be used to produce accurate results in computations that would otherwise exceed the range of the available floating point formats. (See P. Sterbenz, Floating-Point Computation.)

On SPARC based systems, when a floating point instruction incurs a trapped exception, the system leaves the destination register unchanged. Thus, in order to substitute the exponent-wrapped result, an under/overflow handler must decode the instruction, examine the operand registers, and generate the scaled result itself. CODE EXAMPLE 4-4 shows a handler that performs these steps. (In order to use this handler with code compiled for UltraSPARCbased systems, compile the handler on a system running the Solaris 2.6 OS, Solaris 7 OS, or Solaris 8 OS and define the preprocessor token V8PLUS.)

In this example, the variables a, b, x, and y have been declared volatile only to prevent the compiler from evaluating a * b, etc., at compile time. In typical usage, the volatile declarations would not be needed.

The output from the preceding program is:

159.309

1.59309e-28

1

4.14884e+137

4.14884e-163

1

Note: IEEE floating-point exception traps enabled:

underflow; overflow;

See the Numerical Computation Guide, ieee_handler(3M)

On x86 based systems, the floating point hardware provides the exponent-wrapped result when a floating point instruction incurs a trapped underflow or overflow and its destination is a register. When trapped underflow or overflow occurs on a floating point store instruction, however, the hardware traps without completing the store (and without popping the stack, if the store instruction is a store-and-pop). Thus, in order to implement counting mode, an under/overflow handler must generate the scaled result and fix up the stack when a trap occurs on a store instruction. CODE EXAMPLE 4-5 illustrates such a handler.

As on SPARC based systems, the output from the preceding program on x86 is:

159.309

1.59309e-28

1

4.14884e+137

4.14884e-163

1

Note: IEEE floating-point exception traps enabled:

underflow; overflow;

See the Numerical Computation Guide, ieee_handler(3M)

C/C++ programs can use the fex_set_handling function in libm to install a FEX_CUSTOM handler for underflow and overflow. On SPARC based systems, the information supplied to such a handler always includes the operation that caused the exception and the operands, and this information is sufficient to allow the handler to compute the IEEE exponent-wrapped result, as shown above. On x86 based systems, the available information might not always indicate which particular operation caused the exception; when the exception is raised by one of the transcendental instructions, for example, the info->op parameter is set to fex_other. (See the fenv.h file for definitions.) Moreover, the x86 hardware delivers an exponent-wrapped result automatically, and this can overwrite one of the operands if the destination of the excepting instruction is a floating point register.

Fortunately, the fex_set_handling feature provides a simple way for a handler installed in FEX_CUSTOM mode to substitute the IEEE exponent-wrapped result for an operation that underflows or overflows. When either of these exceptions is trapped, the handler can set

info->res.type = fex_nodata;

to indicate that the exponent-wrapped result should be delivered. Here is an example showing such a handler: