リナックスコマンド

fenvのヘルプ・マニュアル

日本語 英語

• help
• man

fenv --help

man fenv

FENV(3) Linux Programmer’s Manual FENV(3) 名前 feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, fetes- texcept, fegetenv, fegetround, feholdexcept, fesetround, fesetenv, feupdateenv, feenableexcept, fedisableexcept, fegetexcept - 浮動小数点 の丸めと例外の取り扱い 書式 #include int feclearexcept(int excepts); int fegetexceptflag(fexcept_t *flagp, int excepts); int feraiseexcept(int excepts); int fesetexceptflag(const fexcept_t *flagp, int excepts); int fetestexcept(int excepts); int fegetround(void); int fesetround(int rounding_mode); int fegetenv(fenv_t *envp); int feholdexcept(fenv_t *envp); int fesetenv(const fenv_t *envp); int feupdateenv(const fenv_t *envp); -lm でリンクする。 説明 これらの 11 個の関数は C99 で定義されており、浮動小数点の丸めと例外 (オ ーバーフロー、ゼロによる除算など) の取り扱いを規定する。 例外 divide-by-zero 例外は、有限の数値に対する演算が、無限大の答えを生成する ような場合に起こる。 overflow 例外は、結果が浮動小数点数値で表記されなければならないのに、そ の 絶対値が表現可能な浮動小数点数の (有限の) 最大値よりも (ずっと) 大き くなってしまうような場合に起こる。 underflow 例外は、結果が浮動小数点数値で表記されなければならないのに 、 そ の絶対値が正の正規化浮動小数点数の最小値よりも小さくなってしまう (そ して 非正規化数で表現した場合に非常に精度を失ってしまう) ような場合に起 こる。 inexact 例外は、丸め後の演算結果が、無限精度の結果と異なるような場合に 起こる。 overflow 例外か underflow 例外が起きたときには、常にこの例外も 起こる。 invalid 例外は、演算結果がうまく定義できない結果を生じるような場合に起 こる。例えば 0/0、無限大 - 無限大、sqrt(-1) など。 例外処理 例外の表し方には 2 つの方法がある。ひとつは、単一のビットで (例外があっ た かなかったかを) 表す方法で、これらのビットは整数のあるビット位置に対 応し、ビットの対応付けは実装依存である。もう一つは、内部構造体を使っ て 表 す方法で、この方法の方が例外に関するより多くの情報 (例えば例外が起こ ったコードのアドレスなど) が含まれる。 FE_DIVBYZERO, FE_INEXACT, FE_INVALID, FE_OVERFLOW, FE_UNDERFLOW の各 マ ク ロは、それぞれ対応する例外の処理を実装がサポートしている場合に定義さ れる。このとき対応するビットをそれぞれ定義することになるので、例外処 理 関 数の呼び出しを、例えば FE_OVERFLOW|FE_UNDERFLOW という整数の引き数を 用いて行うことができる。他の例外もサポートされているかも し れ な い 。 FE_ALL_EXCEPT マクロは、サポートされている例外に対応するビットが全てセ ットされている (サポートされている例外全ての論理和である)。 feclearexcept() 関数は、引き数 excepts のビット列で指定された例外をクリ アする (処理は実装でサポートされている例外についてのみ行われる)。 fegetexceptflag() 関数は、引き数 excepts で指定された例外フラグの状態を *flagp が指す内部オブジェクトに保存する。 feraiseexcept() 関数は、 excepts のビット列で指定された例外のうち、実装 がサポートしているものを発生させる。 fesetexceptflag() 関数は、 excepts で指定された例外に対応するフラグの状 態を *flagp の値に設定する。 *flagp の値は、この関数を呼ぶ前に fegetex- ceptflag() 関 数 を呼び出して取得しておかなければならない (このとき、 fegetexceptflag() の最後の引き数には、 fesetexceptflag() に渡す excepts のすべてのビットを含む値を指定すること)。 fetestexcept() 関数は、 excepts 引き数でセットされているビットのうち、 現在設定されている例外に対応するビットが 1 になったワードを返す。 丸めモード 丸めモードは、結果が仮数部だけで正確に表現できない際に、浮動小数点操 作 の 結果をどのように扱うかを決めるものである。さまざまな丸めモードを提供 することができる: 最も近い値に丸める (デフォルト)、 (正の無限大に向かっ て) 大きくなる方向に丸める、 (負の無限大に向かって) 小さくなる方向に丸 める、 0 に向けて丸める、である。 FE_TONEAREST, FE_UPWARD, FE_DOWNWARD, FE_TOWARDZERO の各マクロは、そ れ ぞれ対応する丸めの方向を実装がサポートしている場合に定義される。 fegetround() 関数は現在の丸めモードに対応するマクロを返す。 fesetround() 関数は丸めモードを引き数に与えられた値にし、成功したらゼロ を返す。 C99 と POSIX.1-2008 では FLT_ROUNDS という識別子が規定さ れ て お り 、 で定義されている。この識別子は浮動小数点数の加算についての実 装定義された丸め動作を表し、以下のいずれかの値を持つ。 -1 丸めモードは決められていない。 0 0 に向けて丸める。 1 最も近い数に丸める。 2 正の無限大に向けて丸める。 3 負の無限大に向けて丸める。 他の値はマシン依存であり、標準的ではない丸めモードである。 FLT_ROUNDS の値には、 fesetround() で設定された現在の丸めモードが反映さ れるべきである (但し、「バグ」の節を参照)。 浮動小数点関連の環境 浮 動小数点関連の環境の全体は、制御モードや状態フラグも含め、 fenv_t 型 の内部オブジェクト一つで取り扱うことができる。デフォルト の 環 境 は 、 (const fenv_t * 型の) FE_DFL_ENV で示されるものである。これはプログラム の開始時に構築される環境であり、 ISO C では、丸めモードを最も近い値への 丸め (FE_TONEAREST) に設定し、すべての例外をクリアし、不停止 (non-stop) (例外が起きても継続する) モードとするように規定されている。 fegetenv() 関数は、現在の浮動小数点環境を、オブジェクト *envp に保存 す る。 feholdexcept() 関数も同じ動作を行い、さらに可能であれば、全ての例外フラ グをクリアし、 non-stop (例外時にも実行を継続) モードに設定する。 fesetenv() 関数は、浮動小数点環境を、オブジェクト *envp から取り出し た 値 に戻す。このオブジェクトは、有効であることが事前に分かっていなければ ならない。例えば、 fegetenv() や feholdexcept() を呼び出した結果であ る と か、 FE_DFL_ENV に等しいとかでなければならない。この関数の呼び出しは 例外を発生しない。 feupdateenv() 関数は、オブジェクト *envp が表現する浮動小数点環境をイン ス トールする。ただし、現在発生している例外はクリアされない。この関数を 呼んだ後に立っている例外は、関数を呼ぶ前の値と *envp の値とのビットごと の OR を取ったものになる。上記と同様に、オブジェクト *envp は、事前に有 効であることが分かっていなければならない。 返り値 これらの関数は、成功の場合 0 を返し、エラーが発生すると 0 以外を返す。 バージョン これらの関数は glibc バージョン 2.1 で初めて登場した。 準拠 IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99, POSIX.1-2001. 注意 glibc での注意 可能な場合には、GNU C Library はマクロ FE_NOMASK_ENV を定義する。このマ ク ロはすべての例外でトラップが生じるような環境を表す。 #ifdef を使って このマクロをテストできる。これは _GNU_SOURCE が定義されている場合に限っ て定義される。 C99 標準は浮動小数点マスク (例えば特定のフラグでのトラッ プなど) の各ビットの設定方法については定義していない。 glibc 2.2 は feenableexcept() 関数と fedisableexcept() 関数をサポートしており、各々 の浮動小数点トラップを設定できるようになっている。また fegetexcept() に よって状態の問い合わせもできるようになっている。 #define _GNU_SOURCE #include int feenableexcept(int excepts); int fedisableexcept(int excepts); int fegetexcept(void); feenebleexcept() 関数と fedisableexcept() 関数は excepts によって表現さ れる各例外のトラップを有効 (無効) にする。成功した場合は直前に有効に な っていた例外のセットを返す。失敗した場合は -1 を返す。 fegetexcept() 関 数は現在有効になっている例外全てからなるセットを返す。 バグ C99 の規定では、 FLT_ROUNDS の値には fesetround() で設定された現在の 丸 め モードが反映されるべきであるとされている。現在のところ、このようにな っておらず、 FLT_ROUNDS は常に値 1 となる。 関連項目 feature_test_macros(7), math_error(7) Linux 2008-08-11 FENV(3)

