mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-08 09:39:38 +00:00
- Move the functions presently described in in ieee(3) to their own
manpages. They are not very related, so separating them makes it easier to add meaningful cross-references and extend some of the descriptions. - Move the part of math(3) that discusses IEEE 754 to the ieee(3) manpage.
This commit is contained in:
David Schultz
parent
2380daafe9
commit
29bf6af890
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=140890
@ -76,7 +76,8 @@ MLINKS+=err.3 err_set_exit.3 err.3 err_set_file.3 err.3 errc.3 err.3 errx.3 \
|
||||
err.3 vwarnx.3 err.3 warnc.3 err.3 warn.3 err.3 warnx.3
|
||||
MLINKS+=exec.3 execl.3 exec.3 execle.3 exec.3 execlp.3 exec.3 exect.3 \
|
||||
exec.3 execv.3 exec.3 execvp.3
|
||||
MLINKS+=fpclassify.3 isfinite.3 fpclassify.3 isinf.3 fpclassify.3 isnan.3 \
|
||||
MLINKS+=fpclassify.3 finite.3 fpclassify.3 finitef.3 \
|
||||
fpclassify.3 isfinite.3 fpclassify.3 isinf.3 fpclassify.3 isnan.3 \
|
||||
fpclassify.3 isnormal.3
|
||||
MLINKS+=fts.3 fts_children.3 fts.3 fts_close.3 fts.3 fts_open.3 \
|
||||
fts.3 fts_read.3 fts.3 fts_set.3
|
||||
|
||||
@ -24,7 +24,7 @@
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd July 8, 2004
|
||||
.Dd January 26, 2005
|
||||
.Dt FPCLASSIFY 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
@ -92,6 +92,12 @@ The symbol
|
||||
is provided as an alias to
|
||||
.Fn isnan
|
||||
for compatibility, and its use is deprecated.
|
||||
Similarly,
|
||||
.Fn finite
|
||||
and
|
||||
.Fn finitef
|
||||
are deprecated versions of
|
||||
.Fn isfinite .
|
||||
.Sh SEE ALSO
|
||||
.Xr isgreater 3 ,
|
||||
.Xr math 3 ,
|
||||
|
||||
@ -140,11 +140,11 @@ SRCS= ${COMMON_SRCS} ${ARCH_SRCS}
|
||||
INCS= fenv.h math.h
|
||||
|
||||
MAN= acos.3 acosh.3 asin.3 asinh.3 atan.3 atan2.3 atanh.3 ceil.3 \
|
||||
cimag.3 cos.3 cosh.3 erf.3 exp.3 fabs.3 fdim.3 feclearexcept.3 \
|
||||
fegetenv.3 fegetround.3 fenv.3 floor.3 \
|
||||
fma.3 fmax.3 fmod.3 hypot.3 ieee.3 \
|
||||
ieee_test.3 j0.3 lgamma.3 lrint.3 lround.3 math.3 rint.3 round.3 \
|
||||
signbit.3 sin.3 sinh.3 sqrt.3 tan.3 tanh.3 trunc.3
|
||||
cimag.3 copysign.3 cos.3 cosh.3 erf.3 exp.3 fabs.3 fdim.3 \
|
||||
feclearexcept.3 fegetenv.3 fegetround.3 fenv.3 floor.3 \
|
||||
fma.3 fmax.3 fmod.3 hypot.3 ieee.3 ieee_test.3 ilogb.3 j0.3 \
|
||||
lgamma.3 lrint.3 lround.3 math.3 nextafter.3 remainder.3 rint.3 \
|
||||
round.3 scalbn.3 signbit.3 sin.3 sinh.3 sqrt.3 tan.3 tanh.3 trunc.3
|
||||
|
||||
MLINKS+=acos.3 acosf.3
|
||||
MLINKS+=acosh.3 acoshf.3
|
||||
@ -157,6 +157,7 @@ MLINKS+=ceil.3 ceilf.3 ceil.3 ceill.3
|
||||
MLINKS+=cimag.3 cimagf.3 cimag.3 cimagl.3 \
|
||||
cimag.3 conj.3 cimag.3 conjf.3 cimag.3 conjl.3 \
|
||||
cimag.3 creal.3 cimag.3 crealf.3 cimag.3 creall.3
|
||||
MLINKS+=copysign.3 copysignf.3 copysign.3 copysignl.3
|
||||
MLINKS+=cos.3 cosf.3
|
||||
MLINKS+=cosh.3 coshf.3
|
||||
MLINKS+=erf.3 erfc.3 erf.3 erff.3 erf.3 erfcf.3
|
||||
@ -177,22 +178,20 @@ MLINKS+=fmax.3 fmaxf.3 fmax.3 fmaxl.3 \
|
||||
fmax.3 fmin.3 fmax.3 fminf.3 fmax.3 fminl.3
|
||||
MLINKS+=fmod.3 fmodf.3
|
||||
MLINKS+=hypot.3 cabs.3 hypot.3 cabsf.3 hypot.3 hypotf.3
|
||||
MLINKS+=ieee.3 copysign.3 ieee.3 copysignf.3 ieee.3 copysignl.3 \
|
||||
ieee.3 finite.3 ieee.3 finitef.3 \
|
||||
ieee.3 ilogb.3 ieee.3 ilogbf.3 ieee.3 ilogbl.3 \
|
||||
ieee.3 nextafter.3 ieee.3 nextafterf.3 \
|
||||
ieee.3 remainder.3 ieee.3 remainderf.3 \
|
||||
ieee.3 scalbln.3 ieee.3 scalblnf.3 ieee.3 scalbn.3 ieee.3 scalbnf.3
|
||||
MLINKS+=ieee_test.3 logb.3 ieee_test.3 logbf.3
|
||||
MLINKS+=ieee_test.3 scalb.3 ieee_test.3 scalbf.3
|
||||
MLINKS+=ieee_test.3 significand.3 ieee_test.3 significandf.3
|
||||
MLINKS+=ilogb.3 ilogbf.3 ilogb.3 ilogbl.3
|
||||
MLINKS+=j0.3 j1.3 j0.3 jn.3 j0.3 y0.3 j0.3 y1.3 j0.3 y1f.3 j0.3 yn.3
|
||||
MLINKS+=j0.3 j0f.3 j0.3 j1f.3 j0.3 jnf.3 j0.3 y0f.3 j0.3 ynf.3
|
||||
MLINKS+=lgamma.3 gamma.3 lgamma.3 gammaf.3 lgamma.3 lgammaf.3 lgamma.3 tgamma.3
|
||||
MLINKS+=lrint.3 llrint.3 lrint.3 llrintf.3 lrint.3 lrintf.3
|
||||
MLINKS+=lround.3 llround.3 lround.3 llroundf.3 lround.3 lroundf.3
|
||||
MLINKS+=nextafter.3 nextafterf.3
|
||||
MLINKS+=remainder.3 remainderf.3
|
||||
MLINKS+=rint.3 rintf.3 rint.3 nearbyint.3 rint.3 nearbyintf.3
|
||||
MLINKS+=round.3 roundf.3
|
||||
MLINKS+=scalbn.3 scalbln.3 scalbn.3 scalblnf.3 scalbn.3 scalbnf.3
|
||||
MLINKS+=sin.3 sinf.3
|
||||
MLINKS+=sinh.3 sinhf.3
|
||||
MLINKS+=sqrt.3 cbrt.3 sqrt.3 cbrtf.3 sqrt.3 sqrtf.3
|
||||
|
||||
90
lib/msun/man/copysign.3
Normal file
90
lib/msun/man/copysign.3
Normal file
@ -0,0 +1,90 @@
|
||||
.\" Copyright (c) 1985, 1991 Regents of the University of California.
|
||||
.\" 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.
|
||||
.\" 3. All advertising materials mentioning features or use of this software
|
||||
.\" must display the following acknowledgement:
|
||||
.\" This product includes software developed by the University of
|
||||
.\" California, Berkeley and its contributors.
|
||||
.\" 4. Neither the name of the University nor the names of its contributors
|
||||
.\" may be used to endorse or promote products derived from this software
|
||||
.\" without specific prior written permission.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
|
||||
.\"
|
||||
.\" from: @(#)ieee.3 6.4 (Berkeley) 5/6/91
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 26, 2005
|
||||
.Dt COPYSIGN 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm copysign ,
|
||||
.Nm copysignf ,
|
||||
.Nm copysignl
|
||||
.Nd copy sign
|
||||
.Sh LIBRARY
|
||||
.Lb libm
|
||||
.Sh SYNOPSIS
|
||||
.In math.h
|
||||
.Ft double
|
||||
.Fn copysign "double x" "double y"
|
||||
.Ft float
|
||||
.Fn copysignf "float x" "float y"
|
||||
.Ft long double
|
||||
.Fn copysignl "long double x" "long double y"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn copysign ,
|
||||
.Fn copysignf
|
||||
and
|
||||
.Fn copysignl
|
||||
functions
|
||||
return
|
||||
.Fa x
|
||||
with its sign changed to
|
||||
.Fa y Ns 's .
|
||||
.Sh SEE ALSO
|
||||
.Xr fabs 3 ,
|
||||
.Xr fdim 3 ,
|
||||
.Xr ieee 3 ,
|
||||
.Xr math 3
|
||||
.Sh STANDARDS
|
||||
The
|
||||
.Fn copysign ,
|
||||
.Fn copysignf ,
|
||||
and
|
||||
.Fn copysignl
|
||||
routines conform to
|
||||
.St -isoC-99 .
|
||||
They implement the Copysign function recommended by
|
||||
.St -ieee754 .
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Fn copysign ,
|
||||
.Fn copysignf ,
|
||||
and
|
||||
.Fn copysignl
|
||||
functions appeared in
|
||||
.Bx 4.3 ,
|
||||
.Fx 2.0 ,
|
||||
and
|
||||
.Fx 5.3 ,
|
||||
respectively.
|
||||
@ -1,4 +1,4 @@
|
||||
.\" Copyright (c) 1985, 1991 Regents of the University of California.
|
||||
.\" Copyright (c) 1985 Regents of the University of California.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
@ -32,181 +32,419 @@
|
||||
.\" from: @(#)ieee.3 6.4 (Berkeley) 5/6/91
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd June 20, 2004
|
||||
.Dd January 26, 2005
|
||||
.Dt IEEE 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm copysign ,
|
||||
.Nm copysignf ,
|
||||
.Nm copysignl ,
|
||||
.Nm finite ,
|
||||
.Nm finitef ,
|
||||
.Nm ilogb ,
|
||||
.Nm ilogbf ,
|
||||
.Nm ilogbl ,
|
||||
.Nm nextafter ,
|
||||
.Nm nextafterf ,
|
||||
.Nm remainder ,
|
||||
.Nm remainderf ,
|
||||
.Nm scalbln ,
|
||||
.Nm scalblnf ,
|
||||
.Nm scalbn ,
|
||||
.Nm scalbnf
|
||||
.Nd functions for IEEE arithmetic
|
||||
.Sh LIBRARY
|
||||
.Lb libm
|
||||
.Sh SYNOPSIS
|
||||
.In math.h
|
||||
.Ft double
|
||||
.Fn copysign "double x" "double y"
|
||||
.Ft float
|
||||
.Fn copysignf "float x" "float y"
|
||||
.Ft long double
|
||||
.Fn copysignl "long double x" "long double y"
|
||||
.Ft int
|
||||
.Fn finite "double x"
|
||||
.Ft int
|
||||
.Fn finitef "float x"
|
||||
.Ft int
|
||||
.Fn ilogb "double x"
|
||||
.Ft int
|
||||
.Fn ilogbf "float x"
|
||||
.Ft int
|
||||
.Fn ilogbl "long double x"
|
||||
.Ft double
|
||||
.Fn nextafter "double x" "double y"
|
||||
.Ft float
|
||||
.Fn nextafterf "float x" "float y"
|
||||
.Ft double
|
||||
.Fn remainder "double x" "double y"
|
||||
.Ft float
|
||||
.Fn remainderf "float x" "float y"
|
||||
.Ft double
|
||||
.Fn scalbln "double x" "long n"
|
||||
.Ft float
|
||||
.Fn scalblnf "float x" "long n"
|
||||
.Ft double
|
||||
.Fn scalbn "double x" "int n"
|
||||
.Ft float
|
||||
.Fn scalbnf "float x" "int n"
|
||||
.Nm ieee
|
||||
.Nd IEEE standard 754 for floating-point arithmetic
|
||||
.Sh DESCRIPTION
|
||||
These functions are required or recommended by
|
||||
.St -ieee754 .
|
||||
The IEEE Standard 754 for Binary Floating-Point Arithmetic
|
||||
defines representations of floating-point numbers and abstract
|
||||
properties of arithmetic operations relating to precision,
|
||||
rounding, and exceptional cases, as described below.
|
||||
.Ss IEEE STANDARD 754 Floating-Point Arithmetic
|
||||
Radix: Binary.
|
||||
.Pp
|
||||
The
|
||||
.Fn copysign ,
|
||||
.Fn copysignf
|
||||
and
|
||||
.Fn copysignl
|
||||
functions
|
||||
return
|
||||
.Fa x
|
||||
with its sign changed to
|
||||
.Fa y Ns 's .
|
||||
.Bl -column "" -compact
|
||||
Overflow and underflow:
|
||||
.El
|
||||
.Bd -ragged -offset indent -compact
|
||||
Overflow goes by default to a signed \*(If.
|
||||
Underflow is
|
||||
.Em gradual .
|
||||
.Ed
|
||||
.Pp
|
||||
.Fn finite
|
||||
and
|
||||
.Fn finitef
|
||||
return the value 1 just when
|
||||
\-\*(If \*(Lt
|
||||
.Fa x
|
||||
\*(Lt +\*(If;
|
||||
otherwise a
|
||||
zero is returned
|
||||
(when
|
||||
.Pf \\*(Ba Ns Fa x Ns \\*(Ba
|
||||
= \*(If or
|
||||
.Fa x
|
||||
is \*(Na).
|
||||
Zero is represented ambiguously as +0 or \-0.
|
||||
.Bd -ragged -offset indent -compact
|
||||
Its sign transforms correctly through multiplication or
|
||||
division, and is preserved by addition of zeros
|
||||
with like signs; but x\-x yields +0 for every
|
||||
finite x.
|
||||
The only operations that reveal zero's
|
||||
sign are division by zero and
|
||||
.Fn copysign x \(+-0 .
|
||||
In particular, comparison (x > y, x \(>= y, etc.)\&
|
||||
cannot be affected by the sign of zero; but if
|
||||
finite x = y then \*(If = 1/(x\-y) \(!= \-1/(y\-x) = \-\*(If.
|
||||
.Ed
|
||||
.Pp
|
||||
.Fn ilogb ,
|
||||
.Fn ilogbf
|
||||
and
|
||||
.Fn ilogbl
|
||||
return
|
||||
.Fa x Ns 's exponent,
|
||||
in integer format.
|
||||
.Fn ilogb \*(Pm\*(If
|
||||
returns
|
||||
.Dv INT_MAX ,
|
||||
.Fn ilogb \*(Pm\*(Na
|
||||
returns
|
||||
.Dv FP_ILOGBNAN
|
||||
and
|
||||
.Fn ilogb 0
|
||||
returns
|
||||
.Dv FP_ILOGB0 .
|
||||
.Pp
|
||||
.Fn nextafter
|
||||
and
|
||||
.Fn nextafterf
|
||||
return the next machine representable number from
|
||||
.Fa x
|
||||
in direction
|
||||
.Fa y .
|
||||
.Pp
|
||||
.Fn remainder
|
||||
and
|
||||
.Fn remainderf
|
||||
return the remainder
|
||||
.Fa r
|
||||
:=
|
||||
.Fa x
|
||||
\-
|
||||
.Fa n\(**y
|
||||
where
|
||||
.Fa n
|
||||
is the integer nearest the exact value of
|
||||
.Bk -words
|
||||
.Fa x Ns / Ns Fa y ;
|
||||
.Ek
|
||||
moreover if
|
||||
.Pf \\*(Ba Fa n
|
||||
\-
|
||||
.Sm off
|
||||
.Fa x No / Fa y No \\*(Ba
|
||||
.Sm on
|
||||
=
|
||||
1/2
|
||||
then
|
||||
.Fa n
|
||||
is even.
|
||||
Consequently
|
||||
the remainder is computed exactly and
|
||||
.Sm off
|
||||
.Pf \\*(Ba Fa r No \\*(Ba
|
||||
.Sm on
|
||||
\*(Le
|
||||
.Sm off
|
||||
.Pf \\*(Ba Fa y No \\*(Ba/2 .
|
||||
.Sm on
|
||||
Infinity is signed.
|
||||
.Bd -ragged -offset indent -compact
|
||||
It persists when added to itself
|
||||
or to any finite number.
|
||||
Its sign transforms
|
||||
correctly through multiplication and division, and
|
||||
(finite)/\(+-\*(If\0=\0\(+-0
|
||||
(nonzero)/0 = \(+-\*(If.
|
||||
But
|
||||
.Fn remainder x 0
|
||||
and
|
||||
.Fn remainder \*(If 0
|
||||
are invalid operations that produce a \*(Na.
|
||||
\*(If\-\*(If, \*(If\(**0 and \*(If/\*(If
|
||||
are, like 0/0 and sqrt(\-3),
|
||||
invalid operations that produce \*(Na. ...
|
||||
.Ed
|
||||
.Pp
|
||||
.Fn scalbln ,
|
||||
.Fn scalblnf ,
|
||||
.Fn scalbn ,
|
||||
Reserved operands (\*(Nas):
|
||||
.Bd -ragged -offset indent -compact
|
||||
An \*(Na is
|
||||
.Em ( N Ns ot Em a N Ns umber ) .
|
||||
Some \*(Nas, called Signaling \*(Nas, trap any floating-point operation
|
||||
performed upon them; they are used to mark missing
|
||||
or uninitialized values, or nonexistent elements
|
||||
of arrays.
|
||||
The rest are Quiet \*(Nas; they are
|
||||
the default results of Invalid Operations, and
|
||||
propagate through subsequent arithmetic operations.
|
||||
If x \(!= x then x is \*(Na; every other predicate
|
||||
(x > y, x = y, x < y, ...) is FALSE if \*(Na is involved.
|
||||
.Ed
|
||||
.Pp
|
||||
Rounding:
|
||||
.Bd -ragged -offset indent -compact
|
||||
Every algebraic operation (+, \-, \(**, /,
|
||||
\(sr)
|
||||
is rounded by default to within half an
|
||||
.Em ulp ,
|
||||
and when the rounding error is exactly half an
|
||||
.Em ulp
|
||||
then
|
||||
the rounded value's least significant bit is zero.
|
||||
(An
|
||||
.Em ulp
|
||||
is one
|
||||
.Em U Ns nit
|
||||
in the
|
||||
.Em L Ns ast
|
||||
.Em P Ns lace . )
|
||||
This kind of rounding is usually the best kind,
|
||||
sometimes provably so; for instance, for every
|
||||
x = 1.0, 2.0, 3.0, 4.0, ..., 2.0**52, we find
|
||||
(x/3.0)\(**3.0 == x and (x/10.0)\(**10.0 == x and ...
|
||||
despite that both the quotients and the products
|
||||
have been rounded.
|
||||
Only rounding like IEEE 754 can do that.
|
||||
But no single kind of rounding can be
|
||||
proved best for every circumstance, so IEEE 754
|
||||
provides rounding towards zero or towards
|
||||
+\*(If or towards \-\*(If
|
||||
at the programmer's option.
|
||||
.Ed
|
||||
.Pp
|
||||
Exceptions:
|
||||
.Bd -ragged -offset indent -compact
|
||||
IEEE 754 recognizes five kinds of floating-point exceptions,
|
||||
listed below in declining order of probable importance.
|
||||
.Bl -column -offset indent "Invalid Operation" "Gradual Underflow"
|
||||
.Em "Exception Default Result"
|
||||
Invalid Operation \*(Na, or FALSE
|
||||
Overflow \(+-\*(If
|
||||
Divide by Zero \(+-\*(If
|
||||
Underflow Gradual Underflow
|
||||
Inexact Rounded value
|
||||
.El
|
||||
.Pp
|
||||
NOTE: An Exception is not an Error unless handled
|
||||
badly.
|
||||
What makes a class of exceptions exceptional
|
||||
is that no single default response can be satisfactory
|
||||
in every instance.
|
||||
On the other hand, if a default
|
||||
response will serve most instances satisfactorily,
|
||||
the unsatisfactory instances cannot justify aborting
|
||||
computation every time the exception occurs.
|
||||
.Ed
|
||||
.Ss Data Formats
|
||||
Single-precision:
|
||||
.Bd -ragged -offset indent -compact
|
||||
Type name:
|
||||
.Vt float
|
||||
.Pp
|
||||
Wordsize: 32 bits.
|
||||
.Pp
|
||||
Precision: 24 significant bits,
|
||||
roughly like 7 significant decimals.
|
||||
.Bd -ragged -offset indent -compact
|
||||
If x and x' are consecutive positive single-precision
|
||||
numbers (they differ by 1
|
||||
.Em ulp ) ,
|
||||
then
|
||||
.Bd -ragged -compact
|
||||
5.9e\-08 < 0.5**24 < (x'\-x)/x \(<= 0.5**23 < 1.2e\-07.
|
||||
.Ed
|
||||
.Ed
|
||||
.Pp
|
||||
.Bl -column "XXX" -compact
|
||||
Range: Overflow threshold = 2.0**128 = 3.4e38
|
||||
Underflow threshold = 0.5**126 = 1.2e\-38
|
||||
.El
|
||||
.Bd -ragged -offset indent -compact
|
||||
Underflowed results round to the nearest
|
||||
integer multiple of 0.5**149 = 1.4e\-45.
|
||||
.Ed
|
||||
.Ed
|
||||
.Pp
|
||||
Double-precision:
|
||||
.Bd -ragged -offset indent -compact
|
||||
Type name:
|
||||
.Vt double
|
||||
.Bd -ragged -offset indent -compact
|
||||
On some architectures,
|
||||
.Vt long double
|
||||
is the the same as
|
||||
.Vt double .
|
||||
.Ed
|
||||
.Pp
|
||||
Wordsize: 64 bits.
|
||||
.Pp
|
||||
Precision: 53 significant bits,
|
||||
roughly like 16 significant decimals.
|
||||
.Bd -ragged -offset indent -compact
|
||||
If x and x' are consecutive positive double-precision
|
||||
numbers (they differ by 1
|
||||
.Em ulp ) ,
|
||||
then
|
||||
.Bd -ragged -compact
|
||||
1.1e\-16 < 0.5**53 < (x'\-x)/x \(<= 0.5**52 < 2.3e\-16.
|
||||
.Ed
|
||||
.Ed
|
||||
.Pp
|
||||
.Bl -column "XXX" -compact
|
||||
Range: Overflow threshold = 2.0**1024 = 1.8e308
|
||||
Underflow threshold = 0.5**1022 = 2.2e\-308
|
||||
.El
|
||||
.Bd -ragged -offset indent -compact
|
||||
Underflowed results round to the nearest
|
||||
integer multiple of 0.5**1074 = 4.9e\-324.
|
||||
.Ed
|
||||
.Ed
|
||||
.Pp
|
||||
Extended-precision:
|
||||
.Bd -ragged -offset indent -compact
|
||||
Type name:
|
||||
.Vt long double
|
||||
(when supported by the hardware)
|
||||
.Pp
|
||||
Wordsize: 96 bits.
|
||||
.Pp
|
||||
Precision: 64 significant bits,
|
||||
roughly like 19 significant decimals.
|
||||
.Bd -ragged -offset indent -compact
|
||||
If x and x' are consecutive positive double-precision
|
||||
numbers (they differ by 1
|
||||
.Em ulp ) ,
|
||||
then
|
||||
.Bd -ragged -compact
|
||||
1.0e\-19 < 0.5**63 < (x'\-x)/x \(<= 0.5**62 < 2.2e\-19.
|
||||
.Ed
|
||||
.Ed
|
||||
.Pp
|
||||
.Bl -column "XXX" -compact
|
||||
Range: Overflow threshold = 2.0**16384 = 1.2e4932
|
||||
Underflow threshold = 0.5**16382 = 3.4e\-4932
|
||||
.El
|
||||
.Bd -ragged -offset indent -compact
|
||||
Underflowed results round to the nearest
|
||||
integer multiple of 0.5**16451 = 5.7e\-4953.
|
||||
.Ed
|
||||
.Ed
|
||||
.Pp
|
||||
Quad-extended-precision:
|
||||
.Bd -ragged -offset indent -compact
|
||||
Type name:
|
||||
.Vt long double
|
||||
(when supported by the hardware)
|
||||
.Pp
|
||||
Wordsize: 128 bits.
|
||||
.Pp
|
||||
Precision: 113 significant bits,
|
||||
roughly like 34 significant decimals.
|
||||
.Bd -ragged -offset indent -compact
|
||||
If x and x' are consecutive positive double-precision
|
||||
numbers (they differ by 1
|
||||
.Em ulp ) ,
|
||||
then
|
||||
.Bd -ragged -compact
|
||||
9.6e\-35 < 0.5**113 < (x'\-x)/x \(<= 0.5**112 < 2.0e\-34.
|
||||
.Ed
|
||||
.Ed
|
||||
.Pp
|
||||
.Bl -column "XXX" -compact
|
||||
Range: Overflow threshold = 2.0**16384 = 1.2e4932
|
||||
Underflow threshold = 0.5**16382 = 3.4e\-4932
|
||||
.El
|
||||
.Bd -ragged -offset indent -compact
|
||||
Underflowed results round to the nearest
|
||||
integer multiple of 0.5**16494 = 6.5e\-4966.
|
||||
.Ed
|
||||
.Ed
|
||||
.Ss Additional Information Regarding Exceptions
|
||||
.Pp
|
||||
For each kind of floating-point exception, IEEE 754
|
||||
provides a Flag that is raised each time its exception
|
||||
is signaled, and stays raised until the program resets
|
||||
it.
|
||||
Programs may also test, save and restore a flag.
|
||||
Thus, IEEE 754 provides three ways by which programs
|
||||
may cope with exceptions for which the default result
|
||||
might be unsatisfactory:
|
||||
.Bl -enum
|
||||
.It
|
||||
Test for a condition that might cause an exception
|
||||
later, and branch to avoid the exception.
|
||||
.It
|
||||
Test a flag to see whether an exception has occurred
|
||||
since the program last reset its flag.
|
||||
.It
|
||||
Test a result to see whether it is a value that only
|
||||
an exception could have produced.
|
||||
.Pp
|
||||
CAUTION: The only reliable ways to discover
|
||||
whether Underflow has occurred are to test whether
|
||||
products or quotients lie closer to zero than the
|
||||
underflow threshold, or to test the Underflow
|
||||
flag.
|
||||
(Sums and differences cannot underflow in
|
||||
IEEE 754; if x \(!= y then x\-y is correct to
|
||||
full precision and certainly nonzero regardless of
|
||||
how tiny it may be.)
|
||||
Products and quotients that
|
||||
underflow gradually can lose accuracy gradually
|
||||
without vanishing, so comparing them with zero
|
||||
(as one might on a VAX) will not reveal the loss.
|
||||
Fortunately, if a gradually underflowed value is
|
||||
destined to be added to something bigger than the
|
||||
underflow threshold, as is almost always the case,
|
||||
digits lost to gradual underflow will not be missed
|
||||
because they would have been rounded off anyway.
|
||||
So gradual underflows are usually
|
||||
.Em provably
|
||||
ignorable.
|
||||
The same cannot be said of underflows flushed to 0.
|
||||
.El
|
||||
.Pp
|
||||
At the option of an implementor conforming to IEEE 754,
|
||||
other ways to cope with exceptions may be provided:
|
||||
.Bl -enum
|
||||
.It
|
||||
ABORT.
|
||||
This mechanism classifies an exception in
|
||||
advance as an incident to be handled by means
|
||||
traditionally associated with error-handling
|
||||
statements like "ON ERROR GO TO ...".
|
||||
Different
|
||||
languages offer different forms of this statement,
|
||||
but most share the following characteristics:
|
||||
.Bl -dash
|
||||
.It
|
||||
No means is provided to substitute a value for
|
||||
the offending operation's result and resume
|
||||
computation from what may be the middle of an
|
||||
expression.
|
||||
An exceptional result is abandoned.
|
||||
.It
|
||||
In a subprogram that lacks an error-handling
|
||||
statement, an exception causes the subprogram to
|
||||
abort within whatever program called it, and so
|
||||
on back up the chain of calling subprograms until
|
||||
an error-handling statement is encountered or the
|
||||
whole task is aborted and memory is dumped.
|
||||
.El
|
||||
.It
|
||||
STOP.
|
||||
This mechanism, requiring an interactive
|
||||
debugging environment, is more for the programmer
|
||||
than the program.
|
||||
It classifies an exception in
|
||||
advance as a symptom of a programmer's error; the
|
||||
exception suspends execution as near as it can to
|
||||
the offending operation so that the programmer can
|
||||
look around to see how it happened.
|
||||
Quite often
|
||||
the first several exceptions turn out to be quite
|
||||
unexceptionable, so the programmer ought ideally
|
||||
to be able to resume execution after each one as if
|
||||
execution had not been stopped.
|
||||
.It
|
||||
\&... Other ways lie beyond the scope of this document.
|
||||
.El
|
||||
.Pp
|
||||
Ideally, each
|
||||
elementary function should act as if it were indivisible, or
|
||||
atomic, in the sense that ...
|
||||
.Bl -enum
|
||||
.It
|
||||
No exception should be signaled that is not deserved by
|
||||
the data supplied to that function.
|
||||
.It
|
||||
Any exception signaled should be identified with that
|
||||
function rather than with one of its subroutines.
|
||||
.It
|
||||
The internal behavior of an atomic function should not
|
||||
be disrupted when a calling program changes from
|
||||
one to another of the five or so ways of handling
|
||||
exceptions listed above, although the definition
|
||||
of the function may be correlated intentionally
|
||||
with exception handling.
|
||||
.El
|
||||
.Pp
|
||||
The functions in
|
||||
.Nm libm
|
||||
are only approximately atomic.
|
||||
They signal no inappropriate exception except possibly ...
|
||||
.Bl -tag -width indent -offset indent -compact
|
||||
.It Xo
|
||||
Over/Underflow
|
||||
.Xc
|
||||
when a result, if properly computed, might have lain barely within range, and
|
||||
.It Xo
|
||||
Inexact in
|
||||
.Fn cabs ,
|
||||
.Fn cbrt ,
|
||||
.Fn hypot ,
|
||||
.Fn log10
|
||||
and
|
||||
.Fn scalbnf
|
||||
return
|
||||
.Fa x Ns \(**(2** Ns Fa n )
|
||||
computed by exponent manipulation.
|
||||
.Fn pow
|
||||
.Xc
|
||||
when it happens to be exact, thanks to fortuitous cancellation of errors.
|
||||
.El
|
||||
Otherwise, ...
|
||||
.Bl -tag -width indent -offset indent -compact
|
||||
.It Xo
|
||||
Invalid Operation is signaled only when
|
||||
.Xc
|
||||
any result but \*(Na would probably be misleading.
|
||||
.It Xo
|
||||
Overflow is signaled only when
|
||||
.Xc
|
||||
the exact result would be finite but beyond the overflow threshold.
|
||||
.It Xo
|
||||
Divide-by-Zero is signaled only when
|
||||
.Xc
|
||||
a function takes exactly infinite values at finite operands.
|
||||
.It Xo
|
||||
Underflow is signaled only when
|
||||
.Xc
|
||||
the exact result would be nonzero but tinier than the underflow threshold.
|
||||
.It Xo
|
||||
Inexact is signaled only when
|
||||
.Xc
|
||||
greater range or precision would be needed to represent the exact result.
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Xr fenv 3 ,
|
||||
.Xr ieee_test 3 ,
|
||||
.Xr math 3
|
||||
.Pp
|
||||
An explanation of IEEE 754 and its proposed extension p854
|
||||
was published in the IEEE magazine MICRO in August 1984 under
|
||||
the title "A Proposed Radix- and Word-length-independent
|
||||
Standard for Floating-point Arithmetic" by
|
||||
.An "W. J. Cody"
|
||||
et al.
|
||||
The manuals for Pascal, C and BASIC on the Apple Macintosh
|
||||
document the features of IEEE 754 pretty well.
|
||||
Articles in the IEEE magazine COMPUTER vol.\& 14 no.\& 3 (Mar.\&
|
||||
1981), and in the ACM SIGNUM Newsletter Special Issue of
|
||||
Oct.\& 1979, may be helpful although they pertain to
|
||||
superseded drafts of the standard.
|
||||
.Sh STANDARDS
|
||||
.St -ieee754
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Nm ieee
|
||||
functions appeared in
|
||||
.Bx 4.3 .
|
||||
The
|
||||
.Fn copysignl ,
|
||||
.Fn scalbln ,
|
||||
and
|
||||
.Fn scalblnf
|
||||
functions first appeared in
|
||||
.Fx 5.3 .
|
||||
|
||||
95
lib/msun/man/ilogb.3
Normal file
95
lib/msun/man/ilogb.3
Normal file
@ -0,0 +1,95 @@
|
||||
.\" Copyright (c) 1985, 1991 Regents of the University of California.
|
||||
.\" 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.
|
||||
.\" 3. All advertising materials mentioning features or use of this software
|
||||
.\" must display the following acknowledgement:
|
||||
.\" This product includes software developed by the University of
|
||||
.\" California, Berkeley and its contributors.
|
||||
.\" 4. Neither the name of the University nor the names of its contributors
|
||||
.\" may be used to endorse or promote products derived from this software
|
||||
.\" without specific prior written permission.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
|
||||
.\"
|
||||
.\" from: @(#)ieee.3 6.4 (Berkeley) 5/6/91
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 26, 2005
|
||||
.Dt ILOGB 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm ilogb ,
|
||||
.Nm ilogbf ,
|
||||
.Nm ilogbl
|
||||
.Nd extract exponent
|
||||
.Sh LIBRARY
|
||||
.Lb libm
|
||||
.Sh SYNOPSIS
|
||||
.In math.h
|
||||
.Ft int
|
||||
.Fn ilogb "double x"
|
||||
.Ft int
|
||||
.Fn ilogbf "float x"
|
||||
.Ft int
|
||||
.Fn ilogbl "long double x"
|
||||
.Sh DESCRIPTION
|
||||
.Fn ilogb ,
|
||||
.Fn ilogbf
|
||||
and
|
||||
.Fn ilogbl
|
||||
return
|
||||
.Fa x Ns 's exponent,
|
||||
in integer format.
|
||||
.Fn ilogb \*(Pm\*(If
|
||||
returns
|
||||
.Dv INT_MAX ,
|
||||
.Fn ilogb \*(Pm\*(Na
|
||||
returns
|
||||
.Dv FP_ILOGBNAN
|
||||
and
|
||||
.Fn ilogb 0
|
||||
returns
|
||||
.Dv FP_ILOGB0 .
|
||||
.Sh SEE ALSO
|
||||
.Xr frexp 3 ,
|
||||
.Xr ieee 3 ,
|
||||
.Xr math 3 ,
|
||||
.Xr scalbn 3
|
||||
.Sh STANDARDS
|
||||
The
|
||||
.Fn ilogb ,
|
||||
.Fn ilogbf ,
|
||||
and
|
||||
.Fn ilogbl
|
||||
routines conform to
|
||||
.St -isoC-99 .
|
||||
They provide functionality similar to the Logb function recommended by
|
||||
.St -ieee754 .
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Fn ilogb
|
||||
and
|
||||
.Fn ilogbf
|
||||
functions appeared in
|
||||
.Bx 4.3
|
||||
and
|
||||
.Fx 2.0 ,
|
||||
respectively.
|
||||
@ -200,418 +200,9 @@ in this section may not produce a result that is correctly rounded.
|
||||
In general, an unbounded number of digits of a value taken by a
|
||||
transcendental function may be needed to determine the correctly rounded
|
||||
result.
|
||||
.Sh NOTES
|
||||
Virtually all modern floating-point units attempt to support
|
||||
IEEE Standard 754 for Binary Floating-Point Arithmetic.
|
||||
This standard does not cover particular routines in the math library
|
||||
except for the few documented in
|
||||
.Xr ieee 3 ;
|
||||
it primarily defines representations of numbers and abstract
|
||||
properties of arithmetic operations relating to precision, rounding,
|
||||
and exceptional cases, as described below.
|
||||
.Ss IEEE STANDARD 754 Floating-Point Arithmetic
|
||||
.\" XXX mention single- and extended-/quad- precisions
|
||||
Radix: Binary.
|
||||
.Pp
|
||||
.Bl -column "" -compact
|
||||
Overflow and underflow:
|
||||
.El
|
||||
.Bd -ragged -offset indent -compact
|
||||
Overflow goes by default to a signed \*(If.
|
||||
Underflow is
|
||||
.Em gradual .
|
||||
.Ed
|
||||
.Pp
|
||||
Zero is represented ambiguously as +0 or \-0.
|
||||
.Bd -ragged -offset indent -compact
|
||||
Its sign transforms correctly through multiplication or
|
||||
division, and is preserved by addition of zeros
|
||||
with like signs; but x\-x yields +0 for every
|
||||
finite x.
|
||||
The only operations that reveal zero's
|
||||
sign are division by zero and
|
||||
.Fn copysign x \(+-0 .
|
||||
In particular, comparison (x > y, x \(>= y, etc.)\&
|
||||
cannot be affected by the sign of zero; but if
|
||||
finite x = y then \*(If = 1/(x\-y) \(!= \-1/(y\-x) = \-\*(If.
|
||||
.Ed
|
||||
.Pp
|
||||
Infinity is signed.
|
||||
.Bd -ragged -offset indent -compact
|
||||
It persists when added to itself
|
||||
or to any finite number.
|
||||
Its sign transforms
|
||||
correctly through multiplication and division, and
|
||||
(finite)/\(+-\*(If\0=\0\(+-0
|
||||
(nonzero)/0 = \(+-\*(If.
|
||||
But
|
||||
\*(If\-\*(If, \*(If\(**0 and \*(If/\*(If
|
||||
are, like 0/0 and sqrt(\-3),
|
||||
invalid operations that produce \*(Na. ...
|
||||
.Ed
|
||||
.Pp
|
||||
Reserved operands (\*(Nas):
|
||||
.Bd -ragged -offset indent -compact
|
||||
An \*(Na is
|
||||
.Em ( N Ns ot Em a N Ns umber ) .
|
||||
Some \*(Nas, called Signaling \*(Nas, trap any floating-point operation
|
||||
performed upon them; they are used to mark missing
|
||||
or uninitialized values, or nonexistent elements
|
||||
of arrays.
|
||||
The rest are Quiet \*(Nas; they are
|
||||
the default results of Invalid Operations, and
|
||||
propagate through subsequent arithmetic operations.
|
||||
If x \(!= x then x is \*(Na; every other predicate
|
||||
(x > y, x = y, x < y, ...) is FALSE if \*(Na is involved.
|
||||
.Ed
|
||||
.Pp
|
||||
Rounding:
|
||||
.Bd -ragged -offset indent -compact
|
||||
Every algebraic operation (+, \-, \(**, /,
|
||||
\(sr)
|
||||
is rounded by default to within half an
|
||||
.Em ulp ,
|
||||
and when the rounding error is exactly half an
|
||||
.Em ulp
|
||||
then
|
||||
the rounded value's least significant bit is zero.
|
||||
(An
|
||||
.Em ulp
|
||||
is one
|
||||
.Em U Ns nit
|
||||
in the
|
||||
.Em L Ns ast
|
||||
.Em P Ns lace . )
|
||||
This kind of rounding is usually the best kind,
|
||||
sometimes provably so; for instance, for every
|
||||
x = 1.0, 2.0, 3.0, 4.0, ..., 2.0**52, we find
|
||||
(x/3.0)\(**3.0 == x and (x/10.0)\(**10.0 == x and ...
|
||||
despite that both the quotients and the products
|
||||
have been rounded.
|
||||
Only rounding like IEEE 754 can do that.
|
||||
But no single kind of rounding can be
|
||||
proved best for every circumstance, so IEEE 754
|
||||
provides rounding towards zero or towards
|
||||
+\*(If or towards \-\*(If
|
||||
at the programmer's option.
|
||||
.Ed
|
||||
.Pp
|
||||
Exceptions:
|
||||
.Bd -ragged -offset indent -compact
|
||||
IEEE 754 recognizes five kinds of floating-point exceptions,
|
||||
listed below in declining order of probable importance.
|
||||
.Bl -column -offset indent "Invalid Operation" "Gradual Underflow"
|
||||
.Em "Exception Default Result"
|
||||
Invalid Operation \*(Na, or FALSE
|
||||
Overflow \(+-\*(If
|
||||
Divide by Zero \(+-\*(If
|
||||
Underflow Gradual Underflow
|
||||
Inexact Rounded value
|
||||
.El
|
||||
.Pp
|
||||
NOTE: An Exception is not an Error unless handled
|
||||
badly.
|
||||
What makes a class of exceptions exceptional
|
||||
is that no single default response can be satisfactory
|
||||
in every instance.
|
||||
On the other hand, if a default
|
||||
response will serve most instances satisfactorily,
|
||||
the unsatisfactory instances cannot justify aborting
|
||||
computation every time the exception occurs.
|
||||
.Ed
|
||||
.Ss Data Formats
|
||||
Single-precision:
|
||||
.Bd -ragged -offset indent -compact
|
||||
Type name:
|
||||
.Vt float
|
||||
.Pp
|
||||
Wordsize: 32 bits.
|
||||
.Pp
|
||||
Precision: 24 significant bits,
|
||||
roughly like 7 significant decimals.
|
||||
.Bd -ragged -offset indent -compact
|
||||
If x and x' are consecutive positive single-precision
|
||||
numbers (they differ by 1
|
||||
.Em ulp ) ,
|
||||
then
|
||||
.Bd -ragged -compact
|
||||
5.9e\-08 < 0.5**24 < (x'\-x)/x \(<= 0.5**23 < 1.2e\-07.
|
||||
.Ed
|
||||
.Ed
|
||||
.Pp
|
||||
.Bl -column "XXX" -compact
|
||||
Range: Overflow threshold = 2.0**128 = 3.4e38
|
||||
Underflow threshold = 0.5**126 = 1.2e\-38
|
||||
.El
|
||||
.Bd -ragged -offset indent -compact
|
||||
Underflowed results round to the nearest
|
||||
integer multiple of 0.5**149 = 1.4e\-45.
|
||||
.Ed
|
||||
.Ed
|
||||
.Pp
|
||||
Double-precision:
|
||||
.Bd -ragged -offset indent -compact
|
||||
Type name:
|
||||
.Vt double
|
||||
.Bd -ragged -offset indent -compact
|
||||
On some architectures,
|
||||
.Vt long double
|
||||
is the the same as
|
||||
.Vt double .
|
||||
.Ed
|
||||
.Pp
|
||||
Wordsize: 64 bits.
|
||||
.Pp
|
||||
Precision: 53 significant bits,
|
||||
roughly like 16 significant decimals.
|
||||
.Bd -ragged -offset indent -compact
|
||||
If x and x' are consecutive positive double-precision
|
||||
numbers (they differ by 1
|
||||
.Em ulp ) ,
|
||||
then
|
||||
.Bd -ragged -compact
|
||||
1.1e\-16 < 0.5**53 < (x'\-x)/x \(<= 0.5**52 < 2.3e\-16.
|
||||
.Ed
|
||||
.Ed
|
||||
.Pp
|
||||
.Bl -column "XXX" -compact
|
||||
Range: Overflow threshold = 2.0**1024 = 1.8e308
|
||||
Underflow threshold = 0.5**1022 = 2.2e\-308
|
||||
.El
|
||||
.Bd -ragged -offset indent -compact
|
||||
Underflowed results round to the nearest
|
||||
integer multiple of 0.5**1074 = 4.9e\-324.
|
||||
.Ed
|
||||
.Ed
|
||||
.Pp
|
||||
Extended-precision:
|
||||
.Bd -ragged -offset indent -compact
|
||||
Type name:
|
||||
.Vt long double
|
||||
(when supported by the hardware)
|
||||
.Pp
|
||||
Wordsize: 96 bits.
|
||||
.Pp
|
||||
Precision: 64 significant bits,
|
||||
roughly like 19 significant decimals.
|
||||
.Bd -ragged -offset indent -compact
|
||||
If x and x' are consecutive positive double-precision
|
||||
numbers (they differ by 1
|
||||
.Em ulp ) ,
|
||||
then
|
||||
.Bd -ragged -compact
|
||||
1.0e\-19 < 0.5**63 < (x'\-x)/x \(<= 0.5**62 < 2.2e\-19.
|
||||
.Ed
|
||||
.Ed
|
||||
.Pp
|
||||
.Bl -column "XXX" -compact
|
||||
Range: Overflow threshold = 2.0**16384 = 1.2e4932
|
||||
Underflow threshold = 0.5**16382 = 3.4e\-4932
|
||||
.El
|
||||
.Bd -ragged -offset indent -compact
|
||||
Underflowed results round to the nearest
|
||||
integer multiple of 0.5**16451 = 5.7e\-4953.
|
||||
.Ed
|
||||
.Ed
|
||||
.Pp
|
||||
Quad-extended-precision:
|
||||
.Bd -ragged -offset indent -compact
|
||||
Type name:
|
||||
.Vt long double
|
||||
(when supported by the hardware)
|
||||
.Pp
|
||||
Wordsize: 128 bits.
|
||||
.Pp
|
||||
Precision: 113 significant bits,
|
||||
roughly like 34 significant decimals.
|
||||
.Bd -ragged -offset indent -compact
|
||||
If x and x' are consecutive positive double-precision
|
||||
numbers (they differ by 1
|
||||
.Em ulp ) ,
|
||||
then
|
||||
.Bd -ragged -compact
|
||||
9.6e\-35 < 0.5**113 < (x'\-x)/x \(<= 0.5**112 < 2.0e\-34.
|
||||
.Ed
|
||||
.Ed
|
||||
.Pp
|
||||
.Bl -column "XXX" -compact
|
||||
Range: Overflow threshold = 2.0**16384 = 1.2e4932
|
||||
Underflow threshold = 0.5**16382 = 3.4e\-4932
|
||||
.El
|
||||
.Bd -ragged -offset indent -compact
|
||||
Underflowed results round to the nearest
|
||||
integer multiple of 0.5**16494 = 6.5e\-4966.
|
||||
.Ed
|
||||
.Ed
|
||||
.Ss Additional Information Regarding Exceptions
|
||||
.Pp
|
||||
For each kind of floating-point exception, IEEE 754
|
||||
provides a Flag that is raised each time its exception
|
||||
is signaled, and stays raised until the program resets
|
||||
it.
|
||||
Programs may also test, save and restore a flag.
|
||||
Thus, IEEE 754 provides three ways by which programs
|
||||
may cope with exceptions for which the default result
|
||||
might be unsatisfactory:
|
||||
.Bl -enum
|
||||
.It
|
||||
Test for a condition that might cause an exception
|
||||
later, and branch to avoid the exception.
|
||||
.It
|
||||
Test a flag to see whether an exception has occurred
|
||||
since the program last reset its flag.
|
||||
.It
|
||||
Test a result to see whether it is a value that only
|
||||
an exception could have produced.
|
||||
.Pp
|
||||
CAUTION: The only reliable ways to discover
|
||||
whether Underflow has occurred are to test whether
|
||||
products or quotients lie closer to zero than the
|
||||
underflow threshold, or to test the Underflow
|
||||
flag.
|
||||
(Sums and differences cannot underflow in
|
||||
IEEE 754; if x \(!= y then x\-y is correct to
|
||||
full precision and certainly nonzero regardless of
|
||||
how tiny it may be.)
|
||||
Products and quotients that
|
||||
underflow gradually can lose accuracy gradually
|
||||
without vanishing, so comparing them with zero
|
||||
(as one might on a VAX) will not reveal the loss.
|
||||
Fortunately, if a gradually underflowed value is
|
||||
destined to be added to something bigger than the
|
||||
underflow threshold, as is almost always the case,
|
||||
digits lost to gradual underflow will not be missed
|
||||
because they would have been rounded off anyway.
|
||||
So gradual underflows are usually
|
||||
.Em provably
|
||||
ignorable.
|
||||
The same cannot be said of underflows flushed to 0.
|
||||
.El
|
||||
.Pp
|
||||
At the option of an implementor conforming to IEEE 754,
|
||||
other ways to cope with exceptions may be provided:
|
||||
.Bl -enum
|
||||
.It
|
||||
ABORT.
|
||||
This mechanism classifies an exception in
|
||||
advance as an incident to be handled by means
|
||||
traditionally associated with error-handling
|
||||
statements like "ON ERROR GO TO ...".
|
||||
Different
|
||||
languages offer different forms of this statement,
|
||||
but most share the following characteristics:
|
||||
.Bl -dash
|
||||
.It
|
||||
No means is provided to substitute a value for
|
||||
the offending operation's result and resume
|
||||
computation from what may be the middle of an
|
||||
expression.
|
||||
An exceptional result is abandoned.
|
||||
.It
|
||||
In a subprogram that lacks an error-handling
|
||||
statement, an exception causes the subprogram to
|
||||
abort within whatever program called it, and so
|
||||
on back up the chain of calling subprograms until
|
||||
an error-handling statement is encountered or the
|
||||
whole task is aborted and memory is dumped.
|
||||
.El
|
||||
.It
|
||||
STOP.
|
||||
This mechanism, requiring an interactive
|
||||
debugging environment, is more for the programmer
|
||||
than the program.
|
||||
It classifies an exception in
|
||||
advance as a symptom of a programmer's error; the
|
||||
exception suspends execution as near as it can to
|
||||
the offending operation so that the programmer can
|
||||
look around to see how it happened.
|
||||
Quite often
|
||||
the first several exceptions turn out to be quite
|
||||
unexceptionable, so the programmer ought ideally
|
||||
to be able to resume execution after each one as if
|
||||
execution had not been stopped.
|
||||
.It
|
||||
\&... Other ways lie beyond the scope of this document.
|
||||
.El
|
||||
.Pp
|
||||
Ideally, each
|
||||
elementary function should act as if it were indivisible, or
|
||||
atomic, in the sense that ...
|
||||
.Bl -enum
|
||||
.It
|
||||
No exception should be signaled that is not deserved by
|
||||
the data supplied to that function.
|
||||
.It
|
||||
Any exception signaled should be identified with that
|
||||
function rather than with one of its subroutines.
|
||||
.It
|
||||
The internal behavior of an atomic function should not
|
||||
be disrupted when a calling program changes from
|
||||
one to another of the five or so ways of handling
|
||||
exceptions listed above, although the definition
|
||||
of the function may be correlated intentionally
|
||||
with exception handling.
|
||||
.El
|
||||
.Pp
|
||||
The functions in
|
||||
.Nm libm
|
||||
are only approximately atomic.
|
||||
They signal no inappropriate exception except possibly ...
|
||||
.Bl -tag -width indent -offset indent -compact
|
||||
.It Xo
|
||||
Over/Underflow
|
||||
.Xc
|
||||
when a result, if properly computed, might have lain barely within range, and
|
||||
.It Xo
|
||||
Inexact in
|
||||
.Fn cabs ,
|
||||
.Fn cbrt ,
|
||||
.Fn hypot ,
|
||||
.Fn log10
|
||||
and
|
||||
.Fn pow
|
||||
.Xc
|
||||
when it happens to be exact, thanks to fortuitous cancellation of errors.
|
||||
.El
|
||||
Otherwise, ...
|
||||
.Bl -tag -width indent -offset indent -compact
|
||||
.It Xo
|
||||
Invalid Operation is signaled only when
|
||||
.Xc
|
||||
any result but \*(Na would probably be misleading.
|
||||
.It Xo
|
||||
Overflow is signaled only when
|
||||
.Xc
|
||||
the exact result would be finite but beyond the overflow threshold.
|
||||
.It Xo
|
||||
Divide-by-Zero is signaled only when
|
||||
.Xc
|
||||
a function takes exactly infinite values at finite operands.
|
||||
.It Xo
|
||||
Underflow is signaled only when
|
||||
.Xc
|
||||
the exact result would be nonzero but tinier than the underflow threshold.
|
||||
.It Xo
|
||||
Inexact is signaled only when
|
||||
.Xc
|
||||
greater range or precision would be needed to represent the exact result.
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Xr fenv 3 ,
|
||||
.Xr ieee 3
|
||||
.Pp
|
||||
An explanation of IEEE 754 and its proposed extension p854
|
||||
was published in the IEEE magazine MICRO in August 1984 under
|
||||
the title "A Proposed Radix- and Word-length-independent
|
||||
Standard for Floating-point Arithmetic" by
|
||||
.An "W. J. Cody"
|
||||
et al.
|
||||
The manuals for Pascal, C and BASIC on the Apple Macintosh
|
||||
document the features of IEEE 754 pretty well.
|
||||
Articles in the IEEE magazine COMPUTER vol.\& 14 no.\& 3 (Mar.\&
|
||||
1981), and in the ACM SIGNUM Newsletter Special Issue of
|
||||
Oct.\& 1979, may be helpful although they pertain to
|
||||
superseded drafts of the standard.
|
||||
.Sh HISTORY
|
||||
A math library with many of the present functions appeared in
|
||||
.At v7 .
|
||||
|
||||
86
lib/msun/man/nextafter.3
Normal file
86
lib/msun/man/nextafter.3
Normal file
@ -0,0 +1,86 @@
|
||||
.\" Copyright (c) 1985, 1991 Regents of the University of California.
|
||||
.\" 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.
|
||||
.\" 3. All advertising materials mentioning features or use of this software
|
||||
.\" must display the following acknowledgement:
|
||||
.\" This product includes software developed by the University of
|
||||
.\" California, Berkeley and its contributors.
|
||||
.\" 4. Neither the name of the University nor the names of its contributors
|
||||
.\" may be used to endorse or promote products derived from this software
|
||||
.\" without specific prior written permission.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
|
||||
.\"
|
||||
.\" from: @(#)ieee.3 6.4 (Berkeley) 5/6/91
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 26, 2005
|
||||
.Dt NEXTAFTER 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm nextafter ,
|
||||
.Nm nextafterf
|
||||
.Nd next representable value
|
||||
.Sh LIBRARY
|
||||
.Lb libm
|
||||
.Sh SYNOPSIS
|
||||
.In math.h
|
||||
.Ft double
|
||||
.Fn nextafter "double x" "double y"
|
||||
.Ft float
|
||||
.Fn nextafterf "float x" "float y"
|
||||
.Sh DESCRIPTION
|
||||
.Fn nextafter
|
||||
and
|
||||
.Fn nextafterf
|
||||
return the next machine representable number from
|
||||
.Fa x
|
||||
in direction
|
||||
.Fa y .
|
||||
.Sh SEE ALSO
|
||||
.Xr ieee 3 ,
|
||||
.Xr math 3
|
||||
.Sh STANDARDS
|
||||
The
|
||||
.Fn nextafter
|
||||
and
|
||||
.Fn nextafterf
|
||||
routines conform to
|
||||
.St -isoC-99 .
|
||||
They implement the Nextafter function recommended by
|
||||
.St -ieee754 ,
|
||||
with the extension that
|
||||
.Fn nextafter +0.0, -0.0
|
||||
returns
|
||||
.Li -0.0 ,
|
||||
and
|
||||
.Fn nextafter -0.0, +0.0
|
||||
returns
|
||||
.Li +0.0 .
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Fn nextafter
|
||||
function appeared in
|
||||
.Bx 4.3 ,
|
||||
and
|
||||
.Fn nextafterf
|
||||
appeared in
|
||||
.Fx 2.0 .
|
||||
113
lib/msun/man/remainder.3
Normal file
113
lib/msun/man/remainder.3
Normal file
@ -0,0 +1,113 @@
|
||||
.\" Copyright (c) 1985, 1991 Regents of the University of California.
|
||||
.\" 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.
|
||||
.\" 3. All advertising materials mentioning features or use of this software
|
||||
.\" must display the following acknowledgement:
|
||||
.\" This product includes software developed by the University of
|
||||
.\" California, Berkeley and its contributors.
|
||||
.\" 4. Neither the name of the University nor the names of its contributors
|
||||
.\" may be used to endorse or promote products derived from this software
|
||||
.\" without specific prior written permission.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
|
||||
.\"
|
||||
.\" from: @(#)ieee.3 6.4 (Berkeley) 5/6/91
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 26, 2005
|
||||
.Dt REMAINDER 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm remainder ,
|
||||
.Nm remainderf
|
||||
.Nd minimal residue functions
|
||||
.Sh LIBRARY
|
||||
.Lb libm
|
||||
.Sh SYNOPSIS
|
||||
.In math.h
|
||||
.Ft double
|
||||
.Fn remainder "double x" "double y"
|
||||
.Ft float
|
||||
.Fn remainderf "float x" "float y"
|
||||
.Sh DESCRIPTION
|
||||
.Fn remainder
|
||||
and
|
||||
.Fn remainderf
|
||||
return the remainder
|
||||
.Fa r
|
||||
:=
|
||||
.Fa x
|
||||
\-
|
||||
.Fa n\(**y
|
||||
where
|
||||
.Fa n
|
||||
is the integer nearest the exact value of
|
||||
.Bk -words
|
||||
.Fa x Ns / Ns Fa y ;
|
||||
.Ek
|
||||
moreover if
|
||||
.Pf \\*(Ba Fa n
|
||||
\-
|
||||
.Sm off
|
||||
.Fa x No / Fa y No \\*(Ba
|
||||
.Sm on
|
||||
=
|
||||
1/2
|
||||
then
|
||||
.Fa n
|
||||
is even.
|
||||
Consequently
|
||||
the remainder is computed exactly and
|
||||
.Sm off
|
||||
.Pf \\*(Ba Fa r No \\*(Ba
|
||||
.Sm on
|
||||
\*(Le
|
||||
.Sm off
|
||||
.Pf \\*(Ba Fa y No \\*(Ba/2 .
|
||||
.Sm on
|
||||
But
|
||||
.Fn remainder x 0
|
||||
and
|
||||
.Fn remainder \*(If 0
|
||||
are invalid operations that produce a \*(Na.
|
||||
.Sh SEE ALSO
|
||||
.Xr fmod 3 ,
|
||||
.Xr ieee 3 ,
|
||||
.Xr math 3
|
||||
.Sh STANDARDS
|
||||
The
|
||||
.Fn remainder
|
||||
and
|
||||
.Fn remainderf
|
||||
routines conform to
|
||||
.St -isoC-99
|
||||
and
|
||||
.St -ieee754 .
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Fn remainder
|
||||
and
|
||||
.Fn remainderf
|
||||
functions appeared in
|
||||
.Bx 4.3
|
||||
and
|
||||
.Fx 2.0 ,
|
||||
respectively.
|
||||
88
lib/msun/man/scalbn.3
Normal file
88
lib/msun/man/scalbn.3
Normal file
@ -0,0 +1,88 @@
|
||||
.\" Copyright (c) 1985, 1991 Regents of the University of California.
|
||||
.\" 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.
|
||||
.\" 3. All advertising materials mentioning features or use of this software
|
||||
.\" must display the following acknowledgement:
|
||||
.\" This product includes software developed by the University of
|
||||
.\" California, Berkeley and its contributors.
|
||||
.\" 4. Neither the name of the University nor the names of its contributors
|
||||
.\" may be used to endorse or promote products derived from this software
|
||||
.\" without specific prior written permission.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
|
||||
.\"
|
||||
.\" from: @(#)ieee.3 6.4 (Berkeley) 5/6/91
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 26, 2005
|
||||
.Dt SCALBN 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm scalbln ,
|
||||
.Nm scalblnf ,
|
||||
.Nm scalbn ,
|
||||
.Nm scalbnf
|
||||
.Nd adjust exponent
|
||||
.Sh LIBRARY
|
||||
.Lb libm
|
||||
.Sh SYNOPSIS
|
||||
.In math.h
|
||||
.Ft double
|
||||
.Fn scalbln "double x" "long n"
|
||||
.Ft float
|
||||
.Fn scalblnf "float x" "long n"
|
||||
.Ft double
|
||||
.Fn scalbn "double x" "int n"
|
||||
.Ft float
|
||||
.Fn scalbnf "float x" "int n"
|
||||
.Sh DESCRIPTION
|
||||
.Fn scalbln ,
|
||||
.Fn scalblnf ,
|
||||
.Fn scalbn ,
|
||||
and
|
||||
.Fn scalbnf
|
||||
return
|
||||
.Fa x Ns \(**(2** Ns Fa n )
|
||||
computed by exponent manipulation.
|
||||
.Sh SEE ALSO
|
||||
.Xr ieee 3 ,
|
||||
.Xr math 3
|
||||
.Sh STANDARDS
|
||||
These routines conform to
|
||||
.St -isoC-99 ,
|
||||
and they implement the Scalb function recommended by
|
||||
.St -ieee754 .
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Fn scalbn
|
||||
and
|
||||
.Fn scalbnf
|
||||
functions appeared in
|
||||
.Bx 4.3
|
||||
and
|
||||
.Fx 2.0 ,
|
||||
respectively.
|
||||
The
|
||||
.Fn scalbln
|
||||
and
|
||||
.Fn scalblnf
|
||||
functions first appeared in
|
||||
.Fx 5.3 .
|
||||
Loading…
Reference in New Issue
Block a user