User's Guide

Detecting and Trapping Floating-Point Exceptions

As stated earlier, the IEEE standard for floating-point arithmetic defines a number of exception (or error) conditions that might require special care to avoid or recover from. The following sections are intended to help you make your programs work safely in the presence of such exception conditions while sacrificing the minimum amount of performance.

The floating-point hardware always detects a number of floating-point exception conditions (which the IEEE standard rigorously defines): overflow, underflow, zerodivide, invalid, and inexact.

By default, the only action that occurs is that a status flag is set. The program continues without a problem (although the results from that point on may not be what you expect). If you want to know when an exception occurs, you can arrange for one or more of these exception conditions to generate a signal.

The signal causes a branch to a handler routine. The handler receives information about the type of signal and the state of the program when the signal occurred. It can produce a core dump, display a listing showing where the exception occurred, modify the results of the calculation, or carry out some other processing that you specify.

Both the XL Fortran compiler and the operating system provide facilities for working with floating-point exception conditions. The compiler facilities indicate the presence of exceptions by generating SIGTRAP signals. The operating-system facilities generate SIGFPE signals. Do not mix these different facilities within a single program.

Compiler Features for Trapping Floating-Point Exceptions

To turn on XL Fortran exception trapping, compile the program with the -qflttrap option and some combination of suboptions that includes enable. This option uses trap operations to detect floating-point exceptions and generates SIGTRAP signals when exceptions occur.

-qflttrap also has suboptions that correspond to the names of the exception conditions. For example, if you are only concerned with handling overflow and underflow exceptions, you could specify something similar to the following:

  xlf95 -qflttrap=overflow:underflow:enable compute_pi.f

An advantage of this approach is that performance impact is relatively low. To further reduce performance impact, you can include the imprecise suboption of the -qflttrap option. This suboption delays any trapping until the program reaches the start or end of a subprogram.

The disadvantages of this approach include the following:

• It only traps exceptions that occur in code that you compiled with -qflttrap, which does not include system library routines.
• It is generally not possible for a handler to substitute results for failed calculations if you use the imprecise suboption of -qflttrap.

Notes:

1. If your program depends on floating-point exceptions occurring for particular operations, also specify -qfloat suboptions that include nofold and nohssngl. Otherwise, the compiler might replace an exception-producing calculation with a constant NaN or infinity value, or it might eliminate an overflow in a single-precision operation.

2. The suboptions of the -qflttrap option replace an earlier technique that required you to modify your code with calls to the fpsets and fpgets procedures. You no longer require these calls for exception handling if you use the appropriate -qflttrap settings.

   Attention: If your code contains fpsets calls that enable checking for floating-point exceptions and you do not use the -qflttrap option when compiling the whole program, the program will produce unexpected results if exceptions occur, as explained in Table 18.

Operating System Features for Trapping Floating-Point Exceptions

A direct way to turn on exception trapping is to call the operating system routine fp_trap. It uses the system hardware to detect floating-point exceptions and generates SIGFPE signals when exceptions occur. Fortran definitions for the values needed to call it are in the files /usr/include/fp_fort_c.f, fp_fort_t.f, or the xlf_fp_util module.

There are other related operating system routines that you can locate by reading the description of fp_trap.

The advantages of this approach include:

• It works for any code, regardless of the language and without the need to compile with any special options.
• It generates SIGFPE signals, the same as other popular Unix systems.

The disadvantages of this approach include:

• The program may run much slower while exception checking is turned on.
• The call to FP_TRAP requires a source-code change and thus a recompilation.

Installing an Exception Handler

When a program that uses the XL Fortran or AIX exception-detection facilities encounters an exception condition, it generates a signal. This causes a branch to whatever handler is specified by the program. The information in this section, except the explanation of the -qsigtrap option, applies both to SIGTRAP and SIGFPE signals.

By default, the program stops after producing a core file, which you can use with a debugger to locate the problem. If you want to install a SIGTRAP signal handler, use the -qsigtrap option. It allows you to specify an XL Fortran handler that produces a traceback or to specify a handler you have written:

xlf95 -qflttrap=ov:und:en pi.f                             # Dump core on an exception
xlf95 -qflttrap=ov:und:en -qsigtrap pi.f                   # Uses the xl__trce handler
xlf95 -qflttrap=ov:und:en -qsigtrap=return_22_over_7 pi.f  # Uses any other handler