FENV(3) Linux Programmer’s Manual FENV(3) NAME feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, fetes- texcept, fegetenv, fegetround, feholdexcept, fesetround, fesetenv, feupdateenv, feenableexcept, fedisableexcept, fegetexcept - floating- point rounding and exception handling SYNOPSIS #include int feclearexcept(int excepts); int fegetexceptflag(fexcept_t *flagp, int excepts); int feraiseexcept(int excepts); int fesetexceptflag(const fexcept_t *flagp, int excepts); int fetestexcept(int excepts); int fegetround(void); int fesetround(int rounding_mode); int fegetenv(fenv_t *envp); int feholdexcept(fenv_t *envp); int fesetenv(const fenv_t *envp); int feupdateenv(const fenv_t *envp); Link with -lm. DESCRIPTION These eleven functions were defined in C99, and describe the handling of floating-point rounding and exceptions (overflow, zero-divide etc.). Exceptions The divide-by-zero exception occurs when an operation on finite numbers produces infinity as exact answer. The overflow exception occurs when a result has to be represented as a floating-point number, but has (much) larger absolute value than the largest (finite) floating-point number that is representable. The underflow exception occurs when a result has to be represented as a floating-point number, but has smaller absolute value than the smallest positive normalized floating-point number (and would lose much accuracy when represented as a denormalized number). The inexact exception occurs when the rounded result of an operation is not equal to the infinite precision result. It may occur whenever overflow or underflow occurs. The invalid exception occurs when there is no well-defined result for an operation, as for 0/0 or infinity - infinity or sqrt(-1). Exception handling Exceptions are represented in two ways: as a single bit (exception present/absent), and these bits correspond in some implementation- defined way with bit positions in an integer, and also as an opaque structure that may contain more information about the exception (per- haps the code address where it occurred). Each of the macros FE_DIVBYZERO, FE_INEXACT, FE_INVALID, FE_OVERFLOW, FE_UNDERFLOW is defined when the implementation supports handling of the corresponding exception, and if so then defines the corresponding bit(s), so that one can call exception handling functions, for example, using the integer argument FE_OVERFLOW|FE_UNDERFLOW. Other exceptions may be supported. The macro FE_ALL_EXCEPT is the bitwise OR of all bits corresponding to supported exceptions. The feclearexcept() function clears the supported exceptions repre- sented by the bits in its argument. The fegetexceptflag() function stores a representation of the state of the exception flags represented by the argument excepts in the opaque object *flagp. The feraiseexcept() function raises the supported exceptions repre- sented by the bits in excepts. The fesetexceptflag() function sets the complete status for the excep- tions represented by excepts to the value *flagp. This value must have been obtained by an earlier call of fegetexceptflag() with a last argu- ment that contained all bits in excepts. The fetestexcept() function returns a word in which the bits are set that were set in the argument excepts and for which the corresponding exception is currently set. Rounding mode The rounding mode determines how the result of floating-point opera- tions is treated when the result cannot be exactly represented in the signifcand. Various rounding modes may be provided: round to nearest (the default), round up (towards positive infinity), round down (towards negative infinity), and round towards zero. Each of the macros FE_TONEAREST, FE_UPWARD, FE_DOWNWARD, and FE_TOWARDZERO is defined when the implementation supports getting and setting the corresponding rounding direction. The fegetround() function returns the macro corresponding to the cur- rent rounding mode. The fesetround() function sets the rounding mode as specified by its argument and returns zero when it was successful. C99 and POSIX.1-2008 specify an identifier, FLT_ROUNDS, defined in , which indicates the implementation-defined rounding behavior for floating-point addition. This identifier has one of the following values: -1 The rounding mode is not determinable. 0 Rounding is towards 0. 1 Rounding is towards nearest number. 2 Rounding is towards positive infinity. 3 Rounding is towards negative infinity. Other values represent machine-dependent, non-standard rounding modes. The value of FLT_ROUNDS should reflect the current rounding mode as set by fesetround() (but see BUGS). Floating-point environment The entire floating-point environment, including control modes and sta- tus flags, can be handled as one opaque object, of type fenv_t. The default environment is denoted by FE_DFL_ENV (of type const fenv_t *). This is the environment setup at program start and it is defined by ISO C to have round to nearest, all exceptions cleared and a non-stop (con- tinue on exceptions) mode. The fegetenv() function saves the current floating-point environment in the object *envp. The feholdexcept() function does the same, then clears all exception flags, and sets a non-stop (continue on exceptions) mode, if available. It returns zero when successful. The fesetenv() function restores the floating-point environment from the object *envp. This object must be known to be valid, for example, the result of a call to fegetenv() or feholdexcept() or equal to FE_DFL_ENV. This call does not raise exceptions. The feupdateenv() function installs the floating-point environment rep- resented by the object *envp, except that currently raised exceptions are not cleared. After calling this function, the raised exceptions will be a bitwise OR of those previously set with those in *envp. As before, the object *envp must be known to be valid. RETURN VALUE These functions return zero on success and non-zero if an error occurred. VERSIONS These functions first appeared in glibc in version 2.1. CONFORMING TO IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99, POSIX.1-2001. NOTES Glibc Notes If possible, the GNU C Library defines a macro FE_NOMASK_ENV which rep- resents an environment where every exception raised causes a trap to occur. You can test for this macro using #ifdef. It is only defined if _GNU_SOURCE is defined. The C99 standard does not define a way to set individual bits in the floating-point mask, for example, to trap on specific flags. glibc 2.2 supports the functions feenableexcept() and fedisableexcept() to set individual floating-point traps, and fegetex- cept() to query the state. #define _GNU_SOURCE #include int feenableexcept(int excepts); int fedisableexcept(int excepts); int fegetexcept(void); The feenableexcept() and fedisableexcept() functions enable (disable) traps for each of the exceptions represented by excepts and return the previous set of enabled exceptions when successful, and -1 otherwise. The fegetexcept() function returns the set of all currently enabled exceptions. BUGS C99 specifies that the value of FLT_ROUNDS should reflect changes to the current rounding mode, as set by fesetround(). Currently, this does not occur: FLT_ROUNDS always has the value 1. SEE ALSO feature_test_macros(7), math_error(7) COLOPHON This page is part of release 3.22 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/. Linux 2008-08-11 FENV(3)