Ubuntu Manpage: math_error - Détecter des erreurs des fonctions mathématiques

NOM

       math_error - Détecter des erreurs des fonctions mathématiques

SYNOPSIS

       #include <math.h>
       #include <errno.h>
       #include <fenv.h>

DESCRIPTION

Quand une erreur se produit, la plupart des fonctions de bibliothèques l'indiquent en renvoyant une
valeur spéciale (par exemple, -1 ou NULL). Parce qu'elles renvoient en général un nombre en virgule
flottante, les fonctions mathématiques déclarées dans <math.h> indiquent une erreur en utilisant d'autres
mécanismes. Il y a deux mécanismes d'indication d'erreur : l'ancien configure errno ; le nouveau utilise
le mécanisme d'exception de virgule flottante (l'utilisation de feclearexcept(3) et fetestexcept(3),
comme explicité ci-dessous) décrit dans fenv(3).

Un programme portable qui doit vérifier les erreurs d'une fonction mathématique devrait mettre errno à
zéro et effectuer l'appel suivant :

feclearexcept(FE_ALL_EXCEPT);

avant d'appeler une fonction mathématique.

Après le retour d'une fonction mathématique, si errno est non nul ou si l'appel suivant (consultez
fenv(3)) ne renvoie pas zéro :

fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW |
FE_UNDERFLOW);

alors une erreur s'est produite dans la fonction mathématique.

Les conditions d'erreur qui peuvent se produire pour les fonctions mathématiques sont décrites
ci-dessous.

Erreur de domaine
Une erreur de domaine se produit quand une fonction mathématique reçoit un paramètre dont la valeur se
trouve en dehors du domaine de définition de la fonction (par exemple, fournir un paramètre négatif à
log(3)). Lorsqu'une erreur de domaine se produit, les fonctions renvoient généralement un NaN (mais
certaines fonctions renvoient une valeur différente dans ce cas) ; errno prend la valeur EDOM et une
exception de virgule flottante « incorrecte » (FE_INVALID) est levée.

Erreur de pôle
Une erreur de pôle se produit quand le résultat mathématique d'une fonction est un infini (par exemple,
le logarithme de 0 est l'infini négatif). Quand une erreur de pôle se produit, la fonction renvoie la
valeur (signée) HUGE_VAL, HUGE_VALF ou HUGE_VALL suivant que la valeur de retour de la fonction est un
double, un float ou un long double. Le signe du résultat est celui du résultat correct de la fonction
mathématique. errno prend la valeur ERANGE et une exception de virgule flottante de division par zéro
(FE_DIVBYZERO) est levée.

Erreur d'intervalle
Une erreur d'intervalle se produit quand le module du résultat de la fonction ne peut pas être représenté
par le type utilisé pour le résultat de la fonction. La valeur de retour de la fonction dépend suivant
qu'il s'agit d'un dépassement (« overflow ») ou d'un soupassement (« underflow »).

Un dépassement se produit pour le résultat flottant si le résultat est fini, mais trop grand pour être
représenté dans le type du résultat. Quand un dépassement se produit, la fonction renvoie la valeur
HUGE_VAL, HUGE_VALF ou HUGE_VALL, suivant que le type de retour de la fonction est un double, un float ou
un long double. errno prend la valeur ERANGE et une exception de virgule flottante de dépassement
(FE_OVERFLOW) est levée.

