OSDN Git Service

(split) Convert release and draft pages to UTF-8.
[linuxjm/LDP_man-pages.git] / draft / 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 .\"O .SH NAME
39 .SH 名前
40 .\"O feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag,
41 .\"O fetestexcept, fegetenv, fegetround, feholdexcept, fesetround,
42 .\"O fesetenv, feupdateenv, feenableexcept, fedisableexcept,
43 .\"O fegetexcept \- floating-point rounding and exception handling
44 feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag,
45 fetestexcept, fegetenv, fegetround, feholdexcept, fesetround,
46 fesetenv, feupdateenv, feenableexcept, fedisableexcept,
47 fegetexcept \- 浮動小数点の丸めと例外の取り扱い
48 .\"O .SH SYNOPSIS
49 .SH 書式
50 .nf
51 .B #include <fenv.h>
52 .sp
53 .BI "int feclearexcept(int " excepts );
54 .br
55 .BI "int fegetexceptflag(fexcept_t *" flagp ", int " excepts );
56 .br
57 .BI "int feraiseexcept(int " excepts );
58 .br
59 .BI "int fesetexceptflag(const fexcept_t *" flagp ", int " excepts );
60 .br
61 .BI "int fetestexcept(int " excepts );
62 .sp
63 .B "int fegetround(void);"
64 .br
65 .BI "int fesetround(int " rounding_mode );
66 .sp
67 .BI "int fegetenv(fenv_t *" envp );
68 .br
69 .BI "int feholdexcept(fenv_t *" envp );
70 .br
71 .BI "int fesetenv(const fenv_t *" envp );
72 .br
73 .BI "int feupdateenv(const fenv_t *" envp );
74 .fi
75 .sp
76 .\"O Link with \fI\-lm\fP.
77 \fI\-lm\fP でリンクする。
78 .\"O .SH DESCRIPTION
79 .SH 説明
80 .\"O These eleven functions were defined in C99, and describe the handling
81 .\"O of floating-point rounding and exceptions (overflow, zero-divide etc.).
82 これらの 11 個の関数は C99 で定義されており、
83 浮動小数点の丸めと例外 (オーバーフロー、ゼロによる除算など)
84 の取り扱いを規定する。
85 .\"O .SS Exceptions
86 .SS 例外
87 .\"O The
88 .\"O .I divide-by-zero
89 .\"O exception occurs when an operation on finite numbers
90 .\"O produces infinity as exact answer.
91 .I divide-by-zero
92 例外は、有限の数値に対する演算が、
93 無限大の答えを生成するような場合に起こる。
94 .LP
95 .\"O The
96 .\"O .I overflow
97 .\"O exception occurs when a result has to be represented as a
98 .\"O floating-point number, but has (much) larger absolute value than the
99 .\"O largest (finite) floating-point number that is representable.
100 .I overflow
101 例外は、結果が浮動小数点数値で表記されなければならないのに、
102 その絶対値が表現可能な浮動小数点数の (有限の) 最大値よりも
103 (ずっと) 大きくなってしまうような場合に起こる。
104 .LP
105 .\"O The
106 .\"O .I underflow
107 .\"O exception occurs when a result has to be represented as a
108 .\"O floating-point number, but has smaller absolute value than the smallest
109 .\"O positive normalized floating-point number (and would lose much accuracy
110 .\"O when represented as a denormalized number).
111 .I underflow
112 例外は、結果が浮動小数点数値で表記されなければならないのに、
113 その絶対値が正の正規化浮動小数点数の最小値よりも
114 小さくなってしまう
115 (そして 非正規化数で表現した場合に非常に精度を失ってしまう)
116 ような場合に起こる。
117 .LP
118 .\"O The
119 .\"O .I inexact
120 .\"O exception occurs when the rounded result of an operation
121 .\"O is not equal to the infinite precision result.
122 .\"O It may occur whenever
123 .\"O .I overflow
124 .\"O or
125 .\"O .I underflow
126 .\"O occurs.
127 .I inexact
128 例外は、丸め後の演算結果が、
129 無限精度の結果と異なるような場合に起こる。
130 .I overflow
131 例外か
132 .I underflow
133 例外が起きたときには、常にこの例外も起こる。
134 .LP
135 .\"O The
136 .\"O .I invalid
137 .\"O exception occurs when there is no well-defined result
138 .\"O for an operation, as for 0/0 or infinity \- infinity or sqrt(\-1).
139 .I invalid
140 例外は、演算結果がうまく定義できない結果を生じるような場合に起こる。
141 例えば 0/0、無限大 \- 無限大、sqrt(\-1) など。
142 .\"O .SS "Exception handling"
143 .SS 例外処理
144 .\"O Exceptions are represented in two ways: as a single bit
145 .\"O (exception present/absent), and these bits correspond in some
146 .\"O implementation-defined way with bit positions in an integer,
147 .\"O and also as an opaque structure that may contain more information
148 .\"O about the exception (perhaps the code address where it occurred).
149 例外の表し方には 2 つの方法がある。
150 ひとつは、単一のビットで (例外があったかなかったかを) 表す方法で、
151 これらのビットは整数のあるビット位置に対応し、ビットの対応付けは
152 実装依存である。もう一つは、内部構造体を使って表す方法で、
153 この方法の方が例外に関するより多くの情報
154 (例えば例外が起こったコードのアドレスなど) が含まれる。
155 .LP
156 .\"O Each of the macros
157 .\"O .BR FE_DIVBYZERO ,
158 .\"O .BR FE_INEXACT ,
159 .\"O .BR FE_INVALID ,
160 .\"O .BR FE_OVERFLOW ,
161 .\"O .B FE_UNDERFLOW
162 .\"O is defined when the implementation supports handling
163 .\"O of the corresponding exception, and if so then
164 .\"O defines the corresponding bit(s), so that one can call
165 .\"O exception handling functions, for example, using the integer argument
166 .\"O .BR FE_OVERFLOW | FE_UNDERFLOW .
167 .\"O Other exceptions may be supported.
168 .\"O The macro
169 .\"O .B FE_ALL_EXCEPT
170 .\"O is the bitwise OR of all bits corresponding to supported exceptions.
171 .BR FE_DIVBYZERO ,
172 .BR FE_INEXACT ,
173 .BR FE_INVALID ,
174 .BR FE_OVERFLOW ,
175 .B FE_UNDERFLOW
176 の各マクロは、それぞれ対応する例外の処理を
177 実装がサポートしている場合に定義される。
178 このとき対応するビットをそれぞれ定義することになるので、
179 例外処理関数の呼び出しを、例えば
180 .BR FE_OVERFLOW | FE_UNDERFLOW
181 という整数の引き数を用いて行うことができる。
182 他の例外もサポートされているかもしれない。
183 .B FE_ALL_EXCEPT
184 マクロは、サポートされている例外に対応するビットが全てセットされている
185 (サポートされている例外全ての論理和である)。
186 .PP
187 .\"O The
188 .\"O .BR feclearexcept ()
189 .\"O function clears the supported exceptions represented by the bits
190 .\"O in its argument.
191 .BR feclearexcept ()
192 関数は、引き数
193 .I excepts
194 のビット列で指定された例外をクリアする
195 (処理は実装でサポートされている例外についてのみ行われる)。
196 .LP
197 .\"O The
198 .\"O .BR fegetexceptflag ()
199 .\"O function stores a representation of the state of the exception flags
200 .\"O represented by the argument
201 .\"O .I excepts
202 .\"O in the opaque object
203 .\"O .IR *flagp .
204 .BR fegetexceptflag ()
205 関数は、引き数
206 .I excepts
207 で指定された例外フラグの状態を
208 .I *flagp
209 が指す内部オブジェクトに保存する。
210 .LP
211 .\"O The
212 .\"O .BR feraiseexcept ()
213 .\"O function raises the supported exceptions represented by the bits in
214 .\"O .IR excepts .
215 .BR feraiseexcept ()
216 関数は、
217 .I excepts
218 のビット列で指定された例外のうち、
219 実装がサポートしているものを発生させる。
220 .LP
221 .\"O The
222 .\"O .BR fesetexceptflag ()
223 .\"O function sets the complete status for the exceptions represented by
224 .\"O .I excepts
225 .\"O to the value
226 .\"O .IR *flagp .
227 .\"O This value must have been obtained by an earlier call of
228 .\"O .BR fegetexceptflag ()
229 .\"O with a last argument that contained all bits in
230 .\"O .IR excepts .
231 .BR fesetexceptflag ()
232 関数は、
233 .I excepts
234 で指定された例外に対応するフラグの状態を
235 .I *flagp
236 の値に設定する。
237 .I *flagp
238 の値は、この関数を呼ぶ前に
239 .BR fegetexceptflag ()
240 関数を呼び出して取得しておかなければならない
241 (このとき、
242 .BR fegetexceptflag ()
243 の最後の引き数には、
244 .BR fesetexceptflag ()
245 に渡す
246 .I excepts
247 のすべてのビットを含む値を指定すること)。
248 .LP
249 .\"O The
250 .\"O .BR fetestexcept ()
251 .\"O function returns a word in which the bits are set that were
252 .\"O set in the argument
253 .\"O .I excepts
254 .\"O and for which the corresponding exception is currently set.
255 .BR fetestexcept ()
256 関数は、
257 .I excepts
258 引き数でセットされているビットのうち、
259 現在設定されている例外に対応するビットが 1 になったワードを返す。
260 .\"O .SS Rounding mode
261 .SS 丸めモード
262 .\"O The rounding mode determines how the result of floating-point operations
263 .\"O is treated when the result cannot be exactly represented in the significand.
264 .\"O Various rounding modes may be provided:
265 .\"O round to nearest (the default),
266 .\"O round up (toward positive infinity),
267 .\"O round down (toward negative infinity), and
268 .\"O round toward zero.
269 丸めモードは、結果が仮数部だけで正確に表現できない際に、
270 浮動小数点操作の結果をどのように扱うかを決めるものである。
271 さまざまな丸めモードを提供することができる:
272 最も近い値に丸める (デフォルト)、
273 (正の無限大に向かって) 大きくなる方向に丸める、
274 (負の無限大に向かって) 小さくなる方向に丸める、
275 0 に向けて丸める、である。
276
277 .\"O Each of the macros
278 .\"O .BR FE_TONEAREST ,
279 .\"O .BR FE_UPWARD ,
280 .\"O .BR FE_DOWNWARD ,
281 .\"O and
282 .\"O .BR FE_TOWARDZERO
283 .\"O is defined when the implementation supports getting and setting
284 .\"O the corresponding rounding direction.
285 .BR FE_TONEAREST ,
286 .BR FE_UPWARD ,
287 .BR FE_DOWNWARD ,
288 .BR FE_TOWARDZERO
289 の各マクロは、それぞれ対応する丸めの方向を
290 実装がサポートしている場合に定義される。
291 .LP
292 .\"O The
293 .\"O .BR fegetround ()
294 .\"O function returns the macro corresponding to the current
295 .\"O rounding mode.
296 .BR fegetround ()
297 関数は現在の丸めモードに対応するマクロを返す。
298 .LP
299 .\"O The
300 .\"O .BR fesetround ()
301 .\"O function sets the rounding mode as specified by its argument
302 .\"O and returns zero when it was successful.
303 .BR fesetround ()
304 関数は丸めモードを引き数に与えられた値にし、
305 成功したらゼロを返す。
306
307 .\"O C99 and POSIX.1-2008 specify an identifier,
308 .\"O .BR FLT_ROUNDS ,
309 .\"O defined in
310 .\"O .IR <float.h> ,
311 .\"O which indicates the implementation-defined rounding
312 .\"O behavior for floating-point addition.
313 .\"O This identifier has one of the following values:
314 C99 と POSIX.1-2008 では
315 .B FLT_ROUNDS
316 という識別子が規定されており、
317 .I <float.h>
318 で定義されている。この識別子は
319 浮動小数点数の加算についての実装定義された丸め動作を表し、
320 以下のいずれかの値を持つ。
321 .IP \-1
322 .\"O The rounding mode is not determinable.
323 丸めモードは決められていない。
324 .IP 0
325 .\"O Rounding is toward 0.
326 0 に向けて丸める。
327 .IP 1
328 .\"O Rounding is toward nearest number.
329 最も近い数に丸める。
330 .IP 2
331 .\"O Rounding is toward positive infinity.
332 正の無限大に向けて丸める。
333 .IP 3
334 .\"O Rounding is toward negative infinity.
335 負の無限大に向けて丸める。
336 .PP
337 .\"O Other values represent machine-dependent, nonstandard rounding modes.
338 他の値はマシン依存であり、標準的ではない丸めモードである。
339 .PP
340 .\"O The value of
341 .\"O .BR FLT_ROUNDS
342 .\"O should reflect the current rounding mode as set by
343 .\"O .BR fesetround ()
344 .\"O (but see BUGS).
345 .BR FLT_ROUNDS
346 の値には、
347 .BR fesetround ()
348 で設定された現在の丸めモードが反映されるべきである
349 (但し、「バグ」の節を参照)。
350 .\"O .SS "Floating-point environment"
351 .SS 浮動小数点関連の環境
352 .\"O The entire floating-point environment, including
353 .\"O control modes and status flags, can be handled
354 .\"O as one opaque object, of type
355 .\"O .IR fenv_t .
356 .\"O The default environment is denoted by
357 .\"O .B FE_DFL_ENV
358 .\"O (of type
359 .\"O .IR "const fenv_t *" ).
360 浮動小数点関連の環境の全体は、
361 制御モードや状態フラグも含め、
362 .I fenv_t
363 型の内部オブジェクト一つで取り扱うことができる。
364 デフォルトの環境は、
365 .RI ( "const fenv_t *"
366 型の)
367 .B FE_DFL_ENV
368 で示されるものである。
369 .\"O This is the environment setup at program start and it is defined by
370 .\"O ISO C to have round to nearest, all exceptions cleared and a nonstop
371 .\"O (continue on exceptions) mode.
372 これはプログラムの開始時に構築される環境であり、
373 ISO C では、丸めモードを最も近い値への丸め
374 .RB ( FE_TONEAREST )
375 に設定し、すべての例外をクリアし、不停止 (nonstop)
376 (例外が起きても継続する) モードとするように規定されている。
377 .LP
378 .\"O The
379 .\"O .BR fegetenv ()
380 .\"O function saves the current floating-point environment in the object
381 .\"O .IR *envp .
382 .BR fegetenv ()
383 関数は、現在の浮動小数点環境を、オブジェクト
384 .I *envp
385 に保存する。
386 .LP
387 .\"O The
388 .\"O .BR feholdexcept ()
389 .\"O function does the same, then clears all exception flags,
390 .\"O and sets a nonstop (continue on exceptions) mode,
391 .\"O if available.
392 .\"O It returns zero when successful.
393 .BR feholdexcept ()
394 関数も同じ動作を行い、
395 さらに可能であれば、全ての例外フラグをクリアし、
396 nonstop (例外時にも実行を継続) モードに設定する。
397 .LP
398 .\"O The
399 .\"O .BR fesetenv ()
400 .\"O function restores the floating-point environment from
401 .\"O the object
402 .\"O .IR *envp .
403 .\"O This object must be known to be valid, for example, the result of a call to
404 .\"O .BR fegetenv ()
405 .\"O or
406 .\"O .BR feholdexcept ()
407 .\"O or equal to
408 .\"O .BR FE_DFL_ENV .
409 .\"O This call does not raise exceptions.
410 .BR fesetenv ()
411 関数は、浮動小数点環境を、オブジェクト
412 .I *envp
413 から取り出した値に戻す。
414 このオブジェクトは、有効であることが事前に分かっていなければならない。
415 例えば、
416 .BR fegetenv ()
417
418 .BR feholdexcept ()
419 を呼び出した結果であるとか、
420 .B FE_DFL_ENV
421 に等しいとかでなければならない。
422 この関数の呼び出しは例外を発生しない。
423 .LP
424 .\"O The
425 .\"O .BR feupdateenv ()
426 .\"O function installs the floating-point environment represented by
427 .\"O the object
428 .\"O .IR *envp ,
429 .\"O except that currently raised exceptions are not cleared.
430 .\"O After calling this function, the raised exceptions will be a bitwise OR
431 .\"O of those previously set with those in
432 .\"O .IR *envp .
433 .\"O As before, the object
434 .\"O .I *envp
435 .\"O must be known to be valid.
436 .BR feupdateenv ()
437 関数は、オブジェクト
438 .I *envp
439 が表現する浮動小数点環境をインストールする。
440 ただし、現在発生している例外はクリアされない。
441 この関数を呼んだ後に立っている例外は、
442 関数を呼ぶ前の値と
443 .I *envp
444 の値とのビットごとの OR を取ったものになる。
445 上記と同様に、オブジェクト
446 .I *envp
447 は、事前に有効であることが分かっていなければならない。
448 .\"O .SH "RETURN VALUE"
449 .SH 返り値
450 .\"O These functions return zero on success and nonzero if an error occurred.
451 .\"O .\" Earlier seven of these functions were listed as returning void.
452 .\"O .\" This was corrected in Corrigendum 1 (ISO/IEC 9899:1999/Cor.1:2001(E))
453 .\"O .\" of the C99 Standard.
454 これらの関数は、成功の場合 0 を返し、エラーが発生すると 0 以外を返す。
455 .\" 以前は、これらの関数のうち 7つは void を返すものと書かれていた。
456 .\" これは C99 標準の Corrigendum 1 (ISO/IEC 9899:1999/Cor.1:2001(E))
457 .\" で修正された。
458 .\"O .SH VERSIONS
459 .SH バージョン
460 .\"O These functions first appeared in glibc in version 2.1.
461 これらの関数は glibc バージョン 2.1 で初めて登場した。
462 .\"O .SH "CONFORMING TO"
463 .SH 準拠
464 IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99, POSIX.1-2001.
465 .\"O .SH NOTES
466 .SH 注意
467 .\"O .SS Glibc Notes
468 .SS glibc での注意
469 .\"O If possible, the GNU C Library defines a macro
470 .\"O .B FE_NOMASK_ENV
471 .\"O which represents an environment where every exception raised causes a
472 .\"O trap to occur.
473 .\"O You can test for this macro using
474 .\"O .BR #ifdef .
475 .\"O It is only defined if
476 .\"O .B _GNU_SOURCE
477 .\"O is defined.
478 可能な場合には、GNU C Library はマクロ
479 .B FE_NOMASK_ENV
480 を定義する。このマクロはすべての例外でトラップが生じるような環境を表す。
481 .B #ifdef
482 を使ってこのマクロをテストできる。これは
483 .B _GNU_SOURCE
484 が定義されている場合に限って定義される。
485 .\"O The C99 standard does not define a way to set individual bits in the
486 .\"O floating-point mask, for example, to trap on specific flags.
487 .\"O Since version 2.2, glibc supports the functions
488 .\"O .BR feenableexcept ()
489 .\"O and
490 .\"O .BR fedisableexcept ()
491 .\"O to set individual floating-point traps, and
492 .\"O .BR fegetexcept ()
493 .\"O to query the state.
494 C99 標準は浮動小数点マスク (例えば特定のフラグでのトラップなど)
495 の各ビットの設定方法については定義していない。
496 バージョン 2.2 以降の glibc は、
497 .BR feenableexcept ()
498 関数と
499 .BR fedisableexcept ()
500 関数をサポートしており、
501 各々の浮動小数点トラップを設定できるようになっている。
502 また
503 .BR fegetexcept ()
504 によって状態の問い合わせもできるようになっている。
505 .sp
506 .nf
507 .\"O .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
508 .BR "#define _GNU_SOURCE" "         /* feature_test_macros(7) 参照 */"
509 .B "#define _GNU_SOURCE"
510 .br
511 .B "#include <fenv.h>"
512 .sp
513 .BI "int feenableexcept(int " excepts );
514 .br
515 .BI "int fedisableexcept(int " excepts );
516 .br
517 .B "int fegetexcept(void);"
518 .br
519 .fi
520 .LP
521 .\"O The
522 .\"O .BR feenableexcept ()
523 .\"O and
524 .\"O .BR fedisableexcept ()
525 .\"O functions enable (disable) traps for each of the exceptions represented by
526 .\"O .I excepts
527 .\"O and return the previous set of enabled exceptions when successful,
528 .\"O and \-1 otherwise.
529 .\"O The
530 .\"O .BR fegetexcept ()
531 .\"O function returns the set of all currently enabled exceptions.
532 .BR feenableexcept ()
533 関数と
534 .BR fedisableexcept ()
535 関数は
536 .I excepts
537 によって表現される各例外のトラップを有効 (無効) にする。
538 成功した場合は直前に有効になっていた例外のセットを返す。
539 失敗した場合は \-1 を返す。
540 .BR fegetexcept ()
541 関数は現在有効になっている例外全てからなるセットを返す。
542 .\"O .SH BUGS
543 .SH バグ
544 .\"O C99 specifies that the value of
545 .\"O .B FLT_ROUNDS
546 .\"O should reflect changes to the current rounding mode, as set by
547 .\"O .BR fesetround ().
548 C99 の規定では、
549 .BR FLT_ROUNDS
550 の値には
551 .BR fesetround ()
552 で設定された現在の丸めモードが反映されるべきであるとされている。
553 .\"O Currently,
554 現在のところ、
555 .\" Aug 08, glibc 2.8
556 .\"O this does not occur:
557 .\"O .B FLT_ROUNDS
558 .\"O always has the value 1.
559 このようになっておらず、
560 .B FLT_ROUNDS
561 は常に値 1 となる。
562 .\" See http://gcc.gnu.org/ml/gcc/2002-02/msg01535.html
563 .\"O .SH "SEE ALSO"
564 .SH 関連項目
565 .BR math_error (7)