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: head/lib/msun/man/fenv.3 226618 2011-10-21 14:23:59Z das $
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
96 result of a computation is infinite (according to the limit definition).
97 For example, dividing a finite non-zero number by zero or computing
99 raises a divide-by-zero exception.
101 An inexact exception is raised whenever there is a loss of accuracy
104 Invalid operation exceptions occur when a program attempts to
105 perform calculations for which there is no reasonable representable
107 For instance, subtraction of like-signed infinities, division of zero by zero,
108 ordered comparison involving \*(Nas, and taking the real square root of a
109 negative number are all invalid operations.
111 In contrast with divide-by-zero,
112 an overflow exception occurs when an infinity is produced because
113 the magnitude of the exact result is
115 but too large to fit in the destination type.
116 For example, computing
118 raises an overflow exception.
120 Underflow occurs when the result of a computation loses precision
121 because it is too close to zero.
122 The result is a subnormal number or zero.
127 macro expands to the bitwise OR of the above flags and any
128 architecture-specific flags.
129 Combinations of these flags are passed to the
131 .Fn fegetexceptflag ,
133 .Fn fesetexceptflag ,
136 functions to clear, save, raise, restore, and examine the
137 processor's floating-point exception flags, respectively.
144 .Fn fedisableexcept .
145 Unmasked exceptions cause a trap when they are produced, and
146 all exceptions are masked by default.
147 The current mask can be tested with
151 specifies four rounding modes.
152 These modes control the direction in which results are rounded
153 from their exact values in order to fit them into binary
154 floating-point variables.
155 The four modes correspond with the following symbolic constants.
156 .Bl -tag -width ".Dv FE_TOWARDZERO"
158 Results are rounded to the closest representable value.
159 If the exact result is exactly half way between two representable
160 values, the value whose last binary digit is even (zero) is chosen.
161 This is the default mode.
163 Results are rounded towards negative \*[If].
165 Results are rounded towards positive \*[If].
167 Results are rounded towards zero.
174 functions query and set the rounding mode.
175 .Ss Environment Control
180 functions save and restore the floating-point environment,
181 which includes exception flags, the current exception mask,
182 the rounding mode, and possibly other implementation-specific
186 function behaves like
188 but with the additional effect of clearing the exception flags and
192 In non-stop mode, floating-point operations will set exception flags
195 signals will be generated as a result.
196 Non-stop mode is the default, but it may be altered by
199 .Fn fedisableexcept .
202 function restores a saved environment similarly to
204 but it also re-raises any floating-point exceptions from the old
209 expands to a pointer to the default environment.
211 The following routine computes the square root function.
212 It explicitly raises an invalid exception on appropriate inputs using
214 It also defers inexact exceptions while it computes intermediate
215 values, and then it allows an inexact exception to be raised only if
216 the final answer is inexact.
217 .Bd -literal -offset indent
218 #pragma STDC FENV_ACCESS ON
219 double sqrt(double n) {
223 if (isnan(n) || n < 0.0) {
224 feraiseexcept(FE_INVALID);
227 if (isinf(n) || n == 0.0)
230 while (fabs((x * x) - n) > DBL_EPSILON * 2 * x)
231 x = (x / 2) + (n / (2 * x));
233 feclearexcept(FE_INEXACT);
240 .Xr feclearexcept 3 ,
241 .Xr fedisableexcept 3 ,
242 .Xr feenableexcept 3 ,
245 .Xr fegetexceptflag 3 ,
248 .Xr feraiseexcept 3 ,
250 .Xr fesetexceptflag 3 ,
257 Except as noted below,
263 .Fn fedisableexcept ,
266 routines are extensions.
270 header first appeared in
272 It supersedes the non-standard routines defined in
277 The FENV_ACCESS pragma can be enabled with
278 .Dl "#pragma STDC FENV_ACCESS ON"
279 and disabled with the
280 .Dl "#pragma STDC FENV_ACCESS OFF"
282 This lexically-scoped annotation tells the compiler that the program
283 may access the floating-point environment, so optimizations that would
284 violate strict IEEE-754 semantics are disabled.
285 If execution reaches a block of code for which
287 is off, the floating-point environment will become undefined.
291 pragma is unimplemented in the system compiler.
292 However, non-constant expressions generally produce the correct
293 side-effects at low optimization levels.