You can also install an alternative exception handler, either one supplied by XL Fortran or one you have written yourself, by calling the SIGNAL subroutine (defined in /usr/include/fexcp.h):

  INCLUDE 'fexcp.h'
  CALL SIGNAL(SIGTRAP,handler_name)
  CALL SIGNAL(SIGFPE,handler_name)

The XL Fortran exception handlers and related routines are:

xl__ieee

Produces a traceback and an explanation of the signal and continues execution by supplying the default IEEE result for the failed computation. This handler allows the program to produce the same results as if exception detection was not turned on.

xl__trce

Produces a traceback and stops the program.

xl__trcedump

Produces a traceback and a core file and stops the program.

xl__sigdump

Provides a traceback that starts from the point at which it is called and provides information about the signal. You can only call it from inside a user-written signal handler, and it requires the same parameters as other AIX signal handlers. It does not stop the program. To successfully continue, the signal handler must perform some cleanup after calling this subprogram.

xl__trbk

Provides a traceback that starts from the point at which it is called. You call it as a subroutine from your code, rather than specifying it with the -qsigtrap option. It requires no parameters. It does not stop the program.

All of these handler names contain double underscores to avoid duplicating names that you declared in your program. All of these routines work for both SIGTRAP and SIGFPE signals.

You can use the -g compiler option to get line numbers in the traceback listings. The file /usr/include/fsignal.h defines a Fortran derived type similar to the sigcontext structure in /usr/include/sys/signal.h. You can write a Fortran signal handler that accesses this derived type.

Related Information:

Sample Programs for Exception Handling lists some sample programs that illustrate how to use these signal handlers or write your own. For more information on SIGNAL, see the "Intrinsic Procedures" chapter in the XL Fortran for AIX Language Reference.

Producing a Core File

To produce a core file, do not install an exception handler, or else specify the xl__trcedump handler.

Controlling the Floating-Point Status and Control Register

Before the -qflttrap suboptions or the -qsigtrap options, most of the processing for floating-point exceptions required you to change your source files to turn on exception trapping or install a signal handler. Although you can still do so, for any new applications, we recommend that you use the options instead.

To control exception handling at run time, compile without the enable suboption of the -qflttrap option:

   xlf95 -qflttrap compute_pi.f     # Check all exceptions, but do not trap.
   xlf95 -qflttrap=ov compute_pi.f  # Check one type, but do not trap.

Then, inside your program, manipulate the fpstats array (defined in the include file /usr/include/fpdc.h) and call the fpsets subroutine to specify which exceptions should generate traps.

See the sample program that uses fpsets and fpgets in Selecting the Rounding Mode.

Another method is to use the set_fpscr_flags() subroutine in the xlf_fp_util module. This subroutine allows you to set the floating-point status and control register flags you specify in the MASK argument. Flags that you do not specify in MASK remain unaffected. MASK must be of type INTEGER(FPSCR_KIND). For example:

 USE XLF_FP_UTIL
 INTEGER(FPSCR_KIND) SAVED_FPSCR
 INTEGER(FP_MODE_KIND) FP_MODE
 
 SAVED_FPSCR = get_fpscr()           ! Saves the current value of
                                     ! the fpscr register.
 
 CALL set_fpscr_flags(TRP_DIV_BY_ZERO) ! Enables trapping of
 ! ...                                 ! divide-by-zero.
 SAVED_FPSCR=set_fpscr(SAVED_FPSCR)    ! Restores fpscr register.

xlf_fp_util Procedures

The xlf_fp_util procedures allow you to query and control the floating-point status and control register (fpscr) of the processor directly. These procedures are more efficient than the fpsets and fpgets subroutines because they are mapped into inlined machine instructions that manipulate the floating-point status and control register directly.

The module, xlf_fp_util, contains the interfaces and data type definitions for these procedures and the definitions for the named constants that are needed by the procedures. This module enables type checking of these procedures at compile time rather than link time. The following files are supplied for the modules xlf_fp_util:

To use the procedures, you must add a USE XLF_FP_UTIL statement to your source file. For more information on USE, refer to the XL Fortran for AIX Language Reference.

When compiling with the -U option, you must code the names of these procedures in all lowercase.

