Provided by: manpages-pl-dev_4.23.1-1_all 
NAZWA
feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, fetestexcept, fegetenv, fegetround,
feholdexcept, fesetround, fesetenv, feupdateenv, feenableexcept, fedisableexcept, fegetexcept -
zaokrąglanie zmiennoprzecinkowe i obsługa wyjątków
BIBLIOTEKA
Biblioteka matematyczna (libm, -lm)
SKŁADNIA
#include <fenv.h>
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);
OPIS
Tych jedenaście funkcji zdefiniowanych w C99 realizuje obsługę zmiennoprzecinkowego zaokrąglania i
wyjątków (nadmiar, dzielenie przez zero, itp.).
Wyjątki
Wyjątek divide-by-zero (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 mająca
przedstawienie.
Wyjątek underflow (niedomiar) występuje, gdy wynik musi być przedstawiony jako liczba zmiennoprzecinkowa,
ale ma mniejszą wartość bezwzględną niż najmniejsza dodatnia znormalizowana liczba 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, przykłady:
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 odpowiedni(e) bit(y),
umożliwiając wywoływanie funkcji obsługi wyjątków, na przykład 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 obecnie ustawiony odpowiedni wyjątek.
Tryb zaokrąglania
Tryb zaokrąglania określa w jaki sposób traktuje się wynik operacji zmiennoprzecinkowej, jeśli nie może
być on dokładnie reprezentowany w mantysie. Mogą być dostarczane różne tryby zaokrągleń: zaokrąglanie do
najbliższej liczby (domyślnie), zaokrąglanie w górę (w kierunku dodatniej nieskończoności), zaokrąglanie
w dół (w kierunku ujemnej nieskończoności) i zaokrąglanie w kierunku zera.
Każde z makr FE_TONEAREST, FE_UPWARD, FE_DOWNWARD oraz FE_TOWARDZERO jest zdefiniowane, gdy implementacja
wspiera pobieranie i ustawianie odpowiedniego kierunku zaokrąglania.
Funkcja fegetround() zwraca makro odpowiadające bieżącemu trybowi zaokrąglania.
Funkcja fesetround() ustawia tryb zaokrąglania podany jako jej argument i zwraca zero, gdy się powiedzie.
C99 i POSIX.1-2008 określają identyfikator FLT_ROUNDS definiowany w <float.h> wskazujący na zależny od
implementacji sposób zaokrąglania podczas dodawania zmiennoprzecinkowego. Identyfikator ten może
przyjmować jedną z poniższych wartości:
-1 Nie można określić trybu zaokrąglania.
0 Zaokrąglanie w kierunku 0.
1 Zaokrąglanie w kierunku najbliższej liczby.
2 Zaokrąglanie w kierunku dodatniej nieskończoności.
3 Zaokrąglanie w kierunku ujemnej nieskończoności.
Inne wartości oznaczają tryby zaokrąglania niestandardowe, zależne od architektury komputera.
Wartość FLT_ROUNDS powinna odzwierciedlać bieżący tryb zaokrąglania ustawiony przez fesetround() (patrz
także USTERKI).
Ś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 bieżące ś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, na przykład 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
obecnie 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.
WARTOŚĆ ZWRACANA
Funkcje te zwracają zero, gdy się powiodą, lub wartość niezerową, gdy wystąpi błąd.
ATRYBUTY
Informacje o pojęciach używanych w tym rozdziale można znaleźć w podręczniku attributes(7).
┌──────────────────────────────────────────────────────────────┬────────────────────────┬───────────────┐
│ Interfejs │ Atrybut │ Wartość │
├──────────────────────────────────────────────────────────────┼────────────────────────┼───────────────┤
│ feclearexcept(), fegetexceptflag(), feraiseexcept(), │ Bezpieczeństwo wątkowe │ MT-bezpieczne │
│ fesetexceptflag(), fetestexcept(), fegetround(), │ │ │
│ fesetround(), fegetenv(), feholdexcept(), fesetenv(), │ │ │
│ feupdateenv(), feenableexcept(), fedisableexcept(), │ │ │
│ fegetexcept() │ │ │
└──────────────────────────────────────────────────────────────┴────────────────────────┴───────────────┘
STANDARDY
C11, POSIX.1-2008, IEC 60559 (IEC 559:1989), ANSI/IEEE 854.
HISTORIA
C99, POSIX.1-2001. glibc 2.1.
UWAGI
Uwagi dla glibc
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, na przykład aby przechwytywać tylko wybrane
znaczniki. Od glibc 2.2, glibc obsługuje funkcje feenableexcept() i fedisableexcept() ustawiające wybrane
znaczniki zmiennoprzecinkowe oraz fegetexcept() odpytującą o stan.
#define _GNU_SOURCE /* Patrz feature_test_macros(7) */
#include <fenv.h>
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 bieżące ustawienie pułapkowania wyjątków.
USTERKI
C99 określa, że wartość FLT_ROUNDS powinna odzwierciedlać zmiany bieżącego trybu zaokrąglania ustawiane
przez fesetround(). Obecnie to nie działa: FLT_ROUNDS ma zawsze wartość 1.
ZOBACZ TAKŻE
math_error(7)
TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Andrzej Krzysztofowicz
<ankry@green.mf.pg.gda.pl>, Robert Luberda <robert@debian.org> i Michał Kułach <michal.kulach@gmail.com>
Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać
zapoznając się z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje się ŻADNEJ
ODPOWIEDZIALNOŚCI.
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej manpages-pl-
list@lists.sourceforge.net.
Linux man-pages 6.8 2 maja 2024 r. fenv(3)