usr/src/man/man3c/fpgetround.3c

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH FPGETROUND 3C "Dec 29, 1996"
   7 .SH NAME
   8 fpgetround, fpsetround, fpgetmask, fpsetmask, fpgetsticky, fpsetsticky \- IEEE
   9 floating-point environment control
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <ieeefp.h>
  14
  15 \fBfp_rnd\fR \fBfpgetround\fR(\fBvoid\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBfp_rnd\fR \fBfpsetround\fR(\fBfp_rnd\fR \fIrnd_dir\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBfp_except\fR \fBfpgetmask\fR(\fBvoid\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBfp_except\fR \fBfpsetmask\fR(\fBfp_except\fR \fImask\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBfp_except\fR \fBfpgetsticky\fR(\fBvoid\fR);
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBfp_except\fR \fBfpsetsticky\fR(\fBfp_except\fR \fIsticky\fR);
  41 .fi
  42
  43 .SH DESCRIPTION
  44 .sp
  45 .LP
  46 There are five floating-point exceptions:
  47 .RS +4
  48 .TP
  49 .ie t \(bu
  50 .el o
  51 divide-by-zero,
  52 .RE
  53 .RS +4
  54 .TP
  55 .ie t \(bu
  56 .el o
  57 overflow,
  58 .RE
  59 .RS +4
  60 .TP
  61 .ie t \(bu
  62 .el o
  63 underflow,
  64 .RE
  65 .RS +4
  66 .TP
  67 .ie t \(bu
  68 .el o
  69 imprecise (inexact) result, and
  70 .RE
  71 .RS +4
  72 .TP
  73 .ie t \(bu
  74 .el o
  75 invalid operation.
  76 .RE
  77 .sp
  78 .LP
  79 When a floating-point exception occurs, the corresponding sticky bit is set
  80 (1), and if the mask bit is enabled (1), the trap takes place. These routines
  81 let the user change the behavior on occurrence of any of these exceptions, as
  82 well as change the rounding mode for floating-point operations.
  83 .sp
  84 .LP
  85 The \fImask\fR argument is formed by the logical OR operation of the following
  86 floating-point exception masks:
  87 .sp
  88 .in +2
  89 .nf
  90 \fBFP_X_INV       /* invalid operation exception */
  91 FP_X_OFL       /* overflow exception */
  92 FP_X_UFL       /* underflow exception */
  93 FP_X_DZ        /* divide-by-zero exception */
  94 FP_X_IMP       /* imprecise (loss of precision) */\fR
  95 .fi
  96 .in -2
  97
  98 .sp
  99 .LP
 100 The following floating-point rounding modes are passed to  \fBfpsetround\fR and
 101 returned by  \fBfpgetround()\fR.
 102 .sp
 103 .in +2
 104 .nf
 105 FP_RN       /* round to nearest representative number */
 106 FP_RP       /* round to plus infinity */
 107 FP_RM       /* round to minus infinity */
 108 FP_RZ       /* round to zero (truncate) */
 109 .fi
 110 .in -2
 111
 112 .sp
 113 .LP
 114 The default environment is rounding mode set to nearest (\fBFP_RN\fR) and all
 115 traps disabled.
 116 .sp
 117 .LP
 118 The \fBfpsetsticky()\fR function modifies all sticky flags. The
 119 \fBfpsetmask()\fR function changes all mask bits. The \fBfpsetmask()\fR
 120 function clears the sticky bit corresponding to any exception being enabled.
 121 .SH RETURN VALUES
 122 .sp
 123 .LP
 124 The \fBfpgetround()\fR function returns the current rounding mode.
 125 .sp
 126 .LP
 127 The \fBfpsetround()\fR function sets the rounding mode and returns the previous
 128 rounding mode.
 129 .sp
 130 .LP
 131 The \fBfpgetmask()\fR function returns the current exception masks.
 132 .sp
 133 .LP
 134 The \fBfpsetmask()\fR function sets the exception masks and returns the
 135 previous setting.
 136 .sp
 137 .LP
 138 The \fBfpgetsticky()\fR function returns the current exception sticky flags.
 139 .sp
 140 .LP
 141 The \fBfpsetsticky()\fR function sets (clears) the exception sticky flags and
 142 returns the previous setting.
 143 .SH USAGE
 144 .sp
 145 .LP
 146 The C programming language requires truncation (round to zero) for floating
 147 point to integral conversions. The current rounding mode has no effect on these
 148 conversions.
 149 .sp
 150 .LP
 151 The sticky bit must be cleared to recover from the trap  and proceed.  If the
 152 sticky bit is not cleared before the next trap occurs, a wrong exception type
 153 may be signaled.
 154 .sp
 155 .LP
 156 Individual bits may be examined using the constants defined in
 157 \fB<ieeefp.h>\fR\&.
 158 .SH ATTRIBUTES
 159 .sp
 160 .LP
 161 See \fBattributes\fR(5) for descriptions of the following attributes:
 162 .sp
 163
 164 .sp
 165 .TS
 166 box;
 167 c | c
 168 l | l .
 169 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 170 _
 171 MT-Level        MT-Safe
 172 .TE
 173
 174 .SH SEE ALSO
 175 .sp
 176 .LP
 177 \fBisnand\fR(3C), \fBattributes\fR(5)