matherr(3) Gestionnaire d'exception SVID de la bibliothèque mathématique

SYNOPSIS

#define _SVID_SOURCE /* Consultez feature_test_macros(7) */
#include <math.h>
int matherr(struct exception *exc);
extern _LIB_VERSION_TYPE _LIB_VERSION;

Effectuez l'édition des liens avec l'option -lm.

DESCRIPTION

La spécification « System V Interface Definition » (SVID) spécifie que différentes fonctions devraient appeler une fonction matherr() en cas d'exception mathématique. Cette fonction est appelée avant que la fonction mathématique ne rende la main ; après le retour de matherr(), le système retourne dans la fonction mathématique qui renvoie le résultat à l'appelant.

Le mécanisme matherr() est pris en charge par la glibc, mais il est désormais obsolète : les nouvelles applications devraient utiliser les techniques décrites dans math_error(7) et fenv(3). Cette page documente le mécanisme matherr() de la glibc comme aide pour maintenir et porter d'anciennes applications.

Pour utiliser matherr(), le programmeur doit définir la macro de test de fonctionnalité _SVID_SOURCE (avant d'inclure tout en-tête) et définir la variable externe _LIB_VERSION à la valeur _SVID_.

Le système fourni une version par défaut de matherr(). Cette version ne fait rien et renvoie zéro (voir ci-dessous pour la signification). La fonction matherr() par défaut peut être remplacée par une version spécifique au programme, qui sera appelée quand une exception se produit. La fonction est appelée avec un paramètre, un pointeur vers une structure exception, définie comme ceci :

struct exception {
    int    type;      /* Type d'exception */
    char  *name;      /* Nom de la fonction ayant
                         produit l'exception */
    double arg1;      /* 1er paramètre de la fonction */
    double arg2;      /* 2e paramètre de la fonction */
    double retval;    /* Valeur de retour de la fonction */
}

Le champ type peut prendre une des valeurs suivantes :

DOMAIN
Une erreur de domaine s'est produite (un paramètre de la fonction était en dehors du domaine de définition de la fonction). La valeur de retour dépend de la fonction ; errno prend la valeur EDOM.
SING
Une erreur de pôle s'est produite (la fonction résulte en un infini). La valeur de retour dans la plupart des cas est HUGE (le plus grand nombre en virgule flottante), avec le bon signe. Dans la plupart des cas, errno prend la valeur EDOM.
OVERFLOW
Un dépassement s'est produit. Dans la plupart des cas, la valeur HUGE est renvoyée et errno prend la valeur ERANGE.
UNDERFLOW
Un soupassement (« underflow ») s'est produit. 0,0 est renvoyé et errno prend la valeur ERANGE.
TLOSS
Perte complète de chiffres significatifs. 0,0 est renvoyé et errno prend la valeur ERANGE.
PLOSS
Perte partielle de chiffres significatifs. La valeur n'est pas utilisée par la glibc (et beaucoup d'autres systèmes).

Les champs arg1 et arg2 sont les paramètres fournis à la fonction (arg2 n'est pas défini pour les fonctions qui ne prennent qu'un seul paramètre).

Le champ retval spécifie la valeur de retour que la fonction mathématique va renvoyer à l'appelant. La fonction matherr() spécifique au programme peut modifier ce champ pour changer la valeur de retour de la fonction mathématique.

Si la fonction matherr() renvoie zéro, alors le système positionne errno comme décrit ci-dessus et peut afficher un message d'erreur sur la sortie d'erreur (voir ci-dessous).

Si la fonction matherr() renvoie une valeur non nulle, alors le système ne positionne pas errno et n'affiche pas de message d'erreur.

Fonctions mathématiques qui utilisent matherr()

La table ci-dessous liste les fonctions et les circonstances pour lesquelles matherr() est appelée. La colonne « Type » indique la valeur donnée à exc->type lors de l'appel à matherr(). La colonne « Résultat » est la valeur du résultat par défaut donnée à exc->retval.

