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 .\"
  35 .Dd June 4, 1993
  36 .Dt IEEE 3
  37 .Os
  38 .Sh NAME
  39 .Nm copysign ,
  40 .Nm drem ,
  41 .Nm finite ,
  42 .Nm logb ,
  43 .Nm scalb
  44 .Nd "IEEE 754 floating point support
  45 .Sh LIBRARY
  46 .Lb libm
  47 .Sh SYNOPSIS
  48 .Fd #include <math.h>
  49 .Ft double
  50 .Fn copysign "double x" "double y"
  51 .Ft double
  52 .Fn drem "double x" "double y"
  53 .Ft int
  54 .Fn finite "double x"
  55 .Ft double
  56 .Fn logb "double x"
  57 .Ft double
  58 .Fn scalb "double x" "int n"
  59 .Sh DESCRIPTION
  60 These functions are required for, or recommended by the
  61 .Tn IEEE
  62 standard
  63 754 for floating\-point arithmetic.
  64 .Pp
  65 The
  66 .Fn copysign
  67 function
  68 returns
  69 .Fa x
  70 with its sign changed to
  71 .Fa y Ns 's .
  72 .Pp
  73 The
  74 .Fn drem
  75 function
  76 returns the remainder
  77 .Fa r
  78 :=
  79 .Fa x
  80 \-
  81 .Fa n\(**y
  82 where
  83 .Fa n
  84 is the integer nearest the exact value of
  85 .Bk -words
  86 .Fa x Ns / Ns Fa y ;
  87 .Ek
  88 moreover if
  89 .Pf \\*(Ba Fa n
  90 \-
  91 .Sm off
  92 .Fa x No / Fa y No \\*(Ba
  93 .Sm on
  94 =
  95 1/2
  96 then
  97 .Fa n
  98 is even.  Consequently
  99 the remainder is computed exactly and
 100 .Sm off
 101 .Pf \\*(Ba Fa r No \\*(Ba
 102 .Sm on
 103 \*(Le
 104 .Sm off
 105 .Pf \\*(Ba Fa y No \\*(Ba/2 .
 106 .Sm on
 107 But
 108 .Fn drem x 0
 109 is exceptional.
 110 (See below under
 111 .Sx DIAGNOSTICS . )
 112 .Pp
 113 The
 114 .Fn finite
 115 function returns the value 1 just when
 116 \-\*(If \*(Lt
 117 .Fa x
 118 \*(Lt +\*(If;
 119 otherwise a
 120 zero is returned
 121 (when
 122 .Pf \\*(Ba Ns Fa x Ns \\*(Ba
 123 = \*(If or
 124 .Fa x
 125 is \*(Na or
 126 is the
 127 .Tn VAX Ns 's
 128 reserved operand).
 129 .Pp
 130 The
 131 .Fn logb
 132 function returns
 133 .Fa x Ns 's exponent
 134 .Fa n ,
 135 a signed integer converted to double\-precision floating\-point and so
 136 chosen that
 137 1 (<=
 138 .Pf \\*(Ba Ns Fa x Ns \\*(Ba2** Ns Fa n
 139 < 2
 140 unless
 141 .Fa x
 142 = 0 or
 143 (only on machines that conform to
 144 .Tn IEEE
 145 754)
 146 .Pf \\*(Ba Fa x Ns \\*(Ba
 147 = \*(If
 148 or
 149 .Fa x
 150 lies between 0 and the Underflow Threshold.
 151 (See below under
 152 .Sx BUGS . )
 153 .Pp
 154 The
 155 .Fn scalb
 156 function returns
 157 .Fa x Ns \(**(2** Ns Fa n )
 158 computed, for integer n, without first computing
 159 .Pf 2\(** Fa n .
 160 .Sh RETURN VALUES
 161 The
 162 .Tn IEEE
 163 standard
 164 754 defines
 165 .Fn drem x 0
 166 and
 167 .Fn drem \\*(If y
 168 to be invalid operations that produce a \*(Na.
 169 On the
 170 .Tn VAX ,
 171 .Fn drem x 0
 172 generates a reserved operand fault.  No \*(If
 173 exists on a
 174 .Tn VAX .
 175 .Pp
 176 .Tn IEEE
 177 754 defines
 178 .if n \
 179 .Fn logb \(+-\\*(If
 180 = \*(If and
 181 .Fn logb 0
 182 = \-\*(If, and
 183 requires the latter to signal Division\-by\-Zero.
 184 But on a
 185 .Tn VAX ,
 186 .Fn logb 0
 187 = 1.0 \- 2.0**31 = \-2,147,483,647.0.
 188 And if the correct value of
 189 .Fn scalb
 190 would overflow on a
 191 .Tn VAX ,
 192 it generates a reserved operand fault and sets the global variable
 193 .Va errno
 194 to
 195 .Er ERANGE .
 196 .Sh SEE ALSO
 197 .Xr floor 3 ,
 198 .Xr infnan 3 ,
 199 .Xr math 3
 200 .Sh HISTORY
 201 The
 202 .Nm ieee
 203 functions appeared in
 204 .Bx 4.3 .
 205 .Sh BUGS
 206 Should
 207 .Fn drem x 0
 208 and
 209 .Fn logb 0
 210 on a
 211 .Tn VAX
 212 signal invalidity
 213 by setting
 214 .Va errno No = Er EDOM ?
 215 Should
 216 .Fn logb 0
 217 return  \-1.7e38?
 218 .Pp
 219 .Tn IEEE
 220 754 currently specifies that
 221 .Fn logb "denormalized no.\&"
 222 =
 223 .Fn logb "tiniest normalized no. > 0"
 224 but the consensus has changed to the specification in the new
 225 proposed
 226 .Tn IEEE
 227 standard p854, namely that
 228 .Fn logb x
 229 satisfy
 230 .Bd -ragged -offset indent
 231 1 \(<=
 232 .Fn scalb \\*(Bax\\*(Ba \-logb(x)
 233 <
 234 Radix\0 ... = 2
 235 for
 236 .Tn IEEE
 237 754
 238 .Ed
 239 .Pp
 240 for every x except 0,
 241 \*(If
 242 and \*(Na.
 243 Almost every program that assumes 754's specification will work
 244 correctly if
 245 .Fn logb
 246 follows 854's specification instead.
 247 .Pp
 248 .Tn IEEE
 249 754 requires
 250 .Fn copysign x \\*(Na)
 251 =
 252 .Pf \(+- Ns Fa x
 253 but says nothing
 254 else about the sign of a \*(Na.  A \*(Na
 255 .Em (N Ns ot
 256 .Em a
 257 .Em N Ns umber )
 258 is
 259 similar in spirit to the
 260 .Tn VAX Ns 's
 261 reserved operand, but very
 262 different in important details.  Since the sign bit of a
 263 reserved operand makes it look negative,
 264 .Bd -ragged -offset indent
 265 .Fn copysign x "reserved operand"
 266 =
 267 .Pf \- Fa x ;
 268 .Ed
 269 .Pp
 270 should this return the reserved operand instead?