[linuxjm/LDP_man-pages.git] / draft / man7 / math_error.7

.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
.\"     <mtk.manpages@gmail.com>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" Japanese Version Copyright (c) 2008  Akihiro MOTOKI
.\"         all rights reserved.
.\" Translated 2008-08-17, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.07
.\" 
.\"WORD:        significand     仮数部
.\"WORD:        domain error    領域エラー
.\"WORD:        pole error      極エラー
.\"WORD:        range error     範囲エラー
.\" 
.TH MATH_ERROR 7 2008-08-11 "Linux" "Linux Programmer's Manual"
.\"O .SH NAME
.SH 名前
.\"O math_error \- detecting errors from mathematical functions
math_error \- 数学関数からのエラーの検出
.\"O .SH SYNOPSIS
.SH 書式
.nf
.B #include <math.h>
.B #include <errno.h>
.B #include <fenv.h>
.fi
.\"O .SH DESCRIPTION
.SH 説明
.\"O When an error occurs,
.\"O most library functions indicate this fact by returning a special value
.\"O (e.g., \-1 or NULL).
.\"O Because they typically return a floating-point number,
.\"O the mathematical functions declared in
.\"O .IR <math.h>
.\"O indicate an error using other mechanisms.
.\"O There are two error-reporting mechanisms:
.\"O the older one sets
.\"O .IR errno ;
.\"O the newer one uses the floating-point exception mechanism (the use of
.\"O .BR feclearexcept (3)
.\"O and
.\"O .BR fetestexcept (3),
.\"O as outlined below)
.\"O described in
.\"O .BR fenv (3).
エラーが発生すると、ほとんどのライブラリ関数は (\-1 や NULL などの)
特別な値を返すことでエラーを通知する。
.I <math.h>
で宣言されている数学関数は、通常は浮動小数点値を返すので、
他の機構を使ってエラーを通知する。
エラー通知機構は 2 種類あり、
古いものが
.I errno
を設定するやり方であり、新しいものが
.BR fenv (3)
で説明されている浮動小数点例外機構である。
.RB ( feclearexcept (3)
と
.BR fetestexcept (3)
を使用する。これらについては以下で概要を説明している。)

.\"O A portable program that needs to check for an error from a mathematical
.\"O function should set
.\"O .I errno
.\"O to zero, and make the following call
移植性が必要なプログラムで、数学関数からのエラーを確認する必要がある場合には、
数学関数を呼び出す前に
.I errno
を 0 に設定し、以下を呼び出すべきである。
.in +4n
.nf

feclearexcept(FE_ALL_EXCEPT);
.\"O 
.fi
.in
.\"O before calling a mathematical function.
.\"Omotoki: 対応する訳は feclearexcept の引用の前にある。

.\"O Upon return from the mathematical function, if
.\"O .I errno
.\"O is nonzero, or the following call (see
.\"O .BR fenv (3))
.\"O returns nonzero
数学関数から返ってきた際に、
.I errno
が 0 以外か、以下の呼び出しが 0 以外を返した場合
.RB ( fenv (3)
参照)、数学関数でエラーが発生している。
.in +4n
.nf

fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW |
             FE_UNDERFLOW);
.\"O 
.fi
.in
.\" enum
.\" {
.\" FE_INVALID = 0x01,
.\" __FE_DENORM = 0x02,
.\" FE_DIVBYZERO = 0x04,
.\" FE_OVERFLOW = 0x08,
.\" FE_UNDERFLOW = 0x10,
.\" FE_INEXACT = 0x20
.\" };
.\"O then an error occurred in the mathematical function.
.\"Omotoki: 対応する訳は fetestexcept の引用の前にある。

