diff options
author | das <das@FreeBSD.org> | 2005-01-27 05:46:17 +0000 |
---|---|---|
committer | das <das@FreeBSD.org> | 2005-01-27 05:46:17 +0000 |
commit | 783f4bf0c2c565c36458d9573a2c27e8958da1ae (patch) | |
tree | 687ff889319c52bb4bfdc6dace80fa3197cb1b66 /lib | |
parent | 8b8557483e752ce695905e41e5bd36bb85f9cb9c (diff) | |
download | FreeBSD-src-783f4bf0c2c565c36458d9573a2c27e8958da1ae.zip FreeBSD-src-783f4bf0c2c565c36458d9573a2c27e8958da1ae.tar.gz |
- 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.
Diffstat (limited to 'lib')
-rw-r--r-- | lib/libc/gen/Makefile.inc | 3 | ||||
-rw-r--r-- | lib/libc/gen/fpclassify.3 | 8 | ||||
-rw-r--r-- | lib/msun/Makefile | 21 | ||||
-rw-r--r-- | lib/msun/man/copysign.3 | 90 | ||||
-rw-r--r-- | lib/msun/man/ieee.3 | 568 | ||||
-rw-r--r-- | lib/msun/man/ilogb.3 | 95 | ||||
-rw-r--r-- | lib/msun/man/math.3 | 409 | ||||
-rw-r--r-- | lib/msun/man/nextafter.3 | 86 | ||||
-rw-r--r-- | lib/msun/man/remainder.3 | 113 | ||||
-rw-r--r-- | lib/msun/man/scalbn.3 | 88 |
10 files changed, 894 insertions, 587 deletions
diff --git a/lib/libc/gen/Makefile.inc b/lib/libc/gen/Makefile.inc index 959546e..a888259 100644 --- a/lib/libc/gen/Makefile.inc +++ b/lib/libc/gen/Makefile.inc @@ -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 diff --git a/lib/libc/gen/fpclassify.3 b/lib/libc/gen/fpclassify.3 index 9379e38..a547eeb 100644 --- a/lib/libc/gen/fpclassify.3 +++ b/lib/libc/gen/fpclassify.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 , diff --git a/lib/msun/Makefile b/lib/msun/Makefile index d5724df..4917712 100644 --- a/lib/msun/Makefile +++ b/lib/msun/Makefile @@ -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 diff --git a/lib/msun/man/copysign.3 b/lib/msun/man/copysign.3 new file mode 100644 index 0000000..83fc126 --- /dev/null +++ b/lib/msun/man/copysign.3 @@ -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. diff --git a/lib/msun/man/ieee.3 b/lib/msun/man/ieee.3 index 676798c..291ccd8 100644 --- a/lib/msun/man/ieee.3 +++ b/lib/msun/man/ieee.3 @@ -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 . -.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). -.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 . +.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 nextafter -and -.Fn nextafterf -return the next machine representable number from -.Fa x -in direction -.Fa y . +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 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 +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 -.Fn scalbln , -.Fn scalblnf , -.Fn scalbn , +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 . diff --git a/lib/msun/man/ilogb.3 b/lib/msun/man/ilogb.3 new file mode 100644 index 0000000..401e86d --- /dev/null +++ b/lib/msun/man/ilogb.3 @@ -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. diff --git a/lib/msun/man/math.3 b/lib/msun/man/math.3 index 553154b..0b622b4 100644 --- a/lib/msun/man/math.3 +++ b/lib/msun/man/math.3 @@ -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 . diff --git a/lib/msun/man/nextafter.3 b/lib/msun/man/nextafter.3 new file mode 100644 index 0000000..009cfbb --- /dev/null +++ b/lib/msun/man/nextafter.3 @@ -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 . diff --git a/lib/msun/man/remainder.3 b/lib/msun/man/remainder.3 new file mode 100644 index 0000000..4b5b877 --- /dev/null +++ b/lib/msun/man/remainder.3 @@ -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. diff --git a/lib/msun/man/scalbn.3 b/lib/msun/man/scalbn.3 new file mode 100644 index 0000000..45e1aab --- /dev/null +++ b/lib/msun/man/scalbn.3 @@ -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 . |