Provided by: manpages-fr-dev_3.17.1-1_all bug

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.

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  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;      /* 2ème 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.17 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> ».