.\"O The error conditions that can occur for mathematical functions
.\"O are described below.
数学関数で発生するエラー条件については以下で説明する。
.\"O .SS Domain Error
.SS 領域エラー (domain error)
.\"O A
.\"O .I domain error
.\"O occurs when a mathematical function is supplied with an argument whose
.\"O value falls outside the domain for which the function
.\"O is defined (e.g., giving a negative argument to
.\"O .BR log (3)).
.\"O When a domain error occurs,
.\"O math functions commonly return a NaN
.\"O (though some functions return a different value in this case);
.\"O .I errno
.\"O is set to
.\"O .BR EDOM ,
.\"O and an "invalid"
.\"O .RB ( FE_INVALID )
.\"O floating-point exception is raised.
.I 領域エラー
が発生するのは、数学関数に渡された引き数の値がその関数が定義されている
領域に入っていない場合である (例えば
.BR log (3)
に負の引き数を渡した場合)。
領域エラーが発生すると、
数学関数は普通は NaN を返し
(同じ状況で違う値を返す関数もある)、
.I errno
に
.B EDOM
を設定し、「無効 (invalid)」
浮動小数点例外
.RB ( FE_INVALID )
を上げる。
.\"O .SS Pole Error
.SS 極エラー (pole error)
.\"O A
.\"O .I pole error
.\"O occurs when the mathematical result of a function is an exact infinity
.\"O (e.g., the logarithm of 0 is negative infinity).
.\"O When a pole error occurs,
.\"O the function returns the (signed) value
.\"O .BR HUGE_VAL ,
.\"O .BR HUGE_VALF ,
.\"O or
.\"O .BR HUGE_VALL ,
.\"O depending on whether the function result type is
.\"O .IR double ,
.\"O .IR float ,
.\"O or
.\"O .IR "long double" .
.\"O The sign of the result is that which is mathematically correct for
.\"O the function.
.I 極エラー
が発生するのは、関数の数学的な結果が無限大そのものとなる場合である
(例えば
0 の対数は負の無限大である)。
極エラーが発生すると、その関数の返り値は (符号付きの)
.BR HUGE_VAL ,
.BR HUGE_VALF ,
.B HUGE_VALL
のいずれかとなる (前記の値のうちどれが返るかは関数の返り値の型により決まり、
それぞれ
.IR double ,
.IR float ,
.I "long double"
に対応する)。
結果の符号は、その関数の数学的な定義から決定される。
.\"O .I errno
.\"O is set to
.\"O .BR ERANGE ,
.\"O and a "divide-by-zero"
.\"O .RB ( FE_DIVBYZERO )
.\"O floating-point exception is raised.
.I errno
は
.B ERANGE
に設定され、「0 による除算 (divide-by-zero)」
浮動小数点例外
.RB ( FE_DIVBYZERO )
が上がる。
.\"O .SS Range Error
.SS 範囲エラー (range エラー)
.\"O A
.\"O .I range error
.\"O occurs when the magnitude of the function result means that it
.\"O cannot be represented in the result type of the function.
.\"O The return value of the function depends on whether the range error
.\"O was an overflow or an underflow.
.I 範囲エラー
が発生するのは、関数の結果の値がその関数の返り値の型では表現できない場合
である。関数の返り値は、範囲エラーがオーバーフローであったかアンダーフロー
であったかによって異なる。

.\"O A floating result
.\"O .I overflows
.\"O if the result is finite,
.\"O but is too large to represented in the result type.
.\"O When an overflow occurs,
.\"O the function returns the value
.\"O .BR HUGE_VAL ,
.\"O .BR HUGE_VALF ,
.\"O or
.\"O .BR HUGE_VALL ,
.\"O depending on whether the function result type is
.\"O .IR double ,
.\"O .IR float ,
.\"O or
.\"O .IR "long double" .
.\"O .I errno
.\"O is set to
.\"O .BR ERANGE ,
.\"O and an "overflow"
.\"O .RB ( FE_OVERFLOW )
.\"O floating-point exception is raised.
浮動小数点のオーバーフローは、結果が有限だが、大き過ぎて
結果を返す型では表現できない場合に発生する。
オーバーフローが発生すると、
その関数は
.BR HUGE_VAL ,
.BR HUGE_VALF ,
.B HUGE_VALL
のいずれかを返す (前記の値のうちどれが返るかは関数の返り値の型により決まり、
それぞれ
.IR double ,
.IR float ,
.I "long double"
に対応する)。
.I errno
は
.B ERANGE
に設定され、「オーバーフロー (overflow)」
浮動小数点例外
.RB ( FE_OVERFLOW )
が上がる。

.\"O A floating result
.\"O .I underflows
.\"O if the result is too small to be represented in the result type.
.\"O If an underflow occurs,
.\"O a mathematical function typically returns 0.0
.\"O (C99 says a function shall return "an implementation-defined value
.\"O whose magnitude is no greater than the smallest normalized
.\"O positive number in the specified type").
浮動小数点のアンダーフローは、
結果が小さ過ぎて、結果を返す型では表現できない場合に発生する。
アンダーフローが発生すると、数学関数は通常は 0.0 を返す
(C99 では、指定された型において最小の正規化された正の値より大きくない
値を持つ実装定義 (implementation-defined) の値を返す、となっている)。
.\"O .I errno
.\"O may be set to
.\"O .BR ERANGE ,
.\"O and an "overflow"
.\"O .RB ( FE_UNDERFLOW )
.\"O floating-point exception may be raised.
.I errno
は
.B ERANGE
に設定され、「アンダーフロー」浮動小数点例外
.RB ( FE_UNDERFLOW )
が上がる。