Les colonnes « Msg? » et « errno » décrivent le comportement par défaut si matherr() renvoie zéro. Si la colonne « Msg? » contient « o », alors le système affiche un message d'erreur sur la sortie d'erreur.

La table utilise les notations et abréviations suivantes :

x        premier paramètre de la fonction
y        deuxième paramètre de la fonction
fin      valeur finie du paramètre
nég      valeur négative du paramètre
ent      valeur entière du paramètre
o/f      dépassement (« overflow ») pour le résultat
u/f      soupassement (« underflow ») pour le résultat
|x|      valeur absolue de x
X_TLOSS  constante définie dans <math.h>
FonctionTypeRésultatMsg?errno
acos(|x|>1)DOMAINHUGEoEDOM
asin(|x|>1)DOMAINHUGEoEDOM
atan2(0,0)DOMAINHUGEoEDOM
acosh(x<1)DOMAINNANoEDOM
atanh(|x|>1)DOMAINNANoEDOM
atanh(|x|==1)SING(x>0.0)?oEDOM
  HUGE_VAL :
  -HUGE_VAL
cosh(fin) o/fOVERFLOWHUGEnERANGE
sinh(fin) o/fOVERFLOW(x>0.0) ?nERANGE
  HUGE : -HUGE
sqrt(x<0)DOMAIN0.0oEDOM
hypot(fin,fin) o/fOVERFLOWHUGEnERANGE
exp(fin) o/fOVERFLOWHUGEnERANGE
exp(fin) u/fUNDERFLOW0.0nERANGE
exp2(fin) o/fOVERFLOWHUGEnERANGE
exp2(fin) u/fUNDERFLOW0.0nERANGE
exp10(fin) o/fOVERFLOWHUGEnERANGE
exp10(fin) u/fUNDERFLOW0.0nERANGE
j0(|x|>X_TLOSS)TLOSS0.0oERANGE
j1(|x|>X_TLOSS)TLOSS0.0oERANGE
jn(|x|>X_TLOSS)TLOSS0.0oERANGE
y0(x>X_TLOSS)TLOSS0.0oERANGE
y1(x>X_TLOSS)TLOSS0.0oERANGE
yn(x>X_TLOSS)TLOSS0.0oERANGE
y0(0)DOMAIN-HUGEoEDOM
y0(x<0)DOMAIN-HUGEoEDOM
y1(0)DOMAIN-HUGEoEDOM
y1(x<0)DOMAIN-HUGEoEDOM
yn(n,0)DOMAIN-HUGEoEDOM
yn(x<0)DOMAIN-HUGEoEDOM
lgamma(fin) o/fOVERFLOWHUGEnERANGE
lgamma(-ent) orSINGHUGEoEDOM
  lgamma(0)
tgamma(fin) o/fOVERFLOWHUGE_VALnERANGE
tgamma(-ent)SINGNANoEDOM
tgamma(0)SINGcopysign(oERANGE
  HUGE_VAL,x)
log(0)SING-HUGEoEDOM
log(x<0)DOMAIN-HUGEoEDOM
log2(0)SING-HUGEnEDOM
log2(x<0)DOMAIN-HUGEnEDOM
log10(0)SING-HUGEoEDOM
log10(x<0)DOMAIN-HUGEoEDOM
pow(0.0,0.0)DOMAIN0.0oEDOM
pow(x,y) o/fOVERFLOWHUGEnERANGE
pow(x,y) u/fUNDERFLOW0.0nERANGE
pow(NaN,0.0)DOMAINxnEDOM
0**négDOMAIN0.0oEDOM
nég**non-entDOMAIN0.0oEDOM
scalb() o/fOVERFLOW(x>0.0) ?nERANGE
  HUGE_VAL :
  -HUGE_VAL
scalb() u/fUNDERFLOWcopysign(nERANGE
    0.0,x)
fmod(x,0)DOMAINxoEDOM
remainder(x,0)DOMAINNANoEDOM

EXEMPLE

Le programme d'exemple montre l'utilisation de matherr() lors de l'appel à log(3). Le programme prend jusqu'à 3 paramètres en ligne de commande. Le premier paramètre est le nombre en virgule flottante à fournir à log(3). Si le deuxième paramètre, optionnel, est fourni, _LIB_VERSION est configuré à la valeur _SVID_ de telle sorte que matherr() soit appelée et l'entier fourni sur la ligne de commande est utilisé comme valeur de retour de matherr(). Si le troisième paramètre, optionnel, est fourni, il spécifie une autre valeur de retour que matherr() doit positionner comme valeur de retour de la fonction mathématique.

L'exécution suivante de l'exemple (dans laquelle log(3) reçoit la valeur 0,0) n'utilise pas matherr() :

$ ./a.out 0.0
errno: Numerical result out of range
x=-inf

Dans l'exécution suivante, matherr() est appelée et renvoie 0 :

$ ./a.out 0.0 0
matherr SING exception in log() function
        args:   0.000000, 0.000000
        retval: -340282346638528859811704183484516925440.000000
log: SING error
errno: Numerical argument out of domain
x=-340282346638528859811704183484516925440.000000

Le message « log: SING error » a été affiché par la bibliothèque C.

Dans l'exécution suivante, matherr() est appelée et renvoie une valeur non nulle :

$ ./a.out 0.0 1
matherr SING exception in log() function
        args:   0.000000, 0.000000
        retval: -340282346638528859811704183484516925440.000000
x=-340282346638528859811704183484516925440.000000

Dans ce cas, la bibliothèque C n'a pas affiché de message et errno n'a pas été positionnée.

Dans l'exécution suivante, matherr() est appelée, modifie la valeur de retour de la fonction mathématique et renvoie une valeur non nulle :

$ ./a.out 0.0 1 12345.0
matherr SING exception in log() function
        args:   0.000000, 0.000000
        retval: -340282346638528859811704183484516925440.000000
x=12345.000000

Source du programme

#define _SVID_SOURCE
#include <errno.h>
#include <math.h>
#include <stdio.h>
#include <stdlib.h>
static int matherr_ret = 0;     /* Value that matherr()
                                   should return */
static int change_retval = 0;   /* Should matherr() change
                                   function's return value? */
static double new_retval;       /* New function return value */
int
matherr(struct exception *exc)
{
    fprintf(stderr, "matherr %s exception in %s() function\n",
           (exc->type == DOMAIN) ?    "DOMAIN" :
           (exc->type == OVERFLOW) ?  "OVERFLOW" :
           (exc->type == UNDERFLOW) ? "UNDERFLOW" :
           (exc->type == SING) ?      "SING" :
           (exc->type == TLOSS) ?     "TLOSS" :
           (exc->type == PLOSS) ?     "PLOSS" : "???",
            exc->name);
    fprintf(stderr, "        args:   %f, %f\n",
            exc->arg1, exc->arg2);
    fprintf(stderr, "        retval: %f\n", exc->retval);
    if (change_retval)
        exc->retval = new_retval;
    return matherr_ret;
}
int
main(int argc, char *argv[])
{
    double x;
    if (argc < 2) {
        fprintf(stderr, "Usage: %s <argval>"
                " [<matherr-ret> [<new-func-retval>]]\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    if (argc > 2) {
        _LIB_VERSION = _SVID_;
        matherr_ret = atoi(argv[2]);
    }
    if (argc > 3) {
        change_retval = 1;
        new_retval = atof(argv[3]);
    }
    x = log(atof(argv[1]));
    if (errno != 0)
        perror("errno");
    printf("x=%f\n", x);
    exit(EXIT_SUCCESS);
}

COLOPHON

Cette page fait partie de la publication 3.65 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies peuvent être trouvées à l'adresse http://www.kernel.org/doc/man-pages/.

TRADUCTION

Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a <http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet perkamon <http://perkamon.alioth.debian.org/>.

Alain Portal <http://manpagesfr.free.fr/> (2008).

Veuillez signaler toute erreur de traduction en écrivant à <[email protected]> ou par un rapport de bogue sur le paquet manpages-fr.

Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « man -L C <section> <page_de_man> ».