Provided by: manpages-posix-dev_2.16-1_all bug

NAME

       fenv.h - floating-point environment

SYNOPSIS

       #include <fenv.h>

DESCRIPTION

       The  <fenv.h>  header  shall  define  the  following data types through
       typedef:

       fenv_t 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.

       fexcept_t
              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.

       The <fenv.h> header shall define the following constants if and only if
       the  implementation  supports  the floating-point exception by means of
       the  floating-point   functions   feclearexcept(),   fegetexceptflag(),
       feraiseexcept(), fesetexceptflag(), and fetestexcept(). Each expands to
       an integer constant expression with values such that  bitwise-inclusive
       ORs of all combinations of the constants result in distinct values.

              FE_DIVBYZERO
              FE_INEXACT
              FE_INVALID
              FE_OVERFLOW
              FE_UNDERFLOW

       The  <fenv.h>  header  shall  define  the  following constant, which is
       simply  the  bitwise-inclusive  OR  of  all  floating-point   exception
       constants defined above:

              FE_ALL_EXCEPT

       The <fenv.h> header shall define the following constants if and only if
       the  implementation  supports  getting  and  setting  the   represented
       rounding  direction  by  means  of  the  fegetround()  and fesetround()
       functions. Each expands to an integer constant expression whose  values
       are distinct non-negative vales.

              FE_DOWNWARD
              FE_TONEAREST
              FE_TOWARDZERO
              FE_UPWARD

       The   <fenv.h>  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
       fenv_t. It can be used as an  argument  to  the  functions  within  the
       <fenv.h> header that manage the floating-point environment.

              FE_DFL_ENV

       The following shall be declared as functions and may also be defined as
       macros. Function prototypes shall be provided.

              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 *);

       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.)

       The following sections are informative.

APPLICATION USAGE

       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.

       Certain application programming conventions support the intended  model
       of use for the floating-point environment:

        * 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.

        * A function call is assumed to require default floating-point control
          modes, unless its documentation promises otherwise.

        * A  function  call  is  assumed  to  have  the  potential for raising
          floating-point  exceptions,  unless   its   documentation   promises
          otherwise.

       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.

       Even though the rounding  direction  macros  may  expand  to  constants
       corresponding  to the values of FLT_ROUNDS, they are not required to do
       so.

       For example:

              #include <fenv.h>
              void f(double x)
              {
                  #pragma STDC FENV_ACCESS ON
                  void g(double);
                  void h(double);
                  /* ... */
                  g(x + 1);
                  h(x + 1);
                  /* ... */
              }

       If the function g() might depend on status flags set as a  side  effect
       of  the  first  x+1, or if the second x+1 might depend on control modes
       set as a side effect of the call to function g(), then the  application
       shall contain an appropriately placed invocation as follows:

              #pragma STDC FENV_ACCESS ON

RATIONALE

   The fexcept_t Type
       fexcept_t  does  not  have  to  be  an integer type. Its values must be
       obtained by a call to  fegetexceptflag(),  and  cannot  be  created  by
       logical  operations  from the exception macros. An implementation might
       simply implement fexcept_t  as  an  int  and  use  the  representations
       reflected  by  the  exception  macros,  but  is  not required to; other
       representations might contain extra information about  the  exceptions.
       fexcept_t  might  be  a  struct  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 fexcept_t,  and  so  the  user  cannot
       inspect it.

   Exception and Rounding Macros
       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 #ifdef to test for this.

FUTURE DIRECTIONS

       None.

SEE ALSO

       The  System Interfaces volume of IEEE Std 1003.1-2001, feclearexcept(),
       fegetenv(),    fegetexceptflag(),     fegetround(),     feholdexcept(),
       feraiseexcept(),     fesetenv(),    fesetexceptflag(),    fesetround(),
       fetestexcept(), feupdateenv()

COPYRIGHT

       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .