FENV(3)

NAZWA
feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, fetestexcept, fegetenv, fegetround, feholdexcept, fesetround, fesetenv, feupdateenv - zaokrąglanie zmiennoprzecinkowe i obsługa wyjątków w C99

SKŁADNIA
#include <fenv.h>

void feclearexcept(int excepts);
void fegetexceptflag(fexcept_t *flagp, int excepts);
void feraiseexcept(int excepts);
void fesetexceptflag(const fexcept_t *flagp, int excepts);
int fetestexcept(int excepts);

int fegetround(void);
int fesetround(int rounding_mode);

void fegetenv(fenv_t *envp);
int feholdexcept(fenv_t *envp);
void fesetenv(const fenv_t *envp);
void feupdateenv(const fenv_t *envp);

OPIS
Tych jedenaście funkcji zdefiniowano w C99. Realizują one obsługę zmiennoprzecinkowego zaokrąglania i wyjątków (nadmiar, dzielenie przez zero, itp.).

  Wyjątki
Wyjątek DivideByZero (dzielenie przez zero) występuje gdy dokładnym wynikiem operacji na liczbach skończonych jest nieskończoność.

Wyjątek Overflow (nadmiar) występuje gdy wynik musi być przedstawiony jako liczba zmiennoprzecinkowa, ale ma on (dużo) większą wartość bezwzględną niż największa (skończona) liczba zmiennoprzecinkowa posiadająca przedstawienie.

Wyjątek Underflow (niedomiar) występuje gdy wynik musi być przedstawiony jako liczba zmiennoprzecinkowa, ale ma on mniejszą wartość bezwzględną niż najmniejsza dodatnia znormalizowana iczba zmiennoprzecinkowa (i nastąpiłaby duża utrata precyzji, gdyby przedstawić go jako liczbę nieznormalizowaną).

Wyjątek Inexact (niedokładny) występuje gdy wynik operacji zaokrąglenia nie jest równy wynikowi o nieskończonej precyzji. Może on towarzyszyć wystąpieniu Overflow lub Underflow.

Wyjątek Invalid (nieprawidłowy) występuje gdy operacja nie ma dobrze zdefiniowanego wyniku, jak dla 0/0, nieskończoność - nieskończoność lub sqrt(-1).

  Obsługa wyjątków
Wyjątki są reprezentowane na dwa sposoby: jako pojedyncze bity (wyjątek obecny/nieobecny), które to bity odpowiadają w pewien zależny od implementacji sposób pozycjom bitowym w liczbie całkowitej, i jako nieprzezroczysta struktura, która może zawierać więcej informacji o wyjątkach (zapewne adres kodu, gdzie wyjątek wystąpił).

Każde z makr FE_DIVBYZERO, FE_INEXACT, FE_INVALID, FE_OVERFLOW, FE_UNDERFLOW jest zdefiniowane, gdy implementacja wspiera obsługę odpowiedniego wyjątku, i wówczas definiuje ono odpowiedni(e) bit(y), umożliwiając wywoływanie funkcji obsługi wyjątków, np. podając argument całkowity FE_OVERFLOW|FE_UNDERFLOW. Dla innych wyjątków może nie być wsparcia. Makro FE_ALL_EXCEPT jest bitowym OR wszystkich bitów odpowiadającym wspieranym wyjątkom.

Funkcja feclearexcept zeruje wspierane wyjątki reprezentowane przez bity jej argumentu.

Funkcja fegetexceptflag umieszcza odwzorowanie stanu znaczników przypisanych wyjątkom reprezentowanym przez argument excepts w nieprzezroczystym obiekcie *flagp.

Funkcja feraiseexcept zgłasza wspierane wyjątki reprezentowane przez bity excepts.

Funkcja fesetexceptflag ustawia pełny stan o wartości *flagp dla wyjątków reprezentowanych przez excepts. Wartość ta musi być otrzymana jako wynik wcześniejszego wywołania fegetexceptflag z ostatnim argumentem zawierającym wszystkie bity excepts.

Funkcja fetestexcept zwraca słowo z ustawionymi tymi bitami, które są ustawione w argumencie excepts, i dla których jest aktualnie ustawiony odpowiedni wyjątek.

  Rounding
Każde z makr FE_DOWNWARD, FE_TONEAREST, FE_TOWARDZERO, FE_UPWARD jest zdefiniowane, gdy implementacja wspiera pobieranie i ustawianie odpowiedniego kierunku zaokrąglania.

Funkcja fegetround zwraca makro odpowiedające aktualnemu trybowi zaokrąglania.

Funkcja fesetround ustawia tryb zaokrąglania podany jako jej argument i zwraca zero gdy się powiedzie.

  Środowisko zmiennoprzecinkowe
Całe środowisko zmiennoprzecinkowe, włączając w to tryby sterowania i znaczniki stanu, może być obsługiwane jako jeden nieprzezroczysty obiekt typu fenv_t. Środowisko domyślne jest określone przez FE_DFL_ENV (typu const fenv_t *). Są to ustawienia środowiska przy uruchomieniu programu i są one zdefiniowane przez ISO C jako: zaokrąglanie do najbliższej, wszystkie wyjątki wyzerowane i tryb nieprzerywany (kontynuacja w przypadku wystąpienia wyjątku).

Funkcja fegetenv zachowuje aktualne środowisko zmiennoprzecinkowe w obiekcie *envp.

Funkcja feholdexcept robi to samo, a następnie zeruje wszystkie znaczniki wyjątków i ustawia tryb nieprzerywany (kontynuacja w przypadku wystąpienia wyjątku), o ile to możliwe. Zwraca zero, gdy się powiedzie.

Funkcja fesetenv odtwarza środowisko zmiennoprzecinkowe z obiektu *envp. Obiekt ten musi być znany jako poprawny, np. jako wynik wywołania fegetenv lub feholdexcept lub jako równy FE_DFL_ENV. To wywołanie nie zgłasza wyjątków.

Funkcja feupdateenv instaluje środowisko zmiennoprzecinkowe odwzorowane w obiekcie *envp, poza tym, że aktualnie zgłoszone wyjątki nie są zerowane. Po jej wywołaniu, zgłoszone wyjątki będą bitowym OR tych zgłoszonych wcześniej oraz zawartych w *envp. Jak poprzednio, obiekt *envp musi być znany jako poprawny.

SZCZEGÓŁY GNU
O ile to możliwe, biblioteka GNU C definiuje makro FE_NOMASK_ENV odwzorowujące środowisko, w którym każde zgłoszenie wyjątku powoduje wystąpienie pułapki. Można sprawdzać wartość tego makra za pomocą #ifdef. Jest ono zdefiniowane jedynie, gdy zdefiniowane jest _GNU_SOURCE. Standard C99 nie określa sposobu ustawiania poszczególnych bitów w masce zmiennoprzecinkowej, np. aby przechwytywać tylko wybrane znaczniki. glibc 2.2 będzie obsługiwać funkcje feenableexcept i fedisableexcept ustawiające wybrane znaczniki zmiennoprzecinkowe oraz fegetexcept odpytującą o stan.

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

Funkcje feenableexcept i fedisableexcept włączają (wyłączają) pułapkowanie poszczególnych wyjątków odwzorowanych w przez excepts i zwracają poprzednie ustawienie pułapkowania wyjątków, jeśli się powiodą, a -1 w pozostałych przypadkach. Funkcja fegetexcept zwraca aktualne ustawienie pułapkowania wyjątków.

ZGODNE Z
IEC 60559 (IEC 559:1989), ANSI/IEEE 854, ISO C99 (ISO/IEC 9899:1999).