diff options
Diffstat (limited to 'libm/man/fenv.3')
| -rw-r--r-- | libm/man/fenv.3 | 289 |
1 files changed, 289 insertions, 0 deletions
diff --git a/libm/man/fenv.3 b/libm/man/fenv.3 new file mode 100644 index 0000000..33ad541 --- /dev/null +++ b/libm/man/fenv.3 @@ -0,0 +1,289 @@ +.\" Copyright (c) 2004 David Schultz <das@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/lib/msun/man/fenv.3,v 1.5 2005/06/15 19:04:04 ru Exp $ +.\" +.Dd March 16, 2005 +.Dt FENV 3 +.Os +.Sh NAME +.Nm feclearexcept , +.Nm fegetexceptflag , +.Nm feraiseexcept , +.Nm fesetexceptflag , +.Nm fetestexcept , +.Nm fegetround , +.Nm fesetround , +.Nm fegetenv , +.Nm feholdexcept , +.Nm fesetenv , +.Nm feupdateenv , +.Nm feenableexcept , +.Nm fedisableexcept , +.Nm fegetexcept +.Nd floating-point environment control +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In fenv.h +.Fd "#pragma STDC FENV_ACCESS ON" +.Ft int +.Fn feclearexcept "int excepts" +.Ft int +.Fn fegetexceptflag "fexcept_t *flagp" "int excepts" +.Ft int +.Fn feraiseexcept "int excepts" +.Ft int +.Fn fesetexceptflag "const fexcept_t *flagp" "int excepts" +.Ft int +.Fn fetestexcept "int excepts" +.Ft int +.Fn fegetround void +.Ft int +.Fn fesetround "int round" +.Ft int +.Fn fegetenv "fenv_t *envp" +.Ft int +.Fn feholdexcept "fenv_t *envp" +.Ft int +.Fn fesetenv "const fenv_t *envp" +.Ft int +.Fn feupdateenv "const fenv_t *envp" +.Ft int +.Fn feenableexcept "int excepts" +.Ft int +.Fn fedisableexcept "int excepts" +.Ft int +.Fn fegetexcept void +.Sh DESCRIPTION +The +.In fenv.h +routines manipulate the floating-point environment, +which includes the exception flags and rounding modes defined in +.St -ieee754 . +.Ss Exceptions +Exception flags are set as side-effects of floating-point arithmetic +operations and math library routines, and they remain set until +explicitly cleared. +The following macros expand to bit flags of type +.Vt int +representing the five standard floating-point exceptions. +.Bl -tag -width ".Dv FE_DIVBYZERO" +.It Dv FE_DIVBYZERO +A divide-by-zero exception occurs when the program attempts to +divide a finite non-zero number by zero. +.It Dv FE_INEXACT +An inexact exception is raised whenever there is a loss of precision +due to rounding. +.It Dv FE_INVALID +Invalid operation exceptions occur when a program attempts to +perform calculations for which there is no reasonable representable +answer. +For instance, subtraction of infinities, division of zero by zero, +ordered comparison involving \*(Nas, and taking the square root of a +negative number are all invalid operations. +.It Dv FE_OVERFLOW +An overflow exception occurs when the magnitude of the result of a +computation is too large to fit in the destination type. +.It Dv FE_UNDERFLOW +Underflow occurs when the result of a computation is too close to zero +to be represented as a non-zero value in the destination type. +.El +.Pp +Additionally, the +.Dv FE_ALL_EXCEPT +macro expands to the bitwise OR of the above flags and any +architecture-specific flags. +Combinations of these flags are passed to the +.Fn feclearexcept , +.Fn fegetexceptflag , +.Fn feraiseexcept , +.Fn fesetexceptflag , +and +.Fn fetestexcept +functions to clear, save, raise, restore, and examine the +processor's floating-point exception flags, respectively. +.Pp +Exceptions may be +.Em unmasked +with +.Fn feenableexcept +and masked with +.Fn fedisableexcept . +Unmasked exceptions cause a trap when they are produced, and +all exceptions are masked by default. +The current mask can be tested with +.Fn fegetexcept . +.Ss Rounding Modes +.St -ieee754 +specifies four rounding modes. +These modes control the direction in which results are rounded +from their exact values in order to fit them into binary +floating-point variables. +The four modes correspond with the following symbolic constants. +.Bl -tag -width ".Dv FE_TOWARDZERO" +.It Dv FE_TONEAREST +Results are rounded to the closest representable value. +If the exact result is exactly half way between two representable +values, the value whose last binary digit is even (zero) is chosen. +This is the default mode. +.It Dv FE_DOWNWARD +Results are rounded towards negative \*[If]. +.It Dv FE_UPWARD +Results are rounded towards positive \*[If]. +.It Dv FE_TOWARDZERO +Results are rounded towards zero. +.El +.Pp +The +.Fn fegetround +and +.Fn fesetround +functions query and set the rounding mode. +.Ss Environment Control +The +.Fn fegetenv +and +.Fn fesetenv +functions save and restore the floating-point environment, +which includes exception flags, the current exception mask, +the rounding mode, and possibly other implementation-specific +state. +The +.Fn feholdexcept +function behaves like +.Fn fegetenv , +but with the additional effect of clearing the exception flags and +installing a +.Em non-stop +mode. +In non-stop mode, floating-point operations will set exception flags +as usual, but no +.Dv SIGFPE +signals will be generated as a result. +Non-stop mode is the default, but it may be altered by +non-standard mechanisms. +.\" XXX Mention fe[gs]etmask() here after the interface is finalized +.\" XXX and ready to be officially documented. +The +.Fn feupdateenv +function restores a saved environment similarly to +.Fn fesetenv , +but it also re-raises any floating-point exceptions from the old +environment. +.Pp +The macro +.Dv FE_DFL_ENV +expands to a pointer to the default environment. +.Sh CAVEATS +The FENV_ACCESS pragma can be enabled with +.Dl "#pragma STDC FENV_ACCESS ON" +and disabled with the +.Dl "#pragma STDC FENV_ACCESS OFF" +directive. +This lexically-scoped annotation tells the compiler that the program +may access the floating-point environment, so optimizations that would +violate strict IEEE-754 semantics are disabled. +If execution reaches a block of code for which +.Dv FENV_ACCESS +is off, the floating-point environment will become undefined. +.Sh EXAMPLES +The following routine computes the square root function. +It explicitly raises an invalid exception on appropriate inputs using +.Fn feraiseexcept . +It also defers inexact exceptions while it computes intermediate +values, and then it allows an inexact exception to be raised only if +the final answer is inexact. +.Bd -literal -offset indent +#pragma STDC FENV_ACCESS ON +double sqrt(double n) { + double x = 1.0; + fenv_t env; + + if (isnan(n) || n < 0.0) { + feraiseexcept(FE_INVALID); + return (NAN); + } + if (isinf(n) || n == 0.0) + return (n); + feholdexcept(&env); + while (fabs((x * x) - n) > DBL_EPSILON * 2 * x) + x = (x / 2) + (n / (2 * x)); + if (x * x == n) + feclearexcept(FE_INEXACT); + feupdateenv(&env); + return (x); +} +.Ed +.Sh SEE ALSO +.Xr cc 1 , +.Xr feclearexcept 3 , +.Xr fedisableexcept 3 , +.Xr feenableexcept 3 , +.Xr fegetenv 3 , +.Xr fegetexcept 3 , +.Xr fegetexceptflag 3 , +.Xr fegetround 3 , +.Xr feholdexcept 3 , +.Xr feraiseexcept 3 , +.Xr fesetenv 3 , +.Xr fesetexceptflag 3 , +.Xr fesetround 3 , +.Xr fetestexcept 3 , +.Xr feupdateenv 3 , +.Xr fpgetprec 3 , +.Xr fpsetprec 3 +.Sh STANDARDS +Except as noted below, +.In fenv.h +conforms to +.St -isoC-99 . +The +.Fn feenableexcept , +.Fn fedisableexcept , +and +.Fn fegetexcept +routines are extensions. +.Sh HISTORY +The +.In fenv.h +header first appeared in +.Fx 5.3 . +It supersedes the non-standard routines defined in +.In ieeefp.h +and documented in +.Xr fpgetround 3 . +.Sh BUGS +The +.Dv FENV_ACCESS +pragma is unimplemented in the system compiler. +However, non-constant expressions generally produce the correct +side-effects at low optimization levels. +.Pp +On the Alpha platform, +.Xr cc 1 +must be passed the +.Fl mieee-with-inexact mfp-rounding-mode=d +options in order to generate code that has the standard +side-effects and uses the specified rounding modes. |