NOM
matherr - Gestionnaire d’exception SVID de la bibliothèque mathématique
SYNOPSIS
#define _SVID_SOURCE
#include <math.h>
int matherr(struct exception *exc);
extern _LIB_VERSION_TYPE _LIB_VERSION;
Effectuez l’édition des liens avec l’option -lm.
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 fonctions 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 et mettre la valeur _SVID_ dans la
variable externe _LIB_VERSION.
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 dans lequel la fonction
est définie). 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 sous-passement (« underflow ») s’est produit. 0,0 est
renvoyé et errno prend la valeur ERANGE.
TLOSS Manque complet de sens. 0,0 est renvoyé et errno prend la
valeur ERANGE.
PLOSS Manque partiel de sens. 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 sous-passement (« underflow ») pour le résultat
|x| valeur absolue de x
X_TLOSS constante définie dans <math.h>
Fonction Type Résultat Msg? errno
acos(|x|>1) DOMAIN HUGE o EDOM
asin(|x|>1) DOMAIN HUGE o EDOM
atan2(0,0) DOMAIN HUGE o EDOM
acosh(x<1) DOMAIN NAN o EDOM
atanh(|x|>1) DOMAIN NAN o EDOM
atanh(|x|==1) SING (x>0.0)? o EDOM
HUGE_VAL :
-HUGE_VAL
cosh(fin) o/f OVERFLOW HUGE n ERANGE
sinh(fin) o/f OVERFLOW (x>0.0) ? n ERANGE
HUGE : -HUGE
sqrt(x<0) DOMAIN 0.0 o EDOM
hypot(fin,fin) o/f OVERFLOW HUGE n ERANGE
exp(fin) o/f OVERFLOW HUGE n ERANGE
exp(fin) u/f UNDERFLOW 0.0 n ERANGE
exp2(fin) o/f OVERFLOW HUGE n ERANGE
exp2(fin) u/f UNDERFLOW 0.0 n ERANGE
exp10(fin) o/f OVERFLOW HUGE n ERANGE
exp10(fin) u/f UNDERFLOW 0.0 n ERANGE
j0(|x|>X_TLOSS) TLOSS 0.0 o ERANGE
j1(|x|>X_TLOSS) TLOSS 0.0 o ERANGE
jn(|x|>X_TLOSS) TLOSS 0.0 o ERANGE
y0(x>X_TLOSS) TLOSS 0.0 o ERANGE
y1(x>X_TLOSS) TLOSS 0.0 o ERANGE
yn(x>X_TLOSS) TLOSS 0.0 o ERANGE
y0(0) DOMAIN -HUGE o EDOM
y0(x<0) DOMAIN -HUGE o EDOM
y1(0) DOMAIN -HUGE o EDOM
y1(x<0) DOMAIN -HUGE o EDOM
yn(n,0) DOMAIN -HUGE o EDOM
yn(x<0) DOMAIN -HUGE o EDOM
lgamma(fin) o/f OVERFLOW HUGE n ERANGE
lgamma(-ent) or SING HUGE o EDOM
lgamma(0)
tgamma(fin) o/f OVERFLOW HUGE_VAL n ERANGE
tgamma(-ent) SING NAN o EDOM
tgamma(0) SING copysign( o ERANGE
HUGE_VAL,x)
log(0) SING -HUGE o EDOM
log(x<0) DOMAIN -HUGE o EDOM
log2(0) SING -HUGE n EDOM
log2(x<0) DOMAIN -HUGE n EDOM
log10(0) SING -HUGE o EDOM
log10(x<0) DOMAIN -HUGE o EDOM
pow(0.0,0.0) DOMAIN 0.0 o EDOM
pow(x,y) o/f OVERFLOW HUGE n ERANGE
pow(x,y) u/f UNDERFLOW 0.0 n ERANGE
pow(NaN,0.0) DOMAIN x n EDOM
0**nég DOMAIN 0.0 o EDOM
nég**non-ent DOMAIN 0.0 o EDOM
scalb() o/f OVERFLOW (x>0.0) ? n ERANGE
HUGE_VAL :
-HUGE_VAL
scalb() u/f UNDERFLOW copysign( n ERANGE
0.0,x)
fmod(x,0) DOMAIN x o EDOM
remainder(x,0) DOMAIN NAN o EDOM
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);
}
VOIR AUSSI
fenv(3), math_error(7), standards(7)
COLOPHON
Cette page fait partie de la publication 3.23 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
Cette page de manuel a été traduite par Alain Portal <aportal AT
univ-montp2 DOT fr> en 2008, et mise à disposition sur
http://manpagesfr.free.fr/.
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> 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> ».