Un soupassement se produit pour le résultat flottant si le résultat est trop petit pour être représenté
dans le type du résultat. Quand un soupassement se produit, une fonction mathématique renvoie
généralement 0,0 (C99 indique qu'une fonction doit renvoyer « une valeur propre à l'implémentation dont
le module n'est pas plus grand que la plus petite valeur normalisée positive du type donné »). errno
prend la valeur ERANGE et une exception de virgule flottante de « soupassement » (FE_UNDERFLOW) peut être
levée.

Certaines fonctions produisent une erreur d'intervalle si la valeur du paramètre fourni, ou le résultat
exact de la fonction, est dénormalisé (« subnormal »). Une valeur dénormalisée est une valeur qui n'est
pas nulle, mais dont le module est si petit qu'il ne peut être représenté dans la forme normalisée
(c'est-à-dire avec un 1 dans le bit de poids fort de la mantisse). La représentation d'un nombre
dénormalisé contiendra un ou plusieurs zéros en tête de la mantisse.

NOTES

       L'identifiant  math_errhandling  spécifié  par  C99 et POSIX.1 n'est pas pris en charge par la glibc. Cet
       identifiant est supposé indiquer lequel des deux mécanismes d'indication d'erreur est utilisé  (errno  ou
       des exceptions récupérables avec fettestexcept(3)). Les normes imposent qu'au moins l'un d'entre eux soit
       utilisé,  mais  autorisent  à  ce  que  les  deux  soient  disponibles. La situation actuelle de la glibc
       (version 2.8) n'est pas très propre. La plupart des fonctions (mais pas toutes) lèvent des exceptions  en
       cas  d'erreur.  Certaines  positionnent  également  errno. Quelques fonctions positionnent errno, mais ne
       lèvent pas d'exception. Très peu ne font ni l'un ni l'autre. Consultez les différentes  pages  de  manuel
       pour avoir les détails.

       Pour éviter la complexité d'avoir à utiliser errno et fetestexcept(3) pour la détection d'erreurs, il est
       souvent  recommandé de vérifier la validité des paramètres avant les appels. Par exemple, le code suivant
       s'assure que le paramètre de log(3) n'est ni un NaN, ni zéro (une erreur de pôle)  ou  inférieur  à  zéro
       (une erreur de domaine) :

           double x, r;

           if (isnan(x) || islessequal(x, 0)) {
               /* Traite un NaN / erreur de pôle / erreur de domaine */
           }

           r = log(x);

       La  discussion  sur  cette  page  ne  s'applique  pas  aux  fonctions mathématiques à variables complexes
       (c'est-à-dire celles déclarées par <complex.h>), pour lesquelles C99 et POSIX.1 n'exigent pas en  général
       de renvoyer d'erreurs.

       L'option  de  gcc(1)  -fno-math-errno  permet  d'utiliser  des  implémentations  de  certaines  fonctions
       mathématiques plus rapides que les implémentations standard, mais qui ne positionnent pas errno (l'option
       -ffast-math de gcc(1) active  également  -fno-math-errno).  Une  erreur  peut  toujours  être  testée  en
       utilisant fetestexcept(3).

VOIR AUSSI

       gcc(1), errno(3), fenv(3), fpclassify(3), INFINITY(3), isgreater(3), matherr(3), nan(3)

       info libc

TRADUCTION

       La   traduction   française   de   cette   page   de   manuel   a   été   créée   par  Christophe  Blaess
       <https://www.blaess.fr/christophe/>,   Stéphan   Rafin   <stephan.rafin@laposte.net>,   Thierry   Vignaud
       <tvignaud@mandriva.com>,  François  Micaux,  Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard
       <fevrier@tigreraye.org>,   Jean-Luc   Coulon   (f5ibh)   <jean-luc.coulon@wanadoo.fr>,   Julien   Cristau
       <jcristau@debian.org>,      Thomas      Huriaux      <thomas.huriaux@gmail.com>,     Nicolas     François
       <nicolas.francois@centraliens.net>,    Florentin    Duneau    <fduneau@gmail.com>,     Simon     Paillard
       <simon.paillard@resel.enst-bretagne.fr>,     Denis    Barbier    <barbier@debian.org>,    David    Prévot
       <david@tilapin.org>,  Cédric  Boutillier  <cedric.boutillier@gmail.com>  et  Jean-Pierre  Giraud   <jean-
       pierregiraud@neuf.fr>

       Cette  traduction  est  une  documentation libre ; veuillez vous reporter à la GNU General Public License
       version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

       Si vous découvrez un bogue dans la traduction de cette page de manuel,  veuillez  envoyer  un  message  à
       debian-l10n-french@lists.debian.org.

Pages du manuel de Linux 6.9.1                     2 mai 2024                                      math_error(7)