diff --git a/lib/msun/man/feclearexcept.3 b/lib/msun/man/feclearexcept.3 new file mode 100644 index 000000000000..67c4341e98f9 --- /dev/null +++ b/lib/msun/man/feclearexcept.3 @@ -0,0 +1,137 @@ +.\" Copyright (c) 2004 David Schultz +.\" 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$ +.\" +.Dd May 8, 2004 +.Dt FECLEAREXCEPT 3 +.Os +.Sh NAME +.Nm feclearexcept , +.Nm fegetexceptflag , +.Nm feraiseexcept , +.Nm fesetexceptflag , +.Nm fetestexcept +.Nd floating-point exception flag manipulation +.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" +.Sh DESCRIPTION +The +.Fn feclearexcept +routine clears the floating-point exception flags specified by +.Fa excepts , +whereas +.Fn feraiseexcept +raises the specified exceptions. +Raising an exception causes the corresponding flag to be set, +and a SIGFPE is delivered to the process if the exception is unmasked. +.Pp +The +.Fn fetestexcept +function determines which flags are currently set, of those specified by +.Fa excepts . +.Pp +The +.Fn fegetexceptflag +function stores the state of the exception flags specified in +.Fa excepts +in the opaque object pointed to by +.Fa flagp . +Similarly, +.Fn fesetexceptflag +changes the specified exception flags to reflect the state stored in +the object pointed to by +.Fa flagp . +Note that the flags restored with +.Fn fesetexceptflag +must be a (not necessarily proper) subset of the flags recorded by +a prior call to +.Fn fegetexceptflag . +.Pp +For all of these functions, the possible types of exceptions +include those described in +.Xr fenv 3 . +Some architectures may define other types of floating-point exceptions. +.Sh IMPLEMENTATION NOTES +On some architectures, raising an overflow or underflow exception +also causes an inexact exception to be raised. +In these cases, the overflow or underflow will be raised first. +.Pp +The +.Fn fegetexceptflag +and +.Fn fesetexceptflag +routines are preferred to +.Fn fetestexcept +and +.Fn feraiseexcept , +respectively, for saving and restoring exception flags. +The latter do not re-raise exceptions and may preserve +architecture-specific information such as addresses where +exceptions occurred. +.Sh RETURN VALUES +The +.Fn feclearexcept , +.Fn fegetexceptflag , +.Fn feraiseexcept , +and +.Fn fesetexceptflag +functions return 0 upon success, and non-zero otherwise. +The +.Fn fetestexcept +function returns the bitwise OR of the values of the current exception +flags that were requested. +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr feholdexcept 3 , +.Xr fenv 3 , +.Xr feupdateenv 3 , +.Xr fpgetsticky 3 , +.Xr fpresetsticky 3 +.Sh STANDARDS +The +.Fn feclearexcept , +.Fn fegetexceptflag , +.Fn feraiseexcept , +.Fn fesetexceptflag , +and +.Fn fetestexcept +routines conform to +.St -isoC-99 . +.Sh HISTORY +These functions first appeared in +.Fx 5.3 . diff --git a/lib/msun/man/fegetenv.3 b/lib/msun/man/fegetenv.3 new file mode 100644 index 000000000000..c99663ed1a4b --- /dev/null +++ b/lib/msun/man/fegetenv.3 @@ -0,0 +1,113 @@ +.\" Copyright (c) 2004 David Schultz +.\" 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$ +.\" +.Dd May 8, 2004 +.Dt FEGETENV 3 +.Os +.Sh NAME +.Nm fegetenv , +.Nm feholdexcept , +.Nm fesetenv , +.Nm feupdateenv +.Nd floating-point environment save and restore +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In fenv.h +.Fd "#pragma STDC FENV_ACCESS ON" +.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" +.Sh DESCRIPTION +The floating-point environment includes exception flags and masks, the +current rounding mode, and other architecture-specific settings. +However, it does not include the floating-point register file. +.Pp +The +.Fn fegetenv +function stores the current floating-point environment in the object +pointed to by +.Fa envp , +whereas +.Fn feholdexcept +saves the current environment, then clears all exception flags +and masks all floating-point exceptions. +.Pp +The +.Fn fesetenv +function restores a previously saved environment. +The +.Fn feupdateenv +function restores a saved environment as well, but it also +raises any exceptions that were set in the environment it +replaces. +.Pp +The +.Fn feholdexcept +function is often used with +.Fn feupdateenv +or +.Fn fesetenv +to suppress spurious exceptions that occur as a result of +intermediate computations. +An example in +.Xr fenv 3 +demonstrates how to do this. +.Sh RETURN VALUES +The +.Fn fegetenv , +.Fn feholdexcept , +.Fn fesetenv , +and +.Fn feupdateenv +functions return 0 if they succeed, and non-zero otherwise. +.Sh SEE ALSO +.Xr feclearexcept 3 , +.Xr fenv 3 , +.Xr feraiseexcept 3 , +.Xr fesetenv 3 , +.Xr fetestexcept 3 , +.Xr fpgetmask 3 , +.Xr fpgetprec 3 , +.Xr fpsetmask 3 , +.Xr fpsetprec 3 +.Sh STANDARDS +The +.Fn fegetenv , +.Fn feholdexcept , +.Fn fesetenv , +and +.Fn feupdateenv +functions conform to +.St -isoC-99 . +.Sh HISTORY +These routines first appeared in +.Fx 5.3 . diff --git a/lib/msun/man/fegetround.3 b/lib/msun/man/fegetround.3 new file mode 100644 index 000000000000..1461c83cca87 --- /dev/null +++ b/lib/msun/man/fegetround.3 @@ -0,0 +1,85 @@ +.\" Copyright (c) 2004 David Schultz +.\" 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$ +.\" +.Dd May 8, 2004 +.Dt FEGETROUND 3 +.Os +.Sh NAME +.Nm fegetround , +.Nm fesetround +.Nd floating-point rounding control +.Sh LIBRARY +.Lb libm +.Sh SYNOPSIS +.In fenv.h +.Fd "#pragma STDC FENV_ACCESS ON" +.Ft int +.Fn fegetround "void" +.Ft int +.Fn fesetround "int round" +.Sh DESCRIPTION +The +.Fn fegetround +function determines the current floating-point rounding mode, +and the +.Fn fesetround +function sets the current rounding mode to +.Fa round . +The rounding mode is one of +.Dv FE_TONEAREST , +.Dv FE_DOWNWARD , +.Dv FE_UPWARD , +or +.Dv FE_TOWARDZERO , +as described in +.Xr fenv 3 . +.Sh RETURN VALUES +The +.Fn fegetround +routine returns the current rounding mode. +The +.Fn fesetround +function returns 0 on success and non-zero otherwise; +however, the present implementation always succeeds. +.Sh SEE ALSO +.Xr fenv 3 , +.Xr fpgetround 3 , +.Xr fpsetround 3 +.Sh STANDARDS +The +.Fn fegetround +and +.Fn fesetround +functions conform to +.St -isoC-99 . +.Sh HISTORY +These routines first appeared in +.Fx 5.3 . +They supersede the non-standard +.Xr fpgetround 3 +and +.Xr fpsetround 3 +functions. diff --git a/lib/msun/man/fenv.3 b/lib/msun/man/fenv.3 new file mode 100644 index 000000000000..336bbc0a86b2 --- /dev/null +++ b/lib/msun/man/fenv.3 @@ -0,0 +1,266 @@ +.\" Copyright (c) 2004 David Schultz +.\" 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$ +.\" +.Dd May 8, 2004 +.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 +.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" +.Sh DESCRIPTION +The fenv 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 +.Na +s, 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. +.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 fegetenv 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 fpgetmask 3 , +.Xr fpgetprec 3 , +.Xr fpgetsticky 3 , +.Xr fpgetround 3 , +.Xr fpresetsticky 3 , +.Xr fpsetmask 3 , +.Xr fpsetprec 3 , +.Xr fpsetround 3 +.Sh STANDARDS +Except as noted below, +.In fenv.h +conforms to +.St -isoC-99 . +.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.