ieee_flags(3M)ieee_flags(3M)NAMEieee_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 combi‐
nations 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 corre‐
sponds 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 pre‐
cision. 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 informa‐
tion 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(5) for descriptions of the following attributes:
┌────────────────────┬─────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├────────────────────┼─────────────────┤
│Interface Stability │ Committed │
│MT-Level │ MT-Safe │
└────────────────────┴─────────────────┘
SEE ALSOfeclearexcept(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_han‐
dler(3M), attributes(5)NOTES
On SPARC, there is no rounding precision mode. When mode is ``preci‐
sion'', 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.
14 Mar 2009 ieee_flags(3M)