.\"O Some functions deliver a range error if the supplied argument value,
.\"O or the correct function result, would be
.\"O .IR subnormal .
.\"O A subnormal value is one that is nonzero,
.\"O but with a magnitude that is so small that
.\"O it can't be presented in normalized form
.\"O (i.e., with a 1 in the most significant bit of the significand).
.\"O The representation of a subnormal number will contain one
.\"O or more leading zeros in the significand.
いくつかの関数では、渡された引き数の値や、正しい関数の結果が
.I subnormal (非正規化数)
になる場合に範囲エラーを上げる。
subnormal な値とは、0 ではないが、その値が小さすぎて
(仮数部の最上位ビットが 1 となる) 標準形では表現できないような値である。
subnormal な値の表現では、仮数部の上位側のビットに 1 個以上の 0 が
含まれることになる。
.\"O .SH NOTES
.SH 注意
.\"O The
.\"O .I math_errhandling
.\"O identifier specified by C99 and POSIX.1-2001 is not supported by glibc.
C99 と POSIX.1-2001 で規定されている
.I math_errhandling
識別子は glibc ではサポートされていない。
.\" See CONFORMANCE in the glibc 2.8 (and earlier) source.
.\"O This identifier is supposed to indicate which of the two
.\"O error-notification mechanisms
.\"O .RI ( errno ,
.\"O exceptions retrievable via
.\"O .BR fettestexcept (3))
.\"O is in use.
この識別子は、2 つのエラー通知機構
.RI ( errno
と
.BR fetestexcept (3)
経由で取得できる例外) のうちどちらが使用されているかを通知
することになっている。
.\"O The standards require that at least one be in use,
.\"O but permit both to be available.
.\"O The current (version 2.8) situation under glibc is messy.
.\"O Most (but not all) functions raise exceptions on errors.
.\"O Some also set
.\"O .IR errno .
.\"O A few functions set
.\"O .IR errno ,
.\"O but don't raise an exception.
.\"O A very few functions do neither.
.\"O See the individual manual pages for details.
標準では、少なくとも一つは使用されることが要求されているが、
両方とも利用可能であってもよいとされている。
glibc での現在の (バージョン 2.8 での) 状況はかなり混乱している。
ほとんどの関数 (ただし全部ではない) はエラー時に例外を上げる。
いくつかの関数は
.I errno
も設定する。
.I errno
を設定するが、例外を上げない関数も少しだけ存在する。
どちらも行わない関数もごく少数だが存在する。
詳細については個々のマニュアルページを参照のこと。

.\"O To avoid the complexities of using
.\"O .I errno
.\"O and
.\"O .BR fetestexcept (3)
.\"O for error checking,
.\"O it is often advised that one should instead check for bad argument
.\"O values before each call.
.I errno
と
.BR fetestexcept (3)
の両方を使ってエラーチェックを行うことで複雑になるのを避けるため、
多くの場合、関数呼び出しを行う前に不正な引き数かのチェックを行う
方法が推奨されている。
.\" http://www.securecoding.cert.org/confluence/display/seccode/FLP32-C.+Prevent+or+detect+domain+and+range+errors+in+math+functions
.\"O For example, the following code ensures that
.\"O .BR log (3)'s
.\"O argument is not a NaN and is not zero (a pole error) or
.\"O less than zero (a domain error):
例えば、以下のコードは、
.BR log (3)
の引き数が NaN でも (極エラーとなる) 0 でも (領域エラーとなる) 0 未満
でもないことを保証するものである。
.in +4n
.nf

double x, r;

if (isnan(x) || islessequal(x, 0)) {
    /* Deal with NaN / pole error / domain error */
}

r = log(x);

.fi
.in
.\"O The discussion on this page does not apply to the complex
.\"O mathematical functions (i.e., those declared by
.\"O .IR <complex.h> ),
.\"O which in general are not required to return errors by C99
.\"O and POSIX.1-2001.
このページに書かれていることは、
.RI ( <complex.h>
で宣言されている) 複素数関数にはあてはまらない。
一般に、C99 や POSIX.1-2001 ではこれらの関数がエラーを返すことを
要求してない。

.\"O The
.\"O .BR gcc (1)
.\"O .I "-fno-math-errno"
.\"O option causes the executable to employ implementations of some
.\"O mathematical functions that are faster than the standard
.\"O implementations, but do not set
.\"O .I errno
.\"O on error.
.\"O (The
.\"O .BR gcc (1)
.\"O .I "-ffast-math"
.\"O option also enables
.\"O .IR "-fno-math-errno" .)
.\"O An error can still be tested for using
.\"O .BR fetestexcept (3).
.BR gcc (1)
の
.I "-fno-math-errno"
オプションを使うと、実行ファイルで、標準の実装よりも高速な数学関数の
実装が使用されるようになるが、
エラー時に
.I errno
が設定されない
.RB ( gcc (1)
の
.I "-ffast-math"
オプションを指定した場合にも
.I "-fno-math-errno"
は有効になる)。
このオプションを指定した場合でも、
.BR fetestexcept (3)
を使ったエラーの検査は可能である。
.\"O .SH SEE ALSO
.SH 関連項目
.BR gcc (1),
.BR errno (3),
.BR fenv (3),
.BR fpclassify (3),
.BR INFINITY (3),
.BR isgreater (3),
.BR matherr (3),
.BR nan (3)
.br
.I "info libc"