fpgetround(3M)

NAME

fpgetround(), fpsetround(), fpgetmask(), fpsetmask(), fpgetsticky(), fpsetsticky(), fpsetdefaults(), fpgetcontrol(), fpsetcontrol(), fpgetfastmode(), fpsetfastmode() − floating-point mode-control functions

SYNOPSIS

#include <math.h>

fp_rnd fpgetround(void);

fp_rnd fpsetround(fp_rnd mode);

fp_except fpgetmask(void);

fp_except fpsetmask(fp_except value);

fp_except fpgetsticky(void);

fp_except fpsetsticky(fp_except value);

int fpgetfastmode(void);

int fpsetfastmode(int value);

void fpsetdefaults(void);

fp_control fpgetcontrol(void);

fp_control fpsetcontrol(fp_control value);

DESCRIPTION

The fpgetround() suite of functions allows programmers to manipulate the floating-point control register (also called the floating-point status register).

fpgetround() returns the current rounding mode. The type of the returned value, fp_rnd, is defined as follows in <math.h>:

typedef enum {
    FP_RZ=0,   /* Round toward zero */
    FP_RN,     /* Round to nearest */
    FP_RP,     /* Round toward positive infinity */
    FP_RM,     /* Round toward negative infinity */
    } fp_rnd;

The default value is FP_RN. Round-to-nearest mode rounds to the representable value closest to the true value. If two representable values are equally close to the true value, the system chooses the one whose least significant bit is zero.

fpsetround() sets the rounding mode to the specified value of type fp_rnd and returns the previous rounding mode.

There are five floating-point exceptions: divide-by-zero, overflow, underflow, imprecise (inexact) result, and invalid operation. If a floating-point exception occurs and the corresponding exception trap enable bit is set to 1, the trap takes place. If an exception occurs and the exception trap enable bit is set to 0, the corresponding exception flag is set to 1 and no trap takes place. The exception trap enable bits are sometimes called mask bits; the exception flags are sometimes called sticky bits. The functions fpgetmask() and fpgetsticky() return the current settings of these bits. To change the settings of these bits, use fpsetmask() and fpsetsticky().

fpgetmask() returns the current exception trap enable bits. The type of the returned value, fp_except, is defined as int in <math.h>. The floating-point exception types are defined as follows in <math.h>:

#define FP_X_INV       0x10 /* invalid operation exception */
#define FP_X_DZ        0x08 /* divide-by-zero exception */
#define FP_X_OFL       0x04 /* overflow exception */
#define FP_X_UFL       0x02 /* underflow exception */
#define FP_X_IMP       0x01 /* imprecise (inexact result) */
#define FP_X_CLEAR     0x00 /* simply zero to clear all flags */

fpsetmask() sets or clears the exception trap enable bits and returns the previous setting. The argument is an expression of type fp_except. (To set or clear the exception trap enable bits at compile time, use the compiler option +FP string).

fpgetsticky() returns the current exception flags.

fpsetsticky() sets or clears the exception flags and returns the previous setting. The argument is an expression of type fp_except.

fpgetfastmode() and fpsetfastmode() allow the programmer to change the way the system handles underflow. Fast underflow mode, also known as fastmode, is an alternative to IEEE-754-compliant underflow mode. On Series 700/800 systems, most underflow cases are supported by trapping into the kernel, where the IEEE-mandated conversion of the result into a denormalized value or zero is accomplished by software emulation. On later PA1.1 systems and on all PA2.0 systems, fastmode causes the hardware to simply substitute a zero for the result of an operation, with no fault occurring. This may be a significant performance optimization for applications that underflow frequently. Fastmode also causes denormalized floating-point operands to be treated as if they were true zero operands.

fpgetfastmode() returns the current fastmode setting: 1 if fastmode is set, 0 if the default IEEE-754-compliant underflow mode is set. On systems that do not support fastmode, this function returns an undefined value.

On systems that support fastmode, fpsetfastmode() sets fastmode to either 1 (fastmode) or 0 (IEEE-754-compliant underflow mode) and returns the previous setting. On systems that do not support fastmode, this function has no effect.

fpsetdefaults() changes the default environment, which is

Round to nearest ( FP_RN )
All exception flags cleared ( FP_X_CLEAR )
All exception traps disabled
Fast underflow mode disabled

fpsetdefaults() changes these defaults to more useful values. Specifically, it enables traps for the invalid operation, divide-by-zero, and overflow exceptions, while leaving the underflow and inexact-result exception traps disabled. It sets the environment as follows:

Round to nearest ( FP_RN )
All exception flags cleared ( FP_X_CLEAR )
All exception traps enabled except underflow and inexact result ( FP_X_INV+FP_X_DZ+FP_X_OFL )
Fast underflow mode enabled (if the system supports it)

fpgetcontrol() and fpsetcontrol() access the floating-point status register.

fpgetcontrol() returns the value of the floating-point status register. The type of the returned value, fp_control, is defined as long in <math.h>.

fpsetcontrol() sets the value of the floating-point status register and returns the previous value. For the format of this register, see the HP-UX Floating-Point Guide or the PA-RISC 1.1 or 2.0 architecture and instruction set reference manual.

To use these functions, link in the math library by specifying −lm on the compiler or linker command line.

ERRORS

No errors are defined.

WARNINGS

fpsetsticky() modifies all exception flags. fpsetmask() modifies all exception trap enable bits.

Both C and FORTRAN require truncation (rounding to zero) for floating-point to integer conversions. The current rounding mode has no effect on these conversions.