lib/libm/common_source/infnan.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 .\"     @(#)infnan.3    8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libm/common_source/infnan.3,v 1.4.2.6 2001/12/17 10:08:31 ru Exp $
  34 .\"
  35 .Dd June 4, 1993
  36 .Dt INFNAN 3
  37 .Os
  38 .Sh NAME
  39 .Nm infnan
  40 .Nd signals invalid floating\-point operations on a
  41 .Tn VAX
  42 (temporary)
  43 .Sh LIBRARY
  44 .Lb libm
  45 .Sh SYNOPSIS
  46 .In math.h
  47 .Ft double
  48 .Fn infnan "int iarg"
  49 .Sh DESCRIPTION
  50 At some time in the future, some of the useful properties of
  51 the Infinities and \*(Nas in the
  52 .Tn IEEE
  53 standard 754 for Binary
  54 Floating\-Point Arithmetic will be simulated in
  55 .Tn UNIX
  56 on the
  57 .Tn DEC VAX
  58 by using its Reserved Operands.  Meanwhile, the
  59 Invalid, Overflow and Divide\-by\-Zero exceptions of the
  60 .Tn IEEE
  61 standard are being approximated on a
  62 .Tn VAX
  63 by calls to a
  64 procedure
  65 .Fn infnan
  66 in appropriate places in
  67 .Xr libm 3 .
  68 When
  69 better exception\-handling is implemented in
  70 .Tn UNIX ,
  71 only
  72 .Fn infnan
  73 among the codes in
  74 .Xr libm
  75 will have to be changed.
  76 And users of
  77 .Xr libm
  78 can design their own
  79 .Fn infnan
  80 now to
  81 insulate themselves from future changes.
  82 .Pp
  83 Whenever an elementary function code in
  84 .Xr libm
  85 has to
  86 simulate one of the aforementioned
  87 .Tn IEEE
  88 exceptions, it calls
  89 .Fn infnan iarg
  90 with an appropriate value of
  91 .Fa iarg .
  92 Then a
  93 reserved operand fault stops computation.  But
  94 .Fn infnan
  95 could
  96 be replaced by a function with the same name that returns
  97 some plausible value, assigns an apt value to the global
  98 variable
  99 .Va errno ,
 100 and allows computation to resume.
 101 Alternatively, the Reserved Operand Fault Handler could be
 102 changed to respond by returning that plausible value, etc.\&
 103 instead of aborting.
 104 .Pp
 105 In the table below, the first two columns show various
 106 exceptions signaled by the
 107 .Tn IEEE
 108 standard, and the default
 109 result it prescribes.  The third column shows what value is
 110 given to
 111 .Fa iarg
 112 by functions in
 113 .Xr libm
 114 when they
 115 invoke
 116 .Fn infnan iarg
 117 under analogous circumstances on a
 118 .Tn VAX .
 119 Currently
 120 .Fn infnan
 121 stops computation under all those
 122 circumstances.  The last two columns offer an alternative;
 123 they suggest a setting for
 124 .Va errno
 125 and a value for a
 126 revised
 127 .Fn infnan
 128 to return.  And a C program to
 129 implement that suggestion follows.
 130 .Bl -column "IEEE Signal" "IEEE Default" XXERANGE ERANGEXXorXXEDOM
 131 .It "IEEE Signal        IEEE Default    " Fa iarg Ta Va errno Ta Fn infnan
 132 .It "Invalid    \*(Na   " Er "EDOM      EDOM    0"
 133 .It "Overflow   \(+-\*(If       " Er "ERANGE    ERANGE" Ta Dv HUGE
 134 .It "Div\-by\-0 \(+-Infinity    " Er "\(+-ERANGE        ERANGE or EDOM" Ta Dv \(+-HUGE
 135 .El
 136 .Bd -ragged -offset center -compact
 137 .Dv ( HUGE
 138 = 1.7e38 ... nearly 2.0**127)
 139 .Ed
 140 .Pp
 141 ALTERNATIVE
 142 .Fn infnan :
 143 .Bd -literal -offset indent
 144 #include        <math.h>
 145 #include        <errno.h>
 146 extern int      errno ;
 147 double  infnan(iarg)
 148 int     iarg ;
 149 {
 150         switch(iarg) {
 151         case    \0ERANGE:       errno = ERANGE; return(HUGE);
 152         case    \-ERANGE:       errno = EDOM;   return(\-HUGE);
 153         default:                errno = EDOM;   return(0);
 154         }
 155 }
 156 .Ed
 157 .Sh SEE ALSO
 158 .Xr intro 2 ,
 159 .Xr math 3 ,
 160 .Xr signal 3
 161 .Pp
 162 .Er ERANGE
 163 and
 164 .Er EDOM
 165 are defined in
 166 .Aq Pa errno.h .
 167 (See
 168 .Xr intro 2
 169 for explanation of
 170 .Er EDOM
 171 and
 172 .Er ERANGE . )
 173 .Sh HISTORY
 174 The
 175 .Fn infnan
 176 function appeared in
 177 .Bx 4.3 .