Go to main content

man pages section 3: Extended Library Functions, Volume 4

Exit Print View

Updated: Thursday, June 13, 2019
 
 

ieee_flags (3SUNMATH)

Name

ieee_flags - access floating-point rounding modes and exception flags

Synopsis

cc [ flag ... ] file ...  -lsunmath -lm [ library ... ]
#include <sunmath.h>

int ieee_flags(const char *action, const char *mode,
     const char *in, char **out);

Description

This function provides access to the floating point rounding modes and exception flags required by ANSI/IEEE Std 754-1985. The action, mode, and in arguments are pointers to case-insensitive strings that specify the operation to perform. Invalid argument strings and invalid combinations of arguments yield undefined results. The out argument is a pointer to an object of type char *. When the action is “get”, *out is set to point to a read-only string that supplies the requested information. For all other values of action, *out is unchanged.

There are four valid values for action: “get”, “set”, “clear”, and “clearall”. When action is “clearall”, ieee_flags() restores the default rounding modes (rounding direction to nearest, rounding precision extended) and clears all accrued exception flags. mode and in are ignored.

When action is “get”, “set”, or “clear”, mode may be any of the following:

 
“direction”       ... current rounding direction mode
“precision”       ... current rounding precision mode
“exception”       ... accrued exception flag status

When action is “clear” and mode is “direction”, ieee_flags() sets the rounding direction to nearest. When action is “clear” and mode is “precision”, ieee_flags() sets the rounding precision to extended. In both cases, in is ignored.

When action is “clear” and mode is “exception”, ieee_flags() clears the accrued exception flag(s) specified by in, which may be one of the following:

 
“inexact”
“underflow”
“overflow”
“invalid”         ... invalid operation exception
“division”        ... division by zero exception
“all”             ... all five exceptions above
“common”          ... invalid, overflow, and division exceptions

When action is “set” and mode is “direction”, ieee_flags() sets the rounding direction to the mode specified by in, which may be one of the following:

 
“nearest”         ... round toward nearest
“tozero”          ... round toward zero
“negative”        ... round toward negative infinity
“positive”        ... round toward positive infinity

When action is “set” and mode is “precision”, ieee_flags() sets the rounding precision to the mode specified by in, which may be one of the following:

 
“extended”
“double”
“single”
 

When action is “set” and mode is “exception”, ieee_flags() sets the accrued exception flag(s) specified by in, which may be one of the exception strings listed above.

When action is “get” and mode is “direction”, ieee_flags() sets *out to the rounding direction mode string listed above that corresponds to the current rounding direction. When action is “get” and mode is “precision”, ieee_flags() sets *out to the rounding precision mode string listed above that corresponds to the current rounding precision. In both cases, in is ignored.

When action is “get” and mode is “exception”, ieee_flags() sets *out to one of the following strings:

 
(a) “not available” if accrued exception flags are not available,
(b) “” (the empty string) if there are no accrued exceptions,
(c) the accrued exception that has the highest priority according 
    to the list below

     (1) the exception named by in,
     (2) “invalid”,
     (3) “overflow”,
     (4) “division”,
     (5) “underflow”,
     (6) “inexact”.

RETURN VALUES

When action is “get”, the return value encodes the requested information using the values of the various enum types defined in <sys/ieeefp.h>. In particular, when mode is “direction”, ieee_flags() returns the enum fp_direction_type value corresponding to the current rounding direction. When mode is “precision”, ieee_flags() returns the enum fp_precision_type value corresponding to the current rounding precision. When mode is “exception”, ieee_flags() returns the bitwise “or” of all accrued exception flags, where the bit position corresponding to each exception is defined by enum fp_exception_type. For other values of mode, ieee_flags() returns 0.

When action is “set”, ieee_flags() returns 1 if the requested mode cannot be set (e.g., because it is not supported in the hardware), 0 otherwise.

For all other values of action, ieee_flags() returns 0.

Examples

 
#include <sunmath.h>

char *out;
int k;

/* report rounding precision */
(void) ieee_flags("get", "precision", "", &out);
printf("current rounding precision is %s\n", out);

/* set rounding direction to round toward zero */
k = ieee_flags("set", "direction", "tozero", &out);
if (k)
     printf("cannot set rounding direction\n");

/* clear all exception flags */
(void) ieee_flags("clear", "exception", "all", &out);

...
... (code that generates three exceptions: overflow, invalid, inexact)
...

/* restore default rounding direction */
(void) ieee_flags("clear", "direction", "", &out);

/* get accrued exceptions */
k = ieee_flags("get", "exception", "overflow", &out);

At this point, out points to the string “overflow” and, on SPARC, k = 25 = 0x19.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
MT-Safe
Availability
system/library/math

See Also

feclearexcept(3M), fegetenv(3M), fegetexceptflag(3M), fegetprec(3M), fegetround(3M), feholdexcept(3M), feraiseexcept(3M), fetestexcept(3M), feupdateenv(3M), fex_merge_flags(3M), fex_set_handling(3M), ieee_handler(3SUNMATH), attributes(7)

Notes

On SPARC, there is no rounding precision mode. When mode is “precision”, ieee_flags() performs no action and returns 0.

On x86, the rounding precision mode only affects the basic x87 floating point arithmetic instructions. It has no effect on SSE instructions.