NOM

matherr — Gestionnaire d'exception SVID de la bibliothèque mathématique

BIBLIOTHÈQUE

Bibliothèque de math (libm, -lm)

SYNOPSIS

#include <math.h>

[[obsolète]] int matherr(struct exception *exc);

[[obsolète]] extern _LIB_VERSION_TYPE _LIB_VERSION;

DESCRIPTION

Note : Le mécanisme décrit dans cette page n'est plus pris en charge par la glibc. Avant la glibc 2.27, il a été marqué comme obsolète. Depuis la glibc 2.27, il a été complètement supprimé. 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.

La spécification « System V Interface Definition » (SVID) spécifie que différentes fonctions mathématiques 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.

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

Le système fournit 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éfini 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;      /* 2ème paramètre de la fonction */
    double retval;    /* Valeur renvoyée par 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 renvoyée dépend de la fonction ; errno prend la valeur EDOM.

SING

Une erreur de pôle s'est produite (le résultat de la fonction est un infini). La valeur renvoyée dans la plupart des cas est HUGE (le plus grand nombre en virgule flottante simple précision), 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 que la fonction mathématique va renvoyer à l'appelant. La fonction matherr() définie par le programmeur peut modifier ce champ pour changer la valeur renvoyée par 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 standard (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.

ATTRIBUTS

Pour une explication des termes utilisés dans cette section, consulter attributes(7).

EXEMPLES

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 renvoyée par matherr(). Si le troisième paramètre, optionnel, est fourni, il spécifie une autre valeur que matherr() doit positionner comme valeur renvoyée 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 renvoyée par 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

#define _SVID_SOURCE
#include <errno.h>
#include <math.h>
#include <stdio.h>
#include <stdlib.h>
static int matherr_ret = 0;     /* Valeur que matherr()
                                   devrait renvoyer */
static int change_retval = 0;   /* Voulez-vous que matherr() modifie la
                                   valeur renvoyée par la fonction ? */
static double new_retval;       /* Nouvelle valeur renvoyée par la fonction */
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);
}

VOIR AUSSI

fenv(3), math_error(7), standards(7)

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.