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 .