ieee_flags(3M)

NAME
ieee_flags - mode and status function for IEEE standard arithmetic

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 easy access to the modes and status required to fully exploit ANSI/IEEE Std 754-1985 arithmetic in a C program. All arguments are pointers to strings. Results arising from invalid arguments and invalid combinations are undefined for efficiency.

There are four types of action: ``get'', ``set'', ``clear'', and ``clearall''. There are three valid settings for mode, two corresponding to modes of IEEE arithmetic:

    ``direction'',		... current rounding direction mode
    ``precision'',		... current rounding precision mode

and one corresponding to status of IEEE arithmetic:

    ``exception''. 		... accrued exception-occurred status

There are 14 types of in and out :

    ``nearest'',		... round toward nearest
    ``tozero'', 		... round toward zero
    ``negative'',		... round toward negative infinity
    ``positive'',		... round toward positive infinity
    ``extended'',
    ``double'',
    ``single'',
    ``inexact'',
    ``division'', 		... division by zero exception
    ``underflow'',
    ``overflow'',
    ``invalid'',
    ``all'',			... all five exceptions above
    ``common''. 		... invalid, overflow, and division exceptions

Note: ``all'' and ``common'' only make sense with ``set'' or ``clear''.

For ``clearall'', ieee_flags() returns 0 and restores all default modes and status. Nothing will be assigned to out. Thus

    char *mode, *out, *in;
    ieee_flags("clearall",mode, in, &out);

set rounding direction to ``nearest'', rounding precision to ``extended'', and all accrued exception-occurred status to zero.

For ``clear'', ieee_flags() returns 0 and restores the default mode or status. Nothing will be assigned to out. Thus

    char *out, *in;
    ieee_flags("clear","direction", in, &out);       ... set rounding direction to round to nearest.

For ``set'', ieee_flags() returns 0 if the action is successful and 1 if the corresponding required status or mode is not available (for instance, not supported in hardware). Nothing will be assigned to out. Thus

    char *out, *in;
    ieee_flags ("set","direction","tozero",&out);	... set rounding direction to round toward zero;

For ``get'', we have the following cases:

Case 1: mode is ``direction''. In that case, out returns one of the four strings ``nearest'', ``tozero'', ``positive'', ``negative''; and ieee_flags() returns a value corresponding to out according to the enum fp_direction_type defined in <sys/ieeefp.h>.

Case 2: mode is ``precision''. In that case, out returns one of the three strings ``extended'', ``double'', ``single''; and ieee_flags() returns a value corresponding to out according to the enum fp_precision_type defined in <sys/ieeefp.h>.

Case 3: mode is ``exception''. In that case, out returns

    (a) ``not available'' if information on exception is not available,
    (b) ``'' (the empty string) if no accrued exception,
    (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''.

In this case ieee_flags() returns a five or six bit value where each bit (cf. enum fp_exception_type in <sys/ieeefp.h>) corresponds to an exception-occurred accrued status flag: 0 = off, 1 = on. The bit corresponding to a particular exception varies among architectures; see /usr/include/sys/ieeefp.h.

Example:

    extern int ieee_flags(const char *, const char *, const char *, char **);
    char *out;
    int k;
    ieee_flags ("clear","exception","all",&out);	/* clear all accrued exceptions */
    ...
    ... (code that generates three exceptions: overflow, invalid, inexact)
    ...
    k = ieee_flags("get","exception","overflow",&out);

then out = ``overflow'', and k=25.