lib/libm/common_source/ieee.3

   1 .\" Copyright (c) 1985, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)ieee.3      8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libm/common_source/ieee.3,v 1.4.2.5 2001/08/17 15:43:05 ru Exp $
  34 .\" $DragonFly: src/lib/libm/common_source/Attic/ieee.3,v 1.2 2003/06/17 04:26:50 dillon Exp $
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt IEEE 3
  38 .Os
  39 .Sh NAME
  40 .Nm copysign ,
  41 .Nm drem ,
  42 .Nm finite ,
  43 .Nm logb ,
  44 .Nm scalb
  45 .Nd "IEEE 754 floating point support
  46 .Sh LIBRARY
  47 .Lb libm
  48 .Sh SYNOPSIS
  49 .Fd #include <math.h>
  50 .Ft double
  51 .Fn copysign "double x" "double y"
  52 .Ft double
  53 .Fn drem "double x" "double y"
  54 .Ft int
  55 .Fn finite "double x"
  56 .Ft double
  57 .Fn logb "double x"
  58 .Ft double
  59 .Fn scalb "double x" "int n"
  60 .Sh DESCRIPTION
  61 These functions are required for, or recommended by the
  62 .Tn IEEE
  63 standard
  64 754 for floating\-point arithmetic.
  65 .Pp
  66 The
  67 .Fn copysign
  68 function
  69 returns
  70 .Fa x
  71 with its sign changed to
  72 .Fa y Ns 's .
  73 .Pp
  74 The
  75 .Fn drem
  76 function
  77 returns the remainder
  78 .Fa r
  79 :=
  80 .Fa x
  81 \-
  82 .Fa n\(**y
  83 where
  84 .Fa n
  85 is the integer nearest the exact value of
  86 .Bk -words
  87 .Fa x Ns / Ns Fa y ;
  88 .Ek
  89 moreover if
  90 .Pf \\*(Ba Fa n
  91 \-
  92 .Sm off
  93 .Fa x No / Fa y No \\*(Ba
  94 .Sm on
  95 =
  96 1/2
  97 then
  98 .Fa n
  99 is even.  Consequently
 100 the remainder is computed exactly and
 101 .Sm off
 102 .Pf \\*(Ba Fa r No \\*(Ba
 103 .Sm on
 104 \*(Le
 105 .Sm off
 106 .Pf \\*(Ba Fa y No \\*(Ba/2 .
 107 .Sm on
 108 But
 109 .Fn drem x 0
 110 is exceptional.
 111 (See below under
 112 .Sx DIAGNOSTICS . )
 113 .Pp
 114 The
 115 .Fn finite
 116 function returns the value 1 just when
 117 \-\*(If \*(Lt
 118 .Fa x
 119 \*(Lt +\*(If;
 120 otherwise a
 121 zero is returned
 122 (when
 123 .Pf \\*(Ba Ns Fa x Ns \\*(Ba
 124 = \*(If or
 125 .Fa x
 126 is \*(Na or
 127 is the
 128 .Tn VAX Ns 's
 129 reserved operand).
 130 .Pp
 131 The
 132 .Fn logb
 133 function returns
 134 .Fa x Ns 's exponent
 135 .Fa n ,
 136 a signed integer converted to double\-precision floating\-point and so
 137 chosen that
 138 1 (<=
 139 .Pf \\*(Ba Ns Fa x Ns \\*(Ba2** Ns Fa n
 140 < 2
 141 unless
 142 .Fa x
 143 = 0 or
 144 (only on machines that conform to
 145 .Tn IEEE
 146 754)
 147 .Pf \\*(Ba Fa x Ns \\*(Ba
 148 = \*(If
 149 or
 150 .Fa x
 151 lies between 0 and the Underflow Threshold.
 152 (See below under
 153 .Sx BUGS . )
 154 .Pp
 155 The
 156 .Fn scalb
 157 function returns
 158 .Fa x Ns \(**(2** Ns Fa n )
 159 computed, for integer n, without first computing
 160 .Pf 2\(** Fa n .
 161 .Sh RETURN VALUES
 162 The
 163 .Tn IEEE
 164 standard
 165 754 defines
 166 .Fn drem x 0
 167 and
 168 .Fn drem \\*(If y
 169 to be invalid operations that produce a \*(Na.
 170 On the
 171 .Tn VAX ,
 172 .Fn drem x 0
 173 generates a reserved operand fault.  No \*(If
 174 exists on a
 175 .Tn VAX .
 176 .Pp
 177 .Tn IEEE
 178 754 defines
 179 .if n \
 180 .Fn logb \(+-\\*(If
 181 = \*(If and
 182 .Fn logb 0
 183 = \-\*(If, and
 184 requires the latter to signal Division\-by\-Zero.
 185 But on a
 186 .Tn VAX ,
 187 .Fn logb 0
 188 = 1.0 \- 2.0**31 = \-2,147,483,647.0.
 189 And if the correct value of
 190 .Fn scalb
 191 would overflow on a
 192 .Tn VAX ,
 193 it generates a reserved operand fault and sets the global variable
 194 .Va errno
 195 to
 196 .Er ERANGE .
 197 .Sh SEE ALSO
 198 .Xr floor 3 ,
 199 .Xr infnan 3 ,
 200 .Xr math 3
 201 .Sh HISTORY
 202 The
 203 .Nm ieee
 204 functions appeared in
 205 .Bx 4.3 .
 206 .Sh BUGS
 207 Should
 208 .Fn drem x 0
 209 and
 210 .Fn logb 0
 211 on a
 212 .Tn VAX
 213 signal invalidity
 214 by setting
 215 .Va errno No = Er EDOM ?
 216 Should
 217 .Fn logb 0
 218 return  \-1.7e38?
 219 .Pp
 220 .Tn IEEE
 221 754 currently specifies that
 222 .Fn logb "denormalized no.\&"
 223 =
 224 .Fn logb "tiniest normalized no. > 0"
 225 but the consensus has changed to the specification in the new
 226 proposed
 227 .Tn IEEE
 228 standard p854, namely that
 229 .Fn logb x
 230 satisfy
 231 .Bd -ragged -offset indent
 232 1 \(<=
 233 .Fn scalb \\*(Bax\\*(Ba \-logb(x)
 234 <
 235 Radix\0 ... = 2
 236 for
 237 .Tn IEEE
 238 754
 239 .Ed
 240 .Pp
 241 for every x except 0,
 242 \*(If
 243 and \*(Na.
 244 Almost every program that assumes 754's specification will work
 245 correctly if
 246 .Fn logb
 247 follows 854's specification instead.
 248 .Pp
 249 .Tn IEEE
 250 754 requires
 251 .Fn copysign x \\*(Na)
 252 =
 253 .Pf \(+- Ns Fa x
 254 but says nothing
 255 else about the sign of a \*(Na.  A \*(Na
 256 .Em (N Ns ot
 257 .Em a
 258 .Em N Ns umber )
 259 is
 260 similar in spirit to the
 261 .Tn VAX Ns 's
 262 reserved operand, but very
 263 different in important details.  Since the sign bit of a
 264 reserved operand makes it look negative,
 265 .Bd -ragged -offset indent
 266 .Fn copysign x "reserved operand"
 267 =
 268 .Pf \- Fa x ;
 269 .Ed
 270 .Pp
 271 should this return the reserved operand instead?