fenv(3)

BEZEICHNUNG
feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, fetestexcept, fegetenv, fegetround, feholdexcept, fesetround, fesetenv, feupdateenv, feenableexcept, fedisableexcept, fegetexcept - Umgang mit Fließkomma-Runden und -Ausnahmen

BIBLIOTHEK
Mathematik-Bibliothek (libm, -lm)

ÜBERSICHT
#include <fenv.h>

int feclearexcept(int Ausnahmen);
int fegetexceptflag(fexcept_t *Schalterz, int Ausnahmen);
int feraiseexcept(int Ausnahmen);
int fesetexceptflag(const fexcept_t *Schalterz, int Ausnahmen);
int fetestexcept(int Ausnahmen);

int fegetround(void);
int fesetround(int Rundungsmodus);

int fegetenv(fenv_t *Umgz);
int feholdexcept(fenv_t *Umgz);
int fesetenv(const fenv_t *Umgz);
int feupdateenv(const fenv_t *Umgz);

BESCHREIBUNG
Diese elf Funktionen wurden in C99 definiert und beschreiben die Handhabung beim Runden von Fließkommazahlen und Ausnahmen (Überlauf, Teilen durch Null, usw.).

  Ausnahmen
Die Ausnahme divide-by-zero (Teilen durch Null) tritt auf, wenn eine Operation auf einer endlichen Zahl als Ergebnis genau unendlich produziert.

Die Ausnahme overflow (Überlauf) tritt auf, wenn ein Ergebnis als Fließkommazahl dargestellt werden muss, aber einen (viel) größeren absoluten Wert als die größte (endliche) Fließkommazahl hat, die darstellbar ist.

Die Ausnahme underflow (Unterlauf) tritt auf, wenn ein Ergebnis als Fließkommazahl dargestellt werden muss, aber einen kleineren absoluten Wert als die kleinste positive normalisierte Fließkommazahl hat (und sehr viel Genauigkeit verlieren würde, wenn sie als denormalisierte Zahl dargestellt würde).

Die Ausnahme inexact (ungenau) tritt auf, wenn das gerundete Ergebnis einer Operation nicht identisch zu dem Ergebnis mit unendlicher Genauigkeit ist. Sie kann immer auftreten, wenn overflow oder underflow auftritt.

Die Ausnahme invalid (ungültig) tritt auf, wenn es kein gut definiertes Ergebnis für eine Operation gibt, wie bei 0/0 oder unendlich - unendlich oder sqrt(-1).

  Ausnahmebehandlung
Ausnahmen werden auf zwei Arten dargestellt: als einzelnes Bit (Ausnahme vorhanden/abwesend) und diese Bits entsprechen auf eine implementierungsabhängige Art den Bit-Positionen in einer Ganzzahl und als undurchsichtige Struktur, die weitere Informationen über die Ausnahme enthalten könnte (möglicherweise Code-Adresse, wo sie auftrat).

Jedes der Makros FE_DIVBYZERO, FE_INEXACT, FE_INVALID, FE_OVERFLOW, FE_UNDERFLOW ist definiert, wenn die Implementierung die Handhabung der entsprechenden Ausnahme erlaubt und falls dies so ist, definiert es die entsprechenden Bit(s), so dass die Ausnahmebehandlungsfunktionen aufgerufen werden können, beispielsweise mit dem Ganzzahlargument FE_OVERFLOW|FE_UNDERFLOW. Andere Ausnahmen könnten auch unterstützt werden. Das Makro FE_ALL_EXCEPT ist entsprechend das bitweise ODER aller unterstützten Ausnahmen.

Die Funktion feclearexcept() setzt die unterstützten Ausnahmen, die durch die Bits in ihrem Argument dargestellt werden, zurück.

Die Funktion fegetexceptflag() speichert eine Darstellung des Zustands der Ausnahmeschalter, die durch das Argument Ausnahmen in dem undurchsichtigen Objekt *Schalterz dargestellt werden.

Die Funktion feraiseexcept() löst die unterstützten Ausnahmen aus, die durch die Bits in Ausnahmen dargestellt werden.

Die Funktion fesetexceptflag() setzt den kompletten Status für die Ausnahmen, die durch Ausnahmen dargestellt werden, auf den Wert von *Schalterz. Dieser Wert muss durch einen früheren Aufruf von fegetexceptflag() erlangt worden sein, wobei dessen letztes Argument alle Bits aus Ausnahmen enthalten muss.

Die Funktion fetestexcept() liefert ein Wort zurück, dessen Bits gesetzt sind, die im Argument Ausnahmen gesetzt sind und für die eine entsprechende Ausnahme derzeit gesetzt ist.

  Rundungsmodus
Der Rundungsmodus bestimmt, wie das Ergebnis von Fließkommazahloperationen behandelt wird, wenn das Ergebnis nicht exakt durch die Mantisse dargestellt werden kann. Verschiedene Rundungsmodi können bereitgestellt werden: runden auf die nächste (die Vorgabe), aufrunden (Richtung positiv unendlich), abrunden (Richtung negativ unendlich) und runden Richtung Null.

Jedes der Makros FE_TONEAREST, FE_UPWARD, FE_DOWNWARD und FE_TOWARDZERO ist definiert, wenn die Implementierung das Ermitteln und Setzen der entsprechenden Rundungsrichtung unterstützt.

Die Funktion fegetround() liefert das Makro zurück, das dem aktuellen Rundungsmodus entspricht.

Die Funktion fesetround() setzt den Rundungsmodus, wie er durch ihr Argument angegeben wurde und liefert Null zurück, wenn sie erfolgreich ist.

