contrib/openbsd_libm/man/feclearexcept.3

   1 .\"     $OpenBSD: feclearexcept.3,v 1.4 2013/06/05 03:40:26 tedu Exp $
   2 .\"
   3 .\" Copyright (c) 2011 Martynas Venckus <martynas@openbsd.org>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: June 5 2013 $
  18 .Dt FECLEAREXCEPT 3
  19 .Os
  20 .Sh NAME
  21 .Nm feclearexcept ,
  22 .Nm fegetexceptflag ,
  23 .Nm feraiseexcept ,
  24 .Nm fesetexceptflag ,
  25 .Nm fetestexcept
  26 .Nd access floating-point status flags
  27 .Sh SYNOPSIS
  28 .In fenv.h
  29 .Ft int
  30 .Fn feclearexcept "int excepts"
  31 .Ft int
  32 .Fn fegetexceptflag "fexcept_t *flagp" "int excepts"
  33 .Ft int
  34 .Fn feraiseexcept "int excepts"
  35 .Ft int
  36 .Fn fesetexceptflag "const fexcept_t *flagp" "int excepts"
  37 .Ft int
  38 .Fn fetestexcept "int excepts"
  39 .Sh DESCRIPTION
  40 These functions provide access to the floating-point status flags.
  41 The
  42 .Fa excepts
  43 input argument is a bitmask specifying an exception type and
  44 containing any of the values listed below.
  45 .Bl -tag -width ".Dv FE_DIVBYZERO"
  46 .It Dv FE_DIVBYZERO
  47 A divide-by-zero exception occurs when the program attempts to
  48 divide a finite non-zero number by zero.
  49 .It Dv FE_INEXACT
  50 An inexact exception is raised whenever there is a loss of precision
  51 due to rounding.
  52 .It Dv FE_INVALID
  53 Invalid operation exceptions occur when a program attempts to
  54 perform calculations for which there is no reasonable representable
  55 answer.
  56 .Pp
  57 For instance, subtraction of infinities, division of zero by zero,
  58 ordered comparison involving \*(Nas, and taking the square root of a
  59 negative number are all invalid operations.
  60 .It Dv FE_OVERFLOW
  61 An overflow exception occurs when the magnitude of the result of a
  62 computation is too large to fit in the destination type.
  63 .It Dv FE_UNDERFLOW
  64 Underflow occurs when the result of a computation is too close to zero
  65 to be represented as a non-zero value in the destination type.
  66 .It Dv FE_DENORMAL
  67 Denormalization exception occurs when the result of a floating-point
  68 expression is a denormalized number.
  69 .Pp
  70 This is available only on the floating-point implementations of
  71 amd64 and i386 processors.
  72 .El
  73 .Pp
  74 Additionally, the macro
  75 .Dv FE_ALL_EXCEPT
  76 is simply the bitwise OR of all floating-point exception macros
  77 listed above.
  78 .Pp
  79 The
  80 .Fn feclearexcept
  81 function clears the floating-point exceptions represented by
  82 .Fa excepts .
  83 .Pp
  84 The
  85 .Fn fegetexceptflag
  86 function stores a representation of the states of the floating-point
  87 flags indicated by
  88 .Pa excepts
  89 in the object pointed to by
  90 .Pa flagp .
  91 .Pp
  92 The
  93 .Fn feraiseexcept
  94 function raises floating-point exceptions represented by
  95 .Pa excepts .
  96 .Pp
  97 The
  98 .Fn fesetexceptflag
  99 function sets the floating-point status flags indicated by
 100 .Pa excepts
 101 to the states stored in the object pointed to by
 102 .Pa flagp .
 103 The value of
 104 .Pa flagp
 105 shall have been set by a previous call to
 106 .Fn fegetexceptflag
 107 whose second argument represented at least those floating-point
 108 exceptions represented by
 109 .Pa excepts .
 110 This function does not raise floating-point exceptions, but only
 111 sets the state of the flags.
 112 .Pp
 113 The
 114 .Fn fetesteexcept
 115 function determines which of a specified subset of the floating-point
 116 exception flags are currently set.
 117 The
 118 .Pa excepts
 119 specifies the floating-point status flags to be queried.
 120 .Sh RETURN VALUES
 121 The
 122 .Fn feclearexcept ,
 123 .Fn fegetexceptflag ,
 124 .Fn feraiseexcept ,
 125 and
 126 .Fn fesetexceptflag
 127 functions return zero on success, and non-zero if an error occurred.
 128 The
 129 .Fn fetestexcept
 130 function returns a bitmask of a specified subset of the floating-point
 131 exception flags which are currently set.
 132 .Sh SEE ALSO
 133 .Xr feenableexcept 3 ,
 134 .Xr fegetenv 3 ,
 135 .Xr fegetround 3
 136 .Sh STANDARDS
 137 The
 138 .Fn feclearexcept ,
 139 .Fn fegetexceptflag ,
 140 .Fn feraiseexcept ,
 141 .Fn fesetexceptflag ,
 142 and
 143 .Fn fetestexcept
 144 functions conform to
 145 .St -isoC-99 .
 146 .Pp
 147 The return types for
 148 .Fn feclearexcept ,
 149 .Fn fegetexceptflag ,
 150 .Fn feraiseexcept ,
 151 and
 152 .Fn fesetexceptflag
 153 are
 154 .Vt int
 155 for alignment with
 156 .St -isoC-99
 157 Defect Report #202.
 158 .Sh HISTORY
 159 These functions first appeared in
 160 .Ox 5.0 .
 161 .Sh CAVEATS
 162 On some architectures,
 163 .Fn feraiseexcept
 164 additionally raises the
 165 .Dq inexact
 166 floating-point exception whenever it raises the
 167 .Dq overflow
 168 or
 169 .Dq underflow
 170 floating-point exception.