1 .\" Copyright (c) 2004 David Schultz <das@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" $FreeBSD: src/lib/msun/man/fenv.3,v 1.6 2007/01/05 07:14:26 das Exp $
45 .Nd floating-point environment control
50 .Fd "#pragma STDC FENV_ACCESS ON"
52 .Fn feclearexcept "int excepts"
54 .Fn fegetexceptflag "fexcept_t *flagp" "int excepts"
56 .Fn feraiseexcept "int excepts"
58 .Fn fesetexceptflag "const fexcept_t *flagp" "int excepts"
60 .Fn fetestexcept "int excepts"
64 .Fn fesetround "int round"
66 .Fn fegetenv "fenv_t *envp"
68 .Fn feholdexcept "fenv_t *envp"
70 .Fn fesetenv "const fenv_t *envp"
72 .Fn feupdateenv "const fenv_t *envp"
74 .Fn feenableexcept "int excepts"
76 .Fn fedisableexcept "int excepts"
82 routines manipulate the floating-point environment,
83 which includes the exception flags and rounding modes defined in
86 Exception flags are set as side-effects of floating-point arithmetic
87 operations and math library routines, and they remain set until
89 The following macros expand to bit flags of type
91 representing the five standard floating-point exceptions.
92 .Bl -tag -width ".Dv FE_DIVBYZERO"
94 A divide-by-zero exception occurs when the program attempts to
95 divide a finite non-zero number by zero.
97 An inexact exception is raised whenever there is a loss of precision
100 Invalid operation exceptions occur when a program attempts to
101 perform calculations for which there is no reasonable representable
103 For instance, subtraction of infinities, division of zero by zero,
104 ordered comparison involving \*(Nas, and taking the square root of a
105 negative number are all invalid operations.
107 An overflow exception occurs when the magnitude of the result of a
108 computation is too large to fit in the destination type.
110 Underflow occurs when the result of a computation is too close to zero
111 to be represented as a non-zero value in the destination type.
116 macro expands to the bitwise OR of the above flags and any
117 architecture-specific flags.
118 Combinations of these flags are passed to the
120 .Fn fegetexceptflag ,
122 .Fn fesetexceptflag ,
125 functions to clear, save, raise, restore, and examine the
126 processor's floating-point exception flags, respectively.
133 .Fn fedisableexcept .
134 Unmasked exceptions cause a trap when they are produced, and
135 all exceptions are masked by default.
136 The current mask can be tested with
140 specifies four rounding modes.
141 These modes control the direction in which results are rounded
142 from their exact values in order to fit them into binary
143 floating-point variables.
144 The four modes correspond with the following symbolic constants.
145 .Bl -tag -width ".Dv FE_TOWARDZERO"
147 Results are rounded to the closest representable value.
148 If the exact result is exactly half way between two representable
149 values, the value whose last binary digit is even (zero) is chosen.
150 This is the default mode.
152 Results are rounded towards negative \*[If].
154 Results are rounded towards positive \*[If].
156 Results are rounded towards zero.
163 functions query and set the rounding mode.
164 .Ss Environment Control
169 functions save and restore the floating-point environment,
170 which includes exception flags, the current exception mask,
171 the rounding mode, and possibly other implementation-specific
175 function behaves like
177 but with the additional effect of clearing the exception flags and
181 In non-stop mode, floating-point operations will set exception flags
184 signals will be generated as a result.
185 Non-stop mode is the default, but it may be altered by
186 non-standard mechanisms.
187 .\" XXX Mention fe[gs]etmask() here after the interface is finalized
188 .\" XXX and ready to be officially documented.
191 function restores a saved environment similarly to
193 but it also re-raises any floating-point exceptions from the old
198 expands to a pointer to the default environment.
200 The FENV_ACCESS pragma can be enabled with
201 .Dl "#pragma STDC FENV_ACCESS ON"
202 and disabled with the
203 .Dl "#pragma STDC FENV_ACCESS OFF"
205 This lexically-scoped annotation tells the compiler that the program
206 may access the floating-point environment, so optimizations that would
207 violate strict IEEE-754 semantics are disabled.
208 If execution reaches a block of code for which
210 is off, the floating-point environment will become undefined.
212 The following routine computes the square root function.
213 It explicitly raises an invalid exception on appropriate inputs using
215 It also defers inexact exceptions while it computes intermediate
216 values, and then it allows an inexact exception to be raised only if
217 the final answer is inexact.
218 .Bd -literal -offset indent
219 #pragma STDC FENV_ACCESS ON
220 double sqrt(double n) {
224 if (isnan(n) || n < 0.0) {
225 feraiseexcept(FE_INVALID);
228 if (isinf(n) || n == 0.0)
231 while (fabs((x * x) - n) > DBL_EPSILON * 2 * x)
232 x = (x / 2) + (n / (2 * x));
234 feclearexcept(FE_INEXACT);
241 .Xr feclearexcept 3 ,
242 .Xr fedisableexcept 3 ,
243 .Xr feenableexcept 3 ,
246 .Xr fegetexceptflag 3 ,
249 .Xr feraiseexcept 3 ,
251 .Xr fesetexceptflag 3 ,
258 Except as noted below,
264 .Fn fedisableexcept ,
267 routines are extensions.
271 header first appeared in
273 It supersedes the non-standard routines defined in
280 pragma is unimplemented in the system compiler.
281 However, non-constant expressions generally produce the correct
282 side-effects at low optimization levels.