share/man/man3/fpgetround.3

   1 .\" Copyright (c) 1993 Andrew Moore, Talke Studio
   2 .\" 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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd December 3, 2010
  29 .Dt FPGETROUND 3
  30 .Os
  31 .Sh NAME
  32 .Nm fpgetround ,
  33 .Nm fpsetround ,
  34 .Nm fpsetprec ,
  35 .Nm fpgetprec ,
  36 .Nm fpgetmask ,
  37 .Nm fpsetmask ,
  38 .Nm fpgetsticky ,
  39 .Nm fpresetsticky
  40 .Nd IEEE floating point interface
  41 .Sh SYNOPSIS
  42 .In ieeefp.h
  43 .Bd -literal
  44 typedef enum {
  45         FP_RN,          /* round to nearest */
  46         FP_RM,          /* round down to minus infinity */
  47         FP_RP,          /* round up to plus infinity */
  48         FP_RZ           /* truncate */
  49 } fp_rnd_t;
  50 .Ed
  51 .Ft fp_rnd_t
  52 .Fn fpgetround void
  53 .Ft fp_rnd_t
  54 .Fn fpsetround "fp_rnd_t direction"
  55 .Bd -literal
  56 typedef enum {
  57         FP_PS,          /* 24 bit (single-precision) */
  58         FP_PRS,         /* reserved */
  59         FP_PD,          /* 53 bit (double-precision) */
  60         FP_PE           /* 64 bit (extended-precision) */
  61 } fp_prec_t;
  62 .Ed
  63 .Ft fp_prec_t
  64 .Fn fpgetprec void
  65 .Ft fp_prec_t
  66 .Fn fpsetprec "fp_prec_t precision"
  67 .Bd -literal
  68 #define fp_except_t     int
  69 #define FP_X_INV        0x01    /* invalid operation */
  70 #define FP_X_DNML       0x02    /* denormal */
  71 #define FP_X_DZ         0x04    /* zero divide */
  72 #define FP_X_OFL        0x08    /* overflow */
  73 #define FP_X_UFL        0x10    /* underflow */
  74 #define FP_X_IMP        0x20    /* (im)precision */
  75 #define FP_X_STK        0x40    /* stack fault */
  76 .Ed
  77 .Ft fp_except_t
  78 .Fn fpgetmask void
  79 .Ft fp_except_t
  80 .Fn fpsetmask "fp_except_t mask"
  81 .Ft fp_except_t
  82 .Fn fpgetsticky void
  83 .Ft fp_except_t
  84 .Fn fpresetsticky "fp_except_t sticky"
  85 .Sh DESCRIPTION
  86 The routines described herein are deprecated.
  87 New code should use the functionality provided by
  88 .Xr fenv 3 .
  89 .Pp
  90 When a floating point exception is detected, the exception sticky flag is
  91 set and the exception mask is tested.
  92 If the mask is set, then a trap
  93 occurs.
  94 These routines allow both setting the floating point exception
  95 masks, and resetting the exception sticky flags after an exception is
  96 detected.
  97 In addition, they allow setting the floating point rounding mode
  98 and precision.
  99 .Pp
 100 The
 101 .Fn fpgetround
 102 function
 103 returns the current floating point rounding mode.
 104 .Pp
 105 The
 106 .Fn fpsetround
 107 function
 108 sets the floating point rounding mode and returns
 109 the previous mode.
 110 .Pp
 111 The
 112 .Fn fpgetprec
 113 function
 114 returns the current floating point precision.
 115 .Pp
 116 The
 117 .Fn fpsetprec
 118 function
 119 sets the floating point precision and returns
 120 the previous precision.
 121 .Pp
 122 The
 123 .Fn fpgetmask
 124 function
 125 returns the current floating point exception masks.
 126 .Pp
 127 The
 128 .Fn fpsetmask
 129 function
 130 sets the floating point exception masks and returns the
 131 previous masks.
 132 .Pp
 133 The
 134 .Fn fpgetsticky
 135 function
 136 returns the current floating point sticky flags.
 137 .Pp
 138 The
 139 .Fn fpresetsticky
 140 function
 141 clears the floating point sticky flags and returns
 142 the previous flags.
 143 .Pp
 144 Sample code which prevents a trap on divide-by-zero:
 145 .Bd -literal -offset indent
 146 fpsetmask(~FP_X_DZ);
 147 a = 1.0;
 148 b = 0;
 149 c = a / b;
 150 fpresetsticky(FP_X_DZ);
 151 fpsetmask(FP_X_DZ);
 152 .Ed
 153 .Sh IMPLEMENTATION NOTES
 154 The
 155 .Fn fpgetprec
 156 and
 157 .Fn fpsetprec
 158 functions provide functionality unavailable on many platforms.
 159 At present, they are implemented only on the i386 and amd64 platforms.
 160 Changing precision is not a supported feature:
 161 it may be ineffective when code is compiled to take advantage of SSE,
 162 and many library functions and compiler optimizations depend upon the
 163 default precision for correct behavior.
 164 .Sh SEE ALSO
 165 .Xr fenv 3 ,
 166 .Xr isnan 3
 167 .Sh HISTORY
 168 These routines are based on SysV/386 routines of the same name.
 169 .Sh CAVEATS
 170 After a floating point exception and before a mask is set, the sticky
 171 flags must be reset.
 172 If another exception occurs before the sticky
 173 flags are reset, then a wrong exception type may be signaled.