506 lines
11 KiB
HTML
506 lines
11 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of FENV</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>FENV</H1>
|
|
Section: Linux Programmer's Manual (3)<BR>Updated: 2017-09-15<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag,
|
|
fetestexcept, fegetenv, fegetround, feholdexcept, fesetround,
|
|
fesetenv, feupdateenv, feenableexcept, fedisableexcept,
|
|
fegetexcept - floating-point rounding and exception handling
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>#include <<A HREF="file:///usr/include/fenv.h">fenv.h</A>></B>
|
|
|
|
<B>int feclearexcept(int </B><I>excepts</I><B>);</B>
|
|
<B>int fegetexceptflag(fexcept_t *</B><I>flagp</I><B>, int </B><I>excepts</I><B>);</B>
|
|
<B>int feraiseexcept(int </B><I>excepts</I><B>);</B>
|
|
<B>int fesetexceptflag(const fexcept_t *</B><I>flagp</I><B>, int </B><I>excepts</I><B>);</B>
|
|
<B>int fetestexcept(int </B><I>excepts</I><B>);</B>
|
|
|
|
<B>int fegetround(void);</B>
|
|
<B>int fesetround(int </B><I>rounding_mode</I><B>);</B>
|
|
|
|
<B>int fegetenv(fenv_t *</B><I>envp</I><B>);</B>
|
|
<B>int feholdexcept(fenv_t *</B><I>envp</I><B>);</B>
|
|
<B>int fesetenv(const fenv_t *</B><I>envp</I><B>);</B>
|
|
<B>int feupdateenv(const fenv_t *</B><I>envp</I><B>);</B>
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
Link with <I>-lm</I>.
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
These eleven functions were defined in C99, and describe the handling
|
|
of floating-point rounding and exceptions (overflow, zero-divide, etc.).
|
|
<A NAME="lbAE"> </A>
|
|
<H3>Exceptions</H3>
|
|
|
|
The
|
|
<I>divide-by-zero</I>
|
|
|
|
exception occurs when an operation on finite numbers
|
|
produces infinity as exact answer.
|
|
<P>
|
|
|
|
The
|
|
<I>overflow</I>
|
|
|
|
exception occurs when a result has to be represented as a
|
|
floating-point number, but has (much) larger absolute value than the
|
|
largest (finite) floating-point number that is representable.
|
|
<P>
|
|
|
|
The
|
|
<I>underflow</I>
|
|
|
|
exception occurs when a result has to be represented as a
|
|
floating-point number, but has smaller absolute value than the smallest
|
|
positive normalized floating-point number (and would lose much accuracy
|
|
when represented as a denormalized number).
|
|
<P>
|
|
|
|
The
|
|
<I>inexact</I>
|
|
|
|
exception occurs when the rounded result of an operation
|
|
is not equal to the infinite precision result.
|
|
It may occur whenever
|
|
<I>overflow</I>
|
|
|
|
or
|
|
<I>underflow</I>
|
|
|
|
occurs.
|
|
<P>
|
|
|
|
The
|
|
<I>invalid</I>
|
|
|
|
exception occurs when there is no well-defined result
|
|
for an operation, as for 0/0 or infinity - infinity or sqrt(-1).
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Exception handling</H3>
|
|
|
|
Exceptions are represented in two ways: as a single bit
|
|
(exception present/absent), and these bits correspond in some
|
|
implementation-defined way with bit positions in an integer,
|
|
and also as an opaque structure that may contain more information
|
|
about the exception (perhaps the code address where it occurred).
|
|
<P>
|
|
|
|
Each of the macros
|
|
<B>FE_DIVBYZERO</B>,
|
|
|
|
<B>FE_INEXACT</B>,
|
|
|
|
<B>FE_INVALID</B>,
|
|
|
|
<B>FE_OVERFLOW</B>,
|
|
|
|
<B>FE_UNDERFLOW</B>
|
|
|
|
is defined when the implementation supports handling
|
|
of the corresponding exception, and if so then
|
|
defines the corresponding bit(s), so that one can call
|
|
exception handling functions, for example, using the integer argument
|
|
<B>FE_OVERFLOW</B>|<B>FE_UNDERFLOW</B>.
|
|
|
|
Other exceptions may be supported.
|
|
The macro
|
|
<B>FE_ALL_EXCEPT</B>
|
|
|
|
is the bitwise OR of all bits corresponding to supported exceptions.
|
|
<P>
|
|
|
|
The
|
|
<B>feclearexcept</B>()
|
|
|
|
function clears the supported exceptions represented by the bits
|
|
in its argument.
|
|
<P>
|
|
|
|
The
|
|
<B>fegetexceptflag</B>()
|
|
|
|
function stores a representation of the state of the exception flags
|
|
represented by the argument
|
|
<I>excepts</I>
|
|
|
|
in the opaque object
|
|
<I>*flagp</I>.
|
|
|
|
<P>
|
|
|
|
The
|
|
<B>feraiseexcept</B>()
|
|
|
|
function raises the supported exceptions represented by the bits in
|
|
<I>excepts</I>.
|
|
|
|
<P>
|
|
|
|
The
|
|
<B>fesetexceptflag</B>()
|
|
|
|
function sets the complete status for the exceptions represented by
|
|
<I>excepts</I>
|
|
|
|
to the value
|
|
<I>*flagp</I>.
|
|
|
|
This value must have been obtained by an earlier call of
|
|
<B>fegetexceptflag</B>()
|
|
|
|
with a last argument that contained all bits in
|
|
<I>excepts</I>.
|
|
|
|
<P>
|
|
|
|
The
|
|
<B>fetestexcept</B>()
|
|
|
|
function returns a word in which the bits are set that were
|
|
set in the argument
|
|
<I>excepts</I>
|
|
|
|
and for which the corresponding exception is currently set.
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Rounding mode</H3>
|
|
|
|
The rounding mode determines how the result of floating-point operations
|
|
is treated when the result cannot be exactly represented in the significand.
|
|
Various rounding modes may be provided:
|
|
round to nearest (the default),
|
|
round up (toward positive infinity),
|
|
round down (toward negative infinity), and
|
|
round toward zero.
|
|
<P>
|
|
|
|
Each of the macros
|
|
<B>FE_TONEAREST</B>,
|
|
|
|
<B>FE_UPWARD</B>,
|
|
|
|
<B>FE_DOWNWARD</B>,
|
|
|
|
and
|
|
<B>FE_TOWARDZERO</B>
|
|
|
|
is defined when the implementation supports getting and setting
|
|
the corresponding rounding direction.
|
|
<P>
|
|
|
|
The
|
|
<B>fegetround</B>()
|
|
|
|
function returns the macro corresponding to the current
|
|
rounding mode.
|
|
<P>
|
|
|
|
The
|
|
<B>fesetround</B>()
|
|
|
|
function sets the rounding mode as specified by its argument
|
|
and returns zero when it was successful.
|
|
<P>
|
|
|
|
C99 and POSIX.1-2008 specify an identifier,
|
|
<B>FLT_ROUNDS</B>,
|
|
|
|
defined in
|
|
<I><<A HREF="file:///usr/include/float.h">float.h</A>></I>,
|
|
|
|
which indicates the implementation-defined rounding
|
|
behavior for floating-point addition.
|
|
This identifier has one of the following values:
|
|
<DL COMPACT>
|
|
<DT id="1">-1<DD>
|
|
The rounding mode is not determinable.
|
|
<DT id="2">0<DD>
|
|
Rounding is toward 0.
|
|
<DT id="3">1<DD>
|
|
Rounding is toward nearest number.
|
|
<DT id="4">2<DD>
|
|
Rounding is toward positive infinity.
|
|
<DT id="5">3<DD>
|
|
Rounding is toward negative infinity.
|
|
</DL>
|
|
<P>
|
|
|
|
Other values represent machine-dependent, nonstandard rounding modes.
|
|
<P>
|
|
|
|
The value of
|
|
<B>FLT_ROUNDS</B>
|
|
|
|
should reflect the current rounding mode as set by
|
|
<B>fesetround</B>()
|
|
|
|
(but see BUGS).
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Floating-point environment</H3>
|
|
|
|
The entire floating-point environment, including
|
|
control modes and status flags, can be handled
|
|
as one opaque object, of type
|
|
<I>fenv_t</I>.
|
|
|
|
The default environment is denoted by
|
|
<B>FE_DFL_ENV</B>
|
|
|
|
(of type
|
|
<I>const fenv_t *</I>).
|
|
|
|
This is the environment setup at program start and it is defined by
|
|
ISO C to have round to nearest, all exceptions cleared and a nonstop
|
|
(continue on exceptions) mode.
|
|
<P>
|
|
|
|
The
|
|
<B>fegetenv</B>()
|
|
|
|
function saves the current floating-point environment in the object
|
|
<I>*envp</I>.
|
|
|
|
<P>
|
|
|
|
The
|
|
<B>feholdexcept</B>()
|
|
|
|
function does the same, then clears all exception flags,
|
|
and sets a nonstop (continue on exceptions) mode,
|
|
if available.
|
|
It returns zero when successful.
|
|
<P>
|
|
|
|
The
|
|
<B>fesetenv</B>()
|
|
|
|
function restores the floating-point environment from
|
|
the object
|
|
<I>*envp</I>.
|
|
|
|
This object must be known to be valid, for example, the result of a call to
|
|
<B>fegetenv</B>()
|
|
|
|
or
|
|
<B>feholdexcept</B>()
|
|
|
|
or equal to
|
|
<B>FE_DFL_ENV</B>.
|
|
|
|
This call does not raise exceptions.
|
|
<P>
|
|
|
|
The
|
|
<B>feupdateenv</B>()
|
|
|
|
function installs the floating-point environment represented by
|
|
the object
|
|
<I>*envp</I>,
|
|
|
|
except that currently raised exceptions are not cleared.
|
|
After calling this function, the raised exceptions will be a bitwise OR
|
|
of those previously set with those in
|
|
<I>*envp</I>.
|
|
|
|
As before, the object
|
|
<I>*envp</I>
|
|
|
|
must be known to be valid.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
These functions return zero on success and nonzero if an error occurred.
|
|
|
|
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>VERSIONS</H2>
|
|
|
|
These functions first appeared in glibc in version 2.1.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>ATTRIBUTES</H2>
|
|
|
|
For an explanation of the terms used in this section, see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+attributes">attributes</A></B>(7).
|
|
|
|
|
|
|
|
<TABLE BORDER>
|
|
<TR VALIGN=top><TD><B>Interface</B></TD><TD><B>Attribute</B></TD><TD><B>Value</B><BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>feclearexcept</B>(),
|
|
|
|
<B>fegetexceptflag</B>(),
|
|
|
|
<B>feraiseexcept</B>(),
|
|
|
|
<B>fesetexceptflag</B>(),
|
|
|
|
<B>fetestexcept</B>(),
|
|
|
|
<B>fegetround</B>(),
|
|
|
|
<B>fesetround</B>(),
|
|
|
|
<B>fegetenv</B>(),
|
|
|
|
<B>feholdexcept</B>(),
|
|
|
|
<B>fesetenv</B>(),
|
|
|
|
<B>feupdateenv</B>(),
|
|
|
|
<B>feenableexcept</B>(),
|
|
|
|
<B>fedisableexcept</B>(),
|
|
|
|
<B>fegetexcept</B>()
|
|
|
|
</TD><TD>Thread safety</TD><TD>
|
|
MT-Safe
|
|
<BR></TD></TR>
|
|
</TABLE>
|
|
|
|
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99, POSIX.1-2001.
|
|
<A NAME="lbAM"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
<A NAME="lbAN"> </A>
|
|
<H3>Glibc notes</H3>
|
|
|
|
If possible, the GNU C Library defines a macro
|
|
<B>FE_NOMASK_ENV</B>
|
|
|
|
which represents an environment where every exception raised causes a
|
|
trap to occur.
|
|
You can test for this macro using
|
|
<B>#ifdef</B>.
|
|
|
|
It is defined only if
|
|
<B>_GNU_SOURCE</B>
|
|
|
|
is defined.
|
|
The C99 standard does not define a way to set individual bits in the
|
|
floating-point mask, for example, to trap on specific flags.
|
|
Since version 2.2, glibc supports the functions
|
|
<B>feenableexcept</B>()
|
|
|
|
and
|
|
<B>fedisableexcept</B>()
|
|
|
|
to set individual floating-point traps, and
|
|
<B>fegetexcept</B>()
|
|
|
|
to query the state.
|
|
<P>
|
|
|
|
<PRE>
|
|
<B>#define _GNU_SOURCE</B> /* See <A HREF="/cgi-bin/man/man2html?7+feature_test_macros">feature_test_macros</A>(7) */
|
|
<B>#include <<A HREF="file:///usr/include/fenv.h">fenv.h</A>></B>
|
|
|
|
<B>int feenableexcept(int </B><I>excepts</I><B>);</B>
|
|
<B>int fedisableexcept(int </B><I>excepts</I><B>);</B>
|
|
<B>int fegetexcept(void);</B>
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
The
|
|
<B>feenableexcept</B>()
|
|
|
|
and
|
|
<B>fedisableexcept</B>()
|
|
|
|
functions enable (disable) traps for each of the exceptions represented by
|
|
<I>excepts</I>
|
|
|
|
and return the previous set of enabled exceptions when successful,
|
|
and -1 otherwise.
|
|
The
|
|
<B>fegetexcept</B>()
|
|
|
|
function returns the set of all currently enabled exceptions.
|
|
<A NAME="lbAO"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
C99 specifies that the value of
|
|
<B>FLT_ROUNDS</B>
|
|
|
|
should reflect changes to the current rounding mode, as set by
|
|
<B>fesetround</B>().
|
|
|
|
Currently,
|
|
|
|
this does not occur:
|
|
<B>FLT_ROUNDS</B>
|
|
|
|
always has the value 1.
|
|
|
|
<A NAME="lbAP"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+math_error">math_error</A></B>(7)
|
|
|
|
<A NAME="lbAQ"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="6"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="7"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="8"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="9"><A HREF="#lbAE">Exceptions</A><DD>
|
|
<DT id="10"><A HREF="#lbAF">Exception handling</A><DD>
|
|
<DT id="11"><A HREF="#lbAG">Rounding mode</A><DD>
|
|
<DT id="12"><A HREF="#lbAH">Floating-point environment</A><DD>
|
|
</DL>
|
|
<DT id="13"><A HREF="#lbAI">RETURN VALUE</A><DD>
|
|
<DT id="14"><A HREF="#lbAJ">VERSIONS</A><DD>
|
|
<DT id="15"><A HREF="#lbAK">ATTRIBUTES</A><DD>
|
|
<DT id="16"><A HREF="#lbAL">CONFORMING TO</A><DD>
|
|
<DT id="17"><A HREF="#lbAM">NOTES</A><DD>
|
|
<DL>
|
|
<DT id="18"><A HREF="#lbAN">Glibc notes</A><DD>
|
|
</DL>
|
|
<DT id="19"><A HREF="#lbAO">BUGS</A><DD>
|
|
<DT id="20"><A HREF="#lbAP">SEE ALSO</A><DD>
|
|
<DT id="21"><A HREF="#lbAQ">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:42 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|