release/man3/fenv.3

   1 .\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  21 .\" USA.
  22 .\"
  23 .\" 2000-08-14 added GNU additions from Andreas Jaeger
  24 .\" 2000-12-05 some changes inspired by acahalan's remarks
  25 .\"
  26 .\" Japanese Version Copyright (c) 2000-2001 NAKANO Takeo
  27 .\" and Copyright (c) 2008 Akihiro MOTOKI.
  28 .\" Translated 2001-02-08, NAKANO Takeo <nakano@apm.seikei.ac.jp>
  29 .\" Updated 2003-10-15, Kentaro Shirakata <argrath@ub32.org>
  30 .\" Updated 2005-02-26, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  31 .\" Updated 2008-09-16, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  32 .\"
  33 .\"WORD:        (floating-point) exception      (浮動小数点) 例外
  34 .\"WORD:        rounding                        丸め
  35 .\"WORD:        opaque                          内部の
  36 .\"
  37 .TH FENV 3  2010-10-31 "Linux" "Linux Programmer's Manual"
  38 .SH 名前
  39 feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag,
  40 fetestexcept, fegetenv, fegetround, feholdexcept, fesetround,
  41 fesetenv, feupdateenv, feenableexcept, fedisableexcept,
  42 fegetexcept \- 浮動小数点の丸めと例外の取り扱い
  43 .SH 書式
  44 .nf
  45 .B #include <fenv.h>
  46 .sp
  47 .BI "int feclearexcept(int " excepts );
  48 .br
  49 .BI "int fegetexceptflag(fexcept_t *" flagp ", int " excepts );
  50 .br
  51 .BI "int feraiseexcept(int " excepts );
  52 .br
  53 .BI "int fesetexceptflag(const fexcept_t *" flagp ", int " excepts );
  54 .br
  55 .BI "int fetestexcept(int " excepts );
  56 .sp
  57 .B "int fegetround(void);"
  58 .br
  59 .BI "int fesetround(int " rounding_mode );
  60 .sp
  61 .BI "int fegetenv(fenv_t *" envp );
  62 .br
  63 .BI "int feholdexcept(fenv_t *" envp );
  64 .br
  65 .BI "int fesetenv(const fenv_t *" envp );
  66 .br
  67 .BI "int feupdateenv(const fenv_t *" envp );
  68 .fi
  69 .sp
  70 \fI\-lm\fP でリンクする。
  71 .SH 説明
  72 これらの 11 個の関数は C99 で定義されており、
  73 浮動小数点の丸めと例外 (オーバーフロー、ゼロによる除算など)
  74 の取り扱いを規定する。
  75 .SS 例外
  76 .I divide-by-zero
  77 例外は、有限の数値に対する演算が、
  78 無限大の答えを生成するような場合に起こる。
  79 .LP
  80 .I overflow
  81 例外は、結果が浮動小数点数値で表記されなければならないのに、
  82 その絶対値が表現可能な浮動小数点数の (有限の) 最大値よりも
  83 (ずっと) 大きくなってしまうような場合に起こる。
  84 .LP
  85 .I underflow
  86 例外は、結果が浮動小数点数値で表記されなければならないのに、
  87 その絶対値が正の正規化浮動小数点数の最小値よりも
  88 小さくなってしまう
  89 (そして 非正規化数で表現した場合に非常に精度を失ってしまう)
  90 ような場合に起こる。
  91 .LP
  92 .I inexact
  93 例外は、丸め後の演算結果が、
  94 無限精度の結果と異なるような場合に起こる。
  95 .I overflow
  96 例外か
  97 .I underflow
  98 例外が起きたときには、常にこの例外も起こる。
  99 .LP
 100 .I invalid
 101 例外は、演算結果がうまく定義できない結果を生じるような場合に起こる。
 102 例えば 0/0、無限大 \- 無限大、sqrt(\-1) など。
 103 .SS 例外処理
 104 例外の表し方には 2 つの方法がある。
 105 ひとつは、単一のビットで (例外があったかなかったかを) 表す方法で、
 106 これらのビットは整数のあるビット位置に対応し、ビットの対応付けは
 107 実装依存である。もう一つは、内部構造体を使って表す方法で、
 108 この方法の方が例外に関するより多くの情報
 109 (例えば例外が起こったコードのアドレスなど) が含まれる。
 110 .LP
 111 .BR FE_DIVBYZERO ,
 112 .BR FE_INEXACT ,
 113 .BR FE_INVALID ,
 114 .BR FE_OVERFLOW ,
 115 .B FE_UNDERFLOW
 116 の各マクロは、それぞれ対応する例外の処理を
 117 実装がサポートしている場合に定義される。
 118 このとき対応するビットをそれぞれ定義することになるので、
 119 例外処理関数の呼び出しを、例えば
 120 .BR FE_OVERFLOW | FE_UNDERFLOW
 121 という整数の引き数を用いて行うことができる。
 122 他の例外もサポートされているかもしれない。
 123 .B FE_ALL_EXCEPT
 124 マクロは、サポートされている例外に対応するビットが全てセットされている
 125 (サポートされている例外全ての論理和である)。
 126 .PP
 127 .BR feclearexcept ()
 128 関数は、引き数
 129 .I excepts
 130 のビット列で指定された例外をクリアする
 131 (処理は実装でサポートされている例外についてのみ行われる)。
 132 .LP
 133 .BR fegetexceptflag ()
 134 関数は、引き数
 135 .I excepts
 136 で指定された例外フラグの状態を
 137 .I *flagp
 138 が指す内部オブジェクトに保存する。
 139 .LP
 140 .BR feraiseexcept ()
 141 関数は、
 142 .I excepts
 143 のビット列で指定された例外のうち、
 144 実装がサポートしているものを発生させる。
 145 .LP
 146 .BR fesetexceptflag ()
 147 関数は、
 148 .I excepts
 149 で指定された例外に対応するフラグの状態を
 150 .I *flagp
 151 の値に設定する。
 152 .I *flagp
 153 の値は、この関数を呼ぶ前に
 154 .BR fegetexceptflag ()
 155 関数を呼び出して取得しておかなければならない
 156 (このとき、
 157 .BR fegetexceptflag ()
 158 の最後の引き数には、
 159 .BR fesetexceptflag ()
 160 に渡す
 161 .I excepts
 162 のすべてのビットを含む値を指定すること)。
 163 .LP
 164 .BR fetestexcept ()
 165 関数は、
 166 .I excepts
 167 引き数でセットされているビットのうち、
 168 現在設定されている例外に対応するビットが 1 になったワードを返す。
 169 .SS 丸めモード
 170 丸めモードは、結果が仮数部だけで正確に表現できない際に、
 171 浮動小数点操作の結果をどのように扱うかを決めるものである。
 172 さまざまな丸めモードを提供することができる:
 173 最も近い値に丸める (デフォルト)、
 174 (正の無限大に向かって) 大きくなる方向に丸める、
 175 (負の無限大に向かって) 小さくなる方向に丸める、
 176 0 に向けて丸める、である。
 177
 178 .BR FE_TONEAREST ,
 179 .BR FE_UPWARD ,
 180 .BR FE_DOWNWARD ,
 181 .BR FE_TOWARDZERO
 182 の各マクロは、それぞれ対応する丸めの方向を
 183 実装がサポートしている場合に定義される。
 184 .LP
 185 .BR fegetround ()
 186 関数は現在の丸めモードに対応するマクロを返す。
 187 .LP
 188 .BR fesetround ()
 189 関数は丸めモードを引き数に与えられた値にし、
 190 成功したらゼロを返す。
 191
 192 C99 と POSIX.1-2008 では
 193 .B FLT_ROUNDS
 194 という識別子が規定されており、
 195 .I <float.h>
 196 で定義されている。この識別子は
 197 浮動小数点数の加算についての実装定義された丸め動作を表し、
 198 以下のいずれかの値を持つ。
 199 .IP \-1
 200 丸めモードは決められていない。
 201 .IP 0
 202 0 に向けて丸める。
 203 .IP 1
 204 最も近い数に丸める。
 205 .IP 2
 206 正の無限大に向けて丸める。
 207 .IP 3
 208 負の無限大に向けて丸める。
 209 .PP
 210 他の値はマシン依存であり、標準的ではない丸めモードである。
 211 .PP
 212 .BR FLT_ROUNDS
 213 の値には、
 214 .BR fesetround ()
 215 で設定された現在の丸めモードが反映されるべきである
 216 (但し、「バグ」の節を参照)。
 217 .SS 浮動小数点関連の環境
 218 浮動小数点関連の環境の全体は、
 219 制御モードや状態フラグも含め、
 220 .I fenv_t
 221 型の内部オブジェクト一つで取り扱うことができる。
 222 デフォルトの環境は、
 223 .RI ( "const fenv_t *"
 224 型の)
 225 .B FE_DFL_ENV
 226 で示されるものである。
 227 これはプログラムの開始時に構築される環境であり、
 228 ISO C では、丸めモードを最も近い値への丸め
 229 .RB ( FE_TONEAREST )
 230 に設定し、すべての例外をクリアし、不停止 (nonstop)
 231 (例外が起きても継続する) モードとするように規定されている。
 232 .LP
 233 .BR fegetenv ()
 234 関数は、現在の浮動小数点環境を、オブジェクト
 235 .I *envp
 236 に保存する。
 237 .LP
 238 .BR feholdexcept ()
 239 関数も同じ動作を行い、
 240 さらに可能であれば、全ての例外フラグをクリアし、
 241 nonstop (例外時にも実行を継続) モードに設定する。
 242 .LP
 243 .BR fesetenv ()
 244 関数は、浮動小数点環境を、オブジェクト
 245 .I *envp
 246 から取り出した値に戻す。
 247 このオブジェクトは、有効であることが事前に分かっていなければならない。
 248 例えば、
 249 .BR fegetenv ()
 250 や
 251 .BR feholdexcept ()
 252 を呼び出した結果であるとか、
 253 .B FE_DFL_ENV
 254 に等しいとかでなければならない。
 255 この関数の呼び出しは例外を発生しない。
 256 .LP
 257 .BR feupdateenv ()
 258 関数は、オブジェクト
 259 .I *envp
 260 が表現する浮動小数点環境をインストールする。
 261 ただし、現在発生している例外はクリアされない。
 262 この関数を呼んだ後に立っている例外は、
 263 関数を呼ぶ前の値と
 264 .I *envp
 265 の値とのビットごとの OR を取ったものになる。
 266 上記と同様に、オブジェクト
 267 .I *envp
 268 は、事前に有効であることが分かっていなければならない。
 269 .SH 返り値
 270 これらの関数は、成功の場合 0 を返し、エラーが発生すると 0 以外を返す。
 271 .\" 以前は、これらの関数のうち 7つは void を返すものと書かれていた。
 272 .\" これは C99 標準の Corrigendum 1 (ISO/IEC 9899:1999/Cor.1:2001(E))
 273 .\" で修正された。
 274 .SH バージョン
 275 これらの関数は glibc バージョン 2.1 で初めて登場した。
 276 .SH 準拠
 277 IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99, POSIX.1-2001.
 278 .SH 注意
 279 .SS glibc での注意
 280 可能な場合には、GNU C Library はマクロ
 281 .B FE_NOMASK_ENV
 282 を定義する。このマクロはすべての例外でトラップが生じるような環境を表す。
 283 .B #ifdef
 284 を使ってこのマクロをテストできる。これは
 285 .B _GNU_SOURCE
 286 が定義されている場合に限って定義される。
 287 C99 標準は浮動小数点マスク (例えば特定のフラグでのトラップなど)
 288 の各ビットの設定方法については定義していない。
 289 バージョン 2.2 以降の glibc は、
 290 .BR feenableexcept ()
 291 関数と
 292 .BR fedisableexcept ()
 293 関数をサポートしており、
 294 各々の浮動小数点トラップを設定できるようになっている。
 295 また
 296 .BR fegetexcept ()
 297 によって状態の問い合わせもできるようになっている。
 298 .sp
 299 .nf
 300 .BR "#define _GNU_SOURCE" "         /* feature_test_macros(7) 参照 */"
 301 .B "#define _GNU_SOURCE"
 302 .br
 303 .B "#include <fenv.h>"
 304 .sp
 305 .BI "int feenableexcept(int " excepts );
 306 .br
 307 .BI "int fedisableexcept(int " excepts );
 308 .br
 309 .B "int fegetexcept(void);"
 310 .br
 311 .fi
 312 .LP
 313 .BR feenableexcept ()
 314 関数と
 315 .BR fedisableexcept ()
 316 関数は
 317 .I excepts
 318 によって表現される各例外のトラップを有効 (無効) にする。
 319 成功した場合は直前に有効になっていた例外のセットを返す。
 320 失敗した場合は \-1 を返す。
 321 .BR fegetexcept ()
 322 関数は現在有効になっている例外全てからなるセットを返す。
 323 .SH バグ
 324 C99 の規定では、
 325 .BR FLT_ROUNDS
 326 の値には
 327 .BR fesetround ()
 328 で設定された現在の丸めモードが反映されるべきであるとされている。
 329 現在のところ、
 330 .\" Aug 08, glibc 2.8
 331 このようになっておらず、
 332 .B FLT_ROUNDS
 333 は常に値 1 となる。
 334 .\" See http://gcc.gnu.org/ml/gcc/2002-02/msg01535.html
 335 .SH 関連項目
 336 .BR math_error (7)