For a list of the xlf_fp_util procedures, see the "Service and Utility Procedures" chapter in the XL Fortran for AIX Language Reference.

fpgets and fpsets Subroutines

The fpsets and fpgets subroutines provide a way to manipulate or query the floating-point status and control register. Instead of calling the operating system routines directly, you pass information back and forth in fpstat, an array of logicals. The following table shows the most commonly used array elements that deal with exceptions:

Table 20. Exception Bits to Use with fpsets and fpgets

To explicitly check for specific exceptions at particular points in a program, use fpgets and then test whether the elements in fpstat have changed. Once an exception has occurred, the corresponding exception bit (second column in the preceding table) is set until it is explicitly reset, except for fpstat(fpfx), fpstat(fpvx), and fpstat(fpfex), which are reset only when the specific exception bits are reset.

An advantage of using the fpgets and fpsets subroutines (as opposed to controlling everything with suboptions of the -qflttrap option) includes control over granularity of exception checking. For example, you might only want to test if an exception occurred anywhere in the program when the program ends.

The disadvantages of this approach include the following:

• You have to change your source code.
• These routines differ from what you may be accustomed to on other platforms.

For example, to trap floating-point overflow exceptions but only in a certain section of the program, you would set fpstat(fpoe) to .TRUE. and call fpsets. After the exception occurs, the corresponding exception bit, fpstat(fpox), is .TRUE. until the program runs:

      call fpgets(fpstat)
      fpstat(fpox) = .FALSE.
      call fpsets(fpstat)   ! resetting fpstat(fpox) to .FALSE.

Sample Programs for Exception Handling

/usr/lpp/xlf/samples/floating_point contains a number of sample programs to illustrate different aspects of exception handling:

flttrap_handler.c  and  flttrap_test.f

A sample exception handler that is written in C and a Fortran program that uses it.

xl__ieee.F  and  xl__ieee.c

Exception handlers that are written in Fortran and C that show how to substitute particular values for operations that produce exceptions. Even when you use support code such as this, the implementation of XL Fortran exception handling does not fully support the exception-handling environment that is suggested by the IEEE floating-point standard.

check_fpscr.f  and  postmortem.f

Show how to work with the fpsets and fpgets procedures and the fpstats array.

fhandler.F

Shows a sample Fortran signal handler and demonstrates the xl__sigdump procedure.

xl__trbk_test.f

Shows how to use the xl__trbk procedure to generate a traceback listing without stopping the program.

The sample programs are strictly for illustrative purposes only.

Causing Exceptions for Particular Variables

To mark a variable as "do not use", you can encode a special value called a signaling NaN (NaNS) in it. This causes an invalid exception condition any time that variable is used in a calculation.

If you use this technique, use the nans suboption of the -qfloat option, so that the program properly detects all cases where a NaNS is used, and one of the methods already described to generate corresponding SIGFPE or SIGTRAP signals.

Notes:

1. Because a NaNS is never generated as the result of a calculation and must be explicitly introduced to your program as a constant or in input data, you should not need to use this technique unless you deliberately use NaNS values in it.
2. In previous XL Fortran releases, the -qfloat suboption was called spnans. In the future, use nans instead (although spnans still works, for backward compatibility).

Minimizing the Performance Impact of Floating-Point Exception Trapping

If you need to deal with floating-point exception conditions but are concerned that doing so will make your program too slow, here are some techniques that can help minimize the performance impact:

• Consider using only a subset of the overflow, underflow, zerodivide, invalid, and inexact suboptions with the -qflttrap option if you can identify some conditions that will never happen or you do not care about. In particular, because an inexact exception occurs for each rounding error, you probably should not check for it if performance is important.
• Include the imprecise suboption with the -qflttrap option, so that your compiler command looks similar to this:

  xlf90 -qflttrap=underflow:enable:imprecise does_underflows.f
  

  imprecise makes the program check for the specified exceptions only on entry and exit to subprograms that perform floating-point calculations. This means that XL Fortran will eventually detect any exception, but you will know only the general area where it occurred, not the exact location.

  When you specify -qflttrap without imprecise, a check for exceptions follows each floating-point operation. If all your exceptions occur during calls to routines that are not compiled with -qflttrap (such as library routines), using imprecise is generally a good idea, because identifying the exact location will be difficult anyway.