267 lines
12 KiB
HTML
267 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title><fenv.h></title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="<fenv.h>"></a> <a name="tag_13_12"></a><!-- <fenv.h> -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_13_12_01"></a>NAME</h4>
|
|
|
|
<blockquote>fenv.h - floating-point environment</blockquote>
|
|
|
|
<h4><a name="tag_13_12_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><tt>#include <fenv.h></tt></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_12_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<div class="box"><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]"
|
|
border="0"> The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the
|
|
requirements described here and the ISO C standard is unintentional. This volume of IEEE Std 1003.1-2001 defers to
|
|
the ISO C standard. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></div>
|
|
|
|
<p>The <i><fenv.h></i> header shall define the following data types through <b>typedef</b>:</p>
|
|
|
|
<dl compact>
|
|
<dt><b>fenv_t</b></dt>
|
|
|
|
<dd>Represents the entire floating-point environment. The floating-point environment refers collectively to any floating-point
|
|
status flags and control modes supported by the implementation.</dd>
|
|
|
|
<dt><b>fexcept_t</b></dt>
|
|
|
|
<dd>Represents the floating-point status flags collectively, including any status the implementation associates with the flags. A
|
|
floating-point status flag is a system variable whose value is set (but never cleared) when a floating-point exception is raised,
|
|
which occurs as a side effect of exceptional floating-point arithmetic to provide auxiliary information. A floating-point control
|
|
mode is a system variable whose value may be set by the user to affect the subsequent behavior of floating-point arithmetic.</dd>
|
|
</dl>
|
|
|
|
<p>The <i><fenv.h></i> header shall define the following constants if and only if the implementation supports the
|
|
floating-point exception by means of the floating-point functions <a href=
|
|
"../functions/feclearexcept.html"><i>feclearexcept</i>()</a>, <a href=
|
|
"../functions/fegetexceptflag.html"><i>fegetexceptflag</i>()</a>, <a href=
|
|
"../functions/feraiseexcept.html"><i>feraiseexcept</i>()</a>, <a href=
|
|
"../functions/fesetexceptflag.html"><i>fesetexceptflag</i>()</a>, and <a href=
|
|
"../functions/fetestexcept.html"><i>fetestexcept</i>()</a>. Each expands to an integer constant expression with values such that
|
|
bitwise-inclusive ORs of all combinations of the constants result in distinct values.</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
FE_DIVBYZERO
|
|
FE_INEXACT
|
|
FE_INVALID
|
|
FE_OVERFLOW
|
|
FE_UNDERFLOW
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The <i><fenv.h></i> header shall define the following constant, which is simply the bitwise-inclusive OR of all
|
|
floating-point exception constants defined above:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
FE_ALL_EXCEPT
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The <i><fenv.h></i> header shall define the following constants if and only if the implementation supports getting and
|
|
setting the represented rounding direction by means of the <a href="../functions/fegetround.html"><i>fegetround</i>()</a> and <a
|
|
href="../functions/fesetround.html"><i>fesetround</i>()</a> functions. Each expands to an integer constant expression whose values
|
|
are distinct non-negative vales.</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
FE_DOWNWARD
|
|
FE_TONEAREST
|
|
FE_TOWARDZERO
|
|
FE_UPWARD
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The <i><fenv.h></i> header shall define the following constant, which represents the default floating-point environment
|
|
(that is, the one installed at program startup) and has type pointer to const-qualified <b>fenv_t</b>. It can be used as an
|
|
argument to the functions within the <i><fenv.h></i> header that manage the floating-point environment.</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
FE_DFL_ENV
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.</p>
|
|
|
|
<pre>
|
|
<tt>int feclearexcept(int);
|
|
int fegetexceptflag(fexcept_t *, int);
|
|
int feraiseexcept(int);
|
|
int fesetexceptflag(const fexcept_t *, int);
|
|
int fetestexcept(int);
|
|
int fegetround(void);
|
|
int fesetround(int);
|
|
int fegetenv(fenv_t *);
|
|
int feholdexcept(fenv_t *);
|
|
int fesetenv(const fenv_t *);
|
|
int feupdateenv(const fenv_t *);
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The FENV_ACCESS pragma provides a means to inform the implementation when an application might access the floating-point
|
|
environment to test floating-point status flags or run under non-default floating-point control modes. The pragma shall occur
|
|
either outside external declarations or preceding all explicit declarations and statements inside a compound statement. When
|
|
outside external declarations, the pragma takes effect from its occurrence until another FENV_ACCESS pragma is encountered, or
|
|
until the end of the translation unit. When inside a compound statement, the pragma takes effect from its occurrence until another
|
|
FENV_ACCESS pragma is encountered (including within a nested compound statement), or until the end of the compound statement; at
|
|
the end of a compound statement the state for the pragma is restored to its condition just before the compound statement. If this
|
|
pragma is used in any other context, the behavior is undefined. If part of an application tests floating-point status flags, sets
|
|
floating-point control modes, or runs under non-default mode settings, but was translated with the state for the FENV_ACCESS pragma
|
|
off, the behavior is undefined. The default state (on or off) for the pragma is implementation-defined. (When execution passes from
|
|
a part of the application translated with FENV_ACCESS off to a part translated with FENV_ACCESS on, the state of the floating-point
|
|
status flags is unspecified and the floating-point control modes have their default settings.)</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_13_12_04"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>This header is designed to support the floating-point exception status flags and directed-rounding control modes required by the
|
|
IEC 60559:1989 standard, and other similar floating-point state information. Also it is designed to facilitate code
|
|
portability among all systems.</p>
|
|
|
|
<p>Certain application programming conventions support the intended model of use for the floating-point environment:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>A function call does not alter its caller's floating-point control modes, clear its caller's floating-point status flags, nor
|
|
depend on the state of its caller's floating-point status flags unless the function is so documented.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A function call is assumed to require default floating-point control modes, unless its documentation promises otherwise.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A function call is assumed to have the potential for raising floating-point exceptions, unless its documentation promises
|
|
otherwise.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>With these conventions, an application can safely assume default floating-point control modes (or be unaware of them). The
|
|
responsibilities associated with accessing the floating-point environment fall on the application that does so explicitly.</p>
|
|
|
|
<p>Even though the rounding direction macros may expand to constants corresponding to the values of FLT_ROUNDS, they are not
|
|
required to do so.</p>
|
|
|
|
<p>For example:</p>
|
|
|
|
<pre>
|
|
<tt>#include <fenv.h>
|
|
void f(double x)
|
|
{
|
|
#pragma STDC FENV_ACCESS ON
|
|
void g(double);
|
|
void h(double);
|
|
/* ... */
|
|
g(x + 1);
|
|
h(x + 1);
|
|
/* ... */
|
|
}
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>If the function <i>g</i>() might depend on status flags set as a side effect of the first <i>x</i>+1, or if the second
|
|
<i>x</i>+1 might depend on control modes set as a side effect of the call to function <i>g</i>(), then the application shall
|
|
contain an appropriately placed invocation as follows:</p>
|
|
|
|
<pre>
|
|
<tt>#pragma STDC FENV_ACCESS ON
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_12_05"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<h5><a name="tag_13_12_05_01"></a>The fexcept_t Type</h5>
|
|
|
|
<p><b>fexcept_t</b> does not have to be an integer type. Its values must be obtained by a call to <a href=
|
|
"../functions/fegetexceptflag.html"><i>fegetexceptflag</i>()</a>, and cannot be created by logical operations from the exception
|
|
macros. An implementation might simply implement <b>fexcept_t</b> as an <b>int</b> and use the representations reflected by the
|
|
exception macros, but is not required to; other representations might contain extra information about the exceptions.
|
|
<b>fexcept_t</b> might be a <b>struct</b> with a member for each exception (that might hold the address of the first or last
|
|
floating-point instruction that caused that exception). The ISO/IEC 9899:1999 standard makes no claims about the internals of
|
|
an <b>fexcept_t</b>, and so the user cannot inspect it.</p>
|
|
|
|
<h5><a name="tag_13_12_05_02"></a>Exception and Rounding Macros</h5>
|
|
|
|
<p>Macros corresponding to unsupported modes and rounding directions are not defined by the implementation and must not be defined
|
|
by the application. An application might use <b>#ifdef</b> to test for this.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_12_06"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_12_07"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p>The System Interfaces volume of IEEE Std 1003.1-2001, <a href=
|
|
"../functions/feclearexcept.html"><i>feclearexcept</i>()</a>, <a href="../functions/fegetenv.html"><i>fegetenv</i>()</a>, <a href=
|
|
"../functions/fegetexceptflag.html"><i>fegetexceptflag</i>()</a>, <a href="../functions/fegetround.html"><i>fegetround</i>()</a>,
|
|
<a href="../functions/feholdexcept.html"><i>feholdexcept</i>()</a>, <a href=
|
|
"../functions/feraiseexcept.html"><i>feraiseexcept</i>()</a>, <a href="../functions/fesetenv.html"><i>fesetenv</i>()</a>, <a href=
|
|
"../functions/fesetexceptflag.html"><i>fesetexceptflag</i>()</a>, <a href="../functions/fesetround.html"><i>fesetround</i>()</a>,
|
|
<a href="../functions/fetestexcept.html"><i>fetestexcept</i>()</a>, <a href=
|
|
"../functions/feupdateenv.html"><i>feupdateenv</i>()</a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_13_12_08"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 6. Included for alignment with the ISO/IEC 9899:1999 standard.</p>
|
|
|
|
<p>The return types for <a href="../functions/feclearexcept.html"><i>feclearexcept</i>()</a>, <a href=
|
|
"../functions/fegetexceptflag.html"><i>fegetexceptflag</i>()</a>, <a href=
|
|
"../functions/feraiseexcept.html"><i>feraiseexcept</i>()</a>, <a href=
|
|
"../functions/fesetexceptflag.html"><i>fesetexceptflag</i>()</a>, <a href="../functions/fegetenv.html"><i>fegetenv</i>()</a>, <a
|
|
href="../functions/fesetenv.html"><i>fesetenv</i>()</a>, and <a href="../functions/feupdateenv.html"><i>feupdateenv</i>()</a> are
|
|
changed from <b>void</b> to <b>int</b> for alignment with the ISO/IEC 9899:1999 standard, Defect Report 202.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|