.\" @(#)ieee_flags.3m 1.21 93/09/01 SMI;
.TH ieee_flags 3M  "1 Sep 1993"
.UC 4
.de Pi		\" PI stuff sign
.if n \\
\\$2pi\\$1
.if t \\
\\$2\\(*p\\$1
..
.ds up \fIulp\fR
.SH NAME
ieee_flags \- mode and status function for IEEE standard arithmetic
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lsunmath -lm
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.B #include <sunmath.h>
.LP
.BI "int ieee_flags(const char *" "action" ,
.BI "const char *" "mode" ,
.BI "const char *" "in" ,
.BI "char **" "out" );
.SH DESCRIPTION
.IX "ieee_flags function" "" "\fLieee_flags()\fP function"
.LP
This function provides easy access to the modes and status required to
fully exploit
.SM 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.
.LP
There are four types of
.IR action :
``get'', ``set'', ``clear'', and ``clearall''.
There are three valid settings for
.IR mode ,
two corresponding to modes of
.SM IEEE
arithmetic:
.IP
.nf
``direction'',		.\|.\|. current rounding direction mode
``precision'',		.\|.\|. current rounding precision mode
.fi
.LP
and one corresponding to status of
.SM IEEE
arithmetic:
.IP
.nf
``exception''. 		.\|.\|. accrued exception-occurred status
.fi
.LP
There are 14 types of
.I in
and
.I out :
.IP
.nf
``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
.fi
.LP
Note: ``all'' and ``common'' only make sense with ``set'' or ``clear''.
.LP
For ``clearall'',
.B ieee_flags(\|)
returns 0 and restores all default modes and status.
Nothing will be assigned to
.IR out .
Thus
.IP
.nf
.ft B
char *mode, *out, *in;
ieee_flags("clearall",mode, in, &out);
.ft R
.fi
.LP
set rounding direction to ``nearest'', rounding precision to ``extended'',
and all accrued exception-occurred status to zero.
.LP
For ``clear'',
.B ieee_flags(\|)
returns 0 and restores the default mode or status.
Nothing will be assigned to
.IR out .
Thus
.IP
.nf
.ft B
char *out, *in;
ieee_flags("clear","direction", in, &out);       \fP.\|.\|. set rounding direction to round to nearest.
.fi
.ft R
.LP
For ``set'',
.B 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
.IR out .
Thus
.IP
.nf
.ft B
char *out, *in;
ieee_flags ("set","direction","tozero",&out);	\fP.\|.\|. set rounding direction to round toward zero;
.fi
.ft R
.LP
For ``get'', we have the following cases:
.LP
Case 1:
.I mode
is ``direction''. In that case,
.I out
returns one of the four strings
``nearest'', ``tozero'', ``positive'', ``negative''; and
.B ieee_flags(\|)
returns a value corresponding to
.I out
according to the enum
.I fp_direction_type
defined in
.BR <sys/ieeefp.h> .
.LP
Case 2:
.I mode
is ``precision''. In that case,
.I out
returns one of the three strings
``extended'', ``double'', ``single''; and
.B ieee_flags(\|)
returns a value corresponding to
.I out
according to the enum
.I fp_precision_type
defined in
.BR <sys/ieeefp.h> .
.br
.ne 10
.LP
Case 3:
.I mode
is ``exception''. In that case,
.I out
returns
.IP
.nf
.BR (a) " ``not available'' if information on exception is not available,"
.BR (b) " ``'' (the empty string) if no accrued exception,"
.BR (c) " the accrued exception that has the highest priority according to the list below"
.RS
.IP
.BR  (1) " the exception named by \fIin\fP,"
.BR  (2) " ``invalid'',"
.BR  (3) " ``overflow'',"
.BR  (4) " ``division'',"
.BR  (5) " ``underflow'',"
.BR  (6) " ``inexact''."
.fi
.RE
.LP
In this case
.B ieee_flags(\|)
returns a five or six bit value where each bit
(cf. enum
.I fp_exception_type
in
.BR <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.
.LP
Example:
.IP
.nf
.ft B
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);
.ft R
.fi
.LP
then out = ``overflow'', and  k=25.