lib/libc/gen/fpgetmask.3

   1 .\"     $NetBSD: fpgetmask.3,v 1.12 2011/03/27 22:55:07 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Ross Harvey.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd March 26, 2011
  31 .Dt FPGETMASK 3
  32 .Os
  33 .Sh NAME
  34 .Nm fpgetmask ,
  35 .Nm fpgetprec ,
  36 .Nm fpgetround ,
  37 .Nm fpgetsticky ,
  38 .Nm fpsetmask ,
  39 .Nm fpsetprec ,
  40 .Nm fpsetround ,
  41 .Nm fpsetsticky
  42 .Nd IEEE FP mode control
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In ieeefp.h
  47 .Ft fp_except_t
  48 .Fn fpgetmask void
  49 .Ft fp_prec_t
  50 .Fn fpgetprec void
  51 .Ft fp_rnd_t
  52 .Fn fpgetround void
  53 .Ft fp_except_t
  54 .Fn fpgetsticky void
  55 .Ft fp_except_t
  56 .Fn fpsetmask "fp_except_t mask"
  57 .Ft fp_prec_t
  58 .Fn fpsetprec "fp_prec_t prec"
  59 .Ft fp_rnd_t
  60 .Fn fpsetround "fp_rnd_t rnd_dir"
  61 .Ft fp_except_t
  62 .Fn fpsetsticky "fp_except_t sticky"
  63 .Sh DESCRIPTION
  64 A rounding mode
  65 .Ft fp_rnd_t
  66 is one of:
  67 .Bl -column -offset indent FP_RZ
  68 .It Dv FP_RZ Ta rounding towards Em zero
  69 .It Dv FP_RM Ta rounding down to Pq Em Minus infinity
  70 .It Dv FP_RN Ta rounding to Em nearest
  71 .It Dv FP_RP Ta rounding down to Pq Em Plus infinity
  72 .El
  73 The default mode is
  74 .Dv FP_RN .
  75 .Pp
  76 An
  77 .Ft fp_except_t
  78 value is a bitmask specifying an exception type and containing any of
  79 the values listed below.
  80 .Bl -column -offset indent FP_X_UFLxx
  81 .It Dv FP_X_INV Ta Invalid\ Operation
  82 .It Dv FP_X_DZ Ta Division\ by\ zero
  83 .It Dv FP_X_OFL Ta Overflow
  84 .It Dv FP_X_UFL Ta Underflow
  85 .It Dv FP_X_IMP Ta Imprecision (inexact)
  86 .It Dv FP_X_IOV Ta Integer\ Overflow
  87 .El
  88 .Pp
  89 An
  90 .Ft fp_prec_t
  91 specifies the precision of the floating point operations listed below.
  92 .Bl -column -offset indent FP_RPS
  93 .It Dv FP_PS Ta Dv 24 bit (single-precision)
  94 .It Dv FP_PRS Ta reserved
  95 .It Dv FP_PD Ta Dv 53 bit (double-precision)
  96 .It Dv FP_PE Ta Dv 64 bit (extended-precision)
  97 .El
  98 .Pp
  99 The
 100 .Fn fpsetmask
 101 function will set the current exception mask, i.e., it will cause
 102 future operations with the specified result status to raise the
 103 .Dv SIGFPE
 104 exception.
 105 The
 106 .Fn fpgetmask
 107 function will return the current exception mask.
 108 .Pp
 109 The
 110 .Fn fpgetprec
 111 function will return the current floating point precision.
 112 The
 113 .Fn fpsetprec
 114 function will set the floating point precision and will return
 115 the previous precision.
 116 .Pp
 117 The
 118 .Fn fpsetround
 119 function will cause future operations to use the specified dynamic
 120 rounding mode.
 121 The
 122 .Fn fpgetround
 123 function will return the current rounding mode.
 124 .Bl -tag -width Note:x
 125 .It Em Note :
 126 On some architectures, instructions can optionally specify static
 127 rounding modes and exception enables that will supersede the specified
 128 dynamic mode.
 129 On other architectures, these features may not be fully supported.
 130 .El
 131 .Pp
 132 A
 133 .Dq sticky
 134 status word may be maintained in which a bit is set every time an
 135 exceptional floating point condition is encountered, whether or not a
 136 .Dv SIGFPE
 137 is generated.
 138 The
 139 .Fn fpsetsticky
 140 function will set or clear the specified exception history bits.
 141 The
 142 .Fn fpgetsticky
 143 function will return the exception history bits.
 144 .Sh RETURN VALUES
 145 The
 146 .Fn fpgetround
 147 and
 148 .Fn fpsetround
 149 functions return the
 150 .Pq previous
 151 rounding mode.
 152 The
 153 .Fn fpgetmask ,
 154 .Fn fpsetmask ,
 155 .Fn fpgetsticky ,
 156 and
 157 .Fn fpsetsticky
 158 functions return the
 159 .Pq previous
 160 exception mask and exception history bits.
 161 .Sh SEE ALSO
 162 .Xr sigaction 2 ,
 163 .Xr fenv 3
 164 .Sh BUGS
 165 There is no way to return an unsupported value.
 166 Not all processors support all the modes.
 167 These interfaces are deprecated and the ones
 168 in
 169 .Xr fenv 3
 170 should be used, although the interfaces in
 171 .Xr fenv 3
 172 don't support getting or setting the precision.