C99 und POSIX.1-2008 spezifizieren einen in <float.h> definierten Kennzeichner FLT_ROUNDS, der das implementierungsabhängige Rundungsverhalten für Fließkomma-Addition anzeigt. Dieser Kennzeichner hat einen der folgenden Werte:

-1  Der Rundungsmodus ist nicht bestimmbar.

0   Runden in Richtung 0.

1   Runden in Richtung der nächsten Zahl.

2   Runden in Richtung positiv unendlich.

3   Runden in Richtung negativ unendlich.

Andere Werte stellen maschinenabhängige, nicht standardisierte Rundungsmodi dar.

Der Wert von FLT_ROUNDS sollte den aktuellen Rundungsmodus wiedergeben, wie er von fesetround() gesetzt wurde (siehe aber auch FEHLER).

  Fließkommaumgebung
Die gesamte Fließkommaumgebung, einschließlich Steuermodi und Statusschalter kann als undurchsichtiges Objekt vom Typ fenv_t gehandhabt werden. Die Standardumgebung wird als FE_DFL_ENV (vom Typ const fenv_t *) bezeichnet. Dies ist die Umgebung, die beim Programmstart eingerichtet wird. ISO C definiert, dass das Runden auf die nächste Zahl erfolgt, alle Ausnahmen zurückgesetzt sind und ein unterbrechungsfreier Modus (Fortführen bei Ausnahmen) vorliegt.

Die Funktion fegetenv() speichert die aktuelle Fließkommazahlumgebung in dem Objekt *Umgz.

Die Funktion feholdexcept() macht das gleiche, setzt dann alle Ausnahmeschalter zurück und setzt den unterbrechungsfreien Modus (Fortführen bei Ausnahmen), falls verfügbar. Sie liefert Null zurück, wenn sie erfolgreich war.

Die Funktion fesetenv() stellt die Fließkommazahlenumgebung aus dem Objekt *Umgz wieder her. Dieses Objekt muss bekanntermaßen gültig, beispielsweise ein Ergebnis des Aufrufs fegetenv() oder feholdexcept(), oder FE_DFL_ENV sein. Dieser Aufruf löst keine Ausnahmen aus.

Die Funktion feupdateenv() installiert die Flißekommazahlumgebung, die durch das Objekt *Umgz dargestellt wird, allerdings werden ausgelöste Ausnahmen nicht zurückgesetzt. Nach dem Aufruf dieser Funktion werden die ausgelösten Ausnahmen ein bitweises ODER der zuvor festgelegten Ausnahmen mit denen in *Umgz sein. Wie vorher muss das Objekt bekanntermaßen gültig sein.

RÜCKGABEWERT
Diese Funktionen liefern im Erfolgsfall Null zurück und einen von Null verschiedenen Wert, wenn ein Fehler auftrat.

ATTRIBUTE
Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt verwandten Ausdrücke.
Schnittstelle | Attribut | Wert
feclearexcept(), fegetexceptflag(), feraiseexcept(), fesetexceptflag(), fetestexcept(), fegetround(), fesetround(), fegetenv(), feholdexcept(), fesetenv(), feupdateenv(), feenableexcept(), fedisableexcept(), fegetexcept() | Multithread-Fähigkeit | MT-Sicher

STANDARDS
C11, POSIX.1-2008, IEC 60559 (IEC 559:1989), ANSI/IEEE 854.

GESCHICHTE
C99, POSIX.1-2001. Glibc 2.1.

ANMERKUNGEN

  Anmerkungen zur Glibc
Falls möglich definiert die GNU C-Bibliothek ein Makro FE_NOMASK_ENV, das eine Umgebung darstellt, bei der jede ausgelöste Ausnahme zum Auftreten einer Abfangaktion führt. Sie können mittels #ifdef auf dieses Makro testen. Es ist nur definiert, wenn _GNU_SOURCE definiert ist. Der C99-Standard definiert keine Art, um einzelne Bits in der Fließkommamaske zu setzen, beispielsweise um bei bestimmten Schaltern abzufangen. Glibc unterstützt seit Version 2.2 die Funktionen feenableexcept() und fedisableexcept(), um individuelle Fliekommazahl-Abfangaktionen zu setzen und fegetexcept(), um den Zustand abzufragen.

#define _GNU_SOURCE         /* Siehe feature_test_macros(7) */
#include <fenv.h>

int feenableexcept(int Ausnahmen);
int fedisableexcept(int Ausnahmen);
int fegetexcept(void);

Die Funktionen feenableexcept() und fedisableexcept() aktivieren (deaktivieren) Abfangaktionen für jede der durch Ausnahmen dargestellten Ausnahmen und lieferen im Erfolgsfall die vorherige Menge der aktivierten Ausnahmen zuürck und -1 andernfalls. Die Funktion fegetexcept() liefert die Menge aller derzeit aktivierten Ausnahmen zurück.

FEHLER
C99 spezifiziert, dass der Wert von FLT_ROUNDS die Änderungen am aktuellen Rundungsmodus wiedergeben soll, wie sie durch fesetround() gesetzt wurden. Derzeit passiert dies nicht: FLT_ROUNDS hat immer den Wert 1.

SIEHE AUCH
math_error(7)

ÜBERSETZUNG
Die deutsche Übersetzung dieser Handbuchseite wurde von Helge Kreutzmann <debian@helgefjell.de> erstellt.

Diese Übersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 (https://www.gnu.org/licenses/gpl-3.0.html) oder neuer bezüglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen.

Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an die Mailingliste der Übersetzer: debian-l10n-german@lists.debian.org.