[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Base Operating System and Extensions Technical Reference, Volume 1

fp_clr_flag, fp_set_flag, fp_read_flag, or fp_swap_flag Subroutine

Purpose

Allows operations on the floating-point exception flags.

Library

Standard C Library (libc.a)

Syntax

#include <float.h>
#include <fpxcp.h>
void fp_clr_flag(Mask)
fpflag_t Mask;
void fp_set_flag(Mask)
fpflag_t Mask;
fpflag_t fp_read_flag( )
fpflag_t fp_swap_flag(Mask)
fpflag_t Mask;

Description

These subroutines aid in determining both when an exception has occurred and the exception type. These subroutines can be called explicitly around blocks of code that may cause a floating-point exception.

According to the IEEE Standard for Binary Floating-Point Arithmetic, the following types of floating-point operations must be signaled when detected in a floating-point operation:

An invalid operation occurs when the result cannot be represented (for example, a sqrt operation on a number less than 0).

The IEEE Standard for Binary Floating-Point Arithmetic states: "For each type of exception, the implementation shall provide a status flag that shall be set on any occurrence of the corresponding exception when no corresponding trap occurs. It shall be reset only at the user's request. The user shall be able to test and to alter the status flags individually, and should further be able to save and restore all five at one time."

Floating-point operations can set flags in the floating-point exception status but cannot clear them. Users can clear a flag in the floating-point exception status using an explicit software action such as the fp_swap_flag (0) subroutine.

The fpxcp.h file defines the following names for the flags indicating floating-point exception status:

FP_INVALID Invalid operation summary
FP_OVERFLOW Overflow
FP_UNDERFLOW Underflow
FP_DIV_BY_ZERO Division by 0
FP_INEXACT Inexact result

In addition to these flags, the operating system supports additional information about the cause of an invalid operation exception. The following flags also indicate floating-point exception status and defined in the fpxcp.h file. The flag number for each exception type varies, but the mnemonics are the same for all ports. The following invalid operation detail flags are not required for conformance to the IEEE floating-point exceptions standard:

FP_INV_SNAN Signaling NaN
FP_INV_ISI INF - INF
FP_INV_IDI INF / INF
FP_INV_ZDZ 0 / 0
FP_INV_IMZ INF x 0
FP_INV_CMP Unordered compare
FP_INV_SQRT Square root of a negative number
FP_INV_CVI Conversion to integer error
FP_INV_VXSOFT Software request

Parameters

Mask A 32-bit pattern that identifies floating-point exception flags.

Return Values

The fp_clr_flag subroutine resets the exception status flags defined by the Mask parameter to 0 (false). The remaining flags in the exception status are unchanged.

The fp_set_flag subroutine sets the exception status flags defined by the Mask parameter to 1 (true). The remaining flags in the exception status are unchanged.

The fp_read_flag subroutine returns the current floating-point exception status. The flags in the returned exception status can be tested using the flag definitions above. You can test individual flags or sets of flags.

The fp_swap_flag subroutine writes the Mask parameter into the floating-point status and returns the floating-point exception status from before the write.

Users set or reset multiple exception flags using fp_set_flag and fp_clr_flag by ANDing or ORing definitions for individual flags. For example, the following resets both the overflow and inexact flags:

fp_clr_flag (FP_OVERFLOW | FP_INEXACT)

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The fp_any_enable, fp_is_enabled, fp_enable_all, fp_enable, fp_disable, or fp_disable_all subroutine, fp_any_xcp, fp_divbyzero, fp_inexact, fp_invalid_op, fp_overflow, fp_underflow subroutines, fp_iop_infdinf, fp_iop_infmzr, fp_iop_infsinf, fp_iop_invcmp, fp_iop_snan, or fp_iop_zrdzr subroutines, fp_read_rnd or fp_swap_rnd subroutine.

IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Standards 754-1985 and 854-1987) describes the IEEE floating-point exceptions.

Floating-Point Exceptions Overview and Subroutines Overview in AIX General Programming Concepts: Writing and Debugging Programs.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]