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.

A floating result underflows if the result is too small to be represented in the result
type. If an underflow occurs, a mathematical function typically returns 0.0 (C99 says a
function shall return "an implementation-defined value whose magnitude is no greater than
the smallest normalized positive number in the specified type"). errno may be set to
ERANGE, and an "underflow" (FE_UNDERFLOW) floating-point exception may be raised.

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

       The  math_errhandling  identifier  specified by C99 and POSIX.1 is not supported by glibc.
       This identifier is supposed to indicate which of  the  two  error-notification  mechanisms
       (errno, exceptions retrievable via fetestexcept(3))  is in use. The standards require that
       at least one be in use, but permit both to be available. The current (glibc 2.8) situation
       under  glibc  is messy. Most (but not all) functions raise exceptions on errors. Some also
       set errno. A few functions set errno, but don't raise an exception. A very  few  functions
       do neither. See the individual manual pages for details.

       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)) {
               /* Deal with NaN / pole error / domain error */
           }

           r = log(x);

       The discussion on this page does not apply to the complex  mathematical  functions  (i.e.,
       those  declared by <complex.h>), which in general are not required to return errors by C99
       and POSIX.1.

       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>  et  Cédric  Boutillier
       <cedric.boutillier@gmail.com>

       Cette  traduction  est  une  documentation libre ; veuillez vous reporter à la GNU General
       Public  License  version 3  ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩   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⟩.