Provided by: manpages-fr-dev_3.27fr1.4-1_all bug

NOM

       matherr - Gestionnaire d'exception SVID de la bibliotheque mathematique

SYNOPSIS

       #define _SVID_SOURCE             /* See feature_test_macros(7) */
       #include <math.h>

       int matherr(struct exception *exc);

       extern _LIB_VERSION_TYPE _LIB_VERSION;

       Effectuez l'edition des liens avec l'option -lm.

DESCRIPTION

       La  specification  << System  V Interface Definition >> (SVID) specifie
       que differentes fonctions devraient appeler une fonction  matherr()  en
       cas  d'exception  mathematique. Cette fonction est appelee avant que la
       fonction mathematique ne rende la main ; apres le retour de  matherr(),
       le  systeme  retourne  dans  la  fonctions  mathematique qui renvoie le
       resultat a l'appelant.

       Le mecanisme matherr() est pris en charge par la  glibc,  mais  il  est
       desormais  obsolete : les nouvelles applications devraient utiliser les
       techniques decrites dans math_error(7) et fenv(3). Cette page documente
       le  mecanisme matherr() de la glibc comme aide pour maintenir et porter
       d'anciennes applications.

       Pour utiliser matherr(), le programmeur doit definir la macro  de  test
       de  fonctionnalite  _SVID_SOURCE  (avant  d'inclure  toute  en-tete) et
       definir la variable externe _LIB_VERSION a la valeur _SVID_.

       Le systeme fourni une version par defaut de matherr(). Cette version ne
       fait  rien  et renvoie zero (voir ci-dessous pour la signification). La
       fonction matherr() par defaut  peut  etre  remplacee  par  une  version
       specifique  au  programme,  qui  sera  appelee  quand  une exception se
       produit. La fonction est appelee avec un parametre,  un  pointeur  vers
       une structure exception, definie comme ceci :

           struct exception {
               int    type;      /* Type d'exception */
               char  *name;      /* Nom de la fonction ayant
                                    produit l'exception */
               double arg1;      /* 1er parametre de la fonction */
               double arg2;      /* 2e parametre 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 parametre de la
                   fonction etait en dehors du domaine dans lequel la fonction
                   est  definie).  La valeur de retour depend de la fonction ;
                   errno prend la valeur EDOM.

       SING        Une erreur de pole s'est produite (la fonction  resulte  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 depassement s'est produit. Dans la plupart des  cas,  la
                   valeur HUGE est renvoyee et errno prend la valeur ERANGE.

       UNDERFLOW   Un  soupassement  (<< underflow >>)  s'est produit. 0,0 est
                   renvoye et errno prend la valeur ERANGE.

       TLOSS       Manque complet de sens. 0,0 est renvoye et errno  prend  la
                   valeur ERANGE.

       PLOSS       Manque partiel de sens. La valeur n'est pas utilisee par la
                   glibc (et beaucoup d'autres systemes).

       Les champs arg1 et arg2 sont  les  parametres  fournis  a  la  fonction
       ((arg2  n'est  pas defini pour les fonctions qui ne prennent qu'un seul
       parametre).

       Le  champ  retval  specifie  la  valeur  de  retour  que  la   fonction
       mathematique va renvoyer a l'appelant. La fonction matherr() specifique
       au programme peut modifier ce champ pour changer la valeur de retour de
       la fonction mathematique.

       Si  la  fonction  matherr()  renvoie  zero, alors le systeme positionne
       errno comme decrit 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 systeme
       ne positionne pas errno et n'affiche pas de message d'erreur.

   Fonctions math'ematiques qui utilisent matherr()
       La table ci-dessous liste  les  fonctions  et  les  circonstances  pour
       lesquelles  matherr()  est  appelee.  La  colonne << Type >> indique la
       valeur donnee a exc->type lors  de  l'appel  a  matherr().  La  colonne
       << Resultat >>   est   la  valeur  du  resultat  par  defaut  donnee  a
       exc->retval.

       Les colonnes << Msg? >> et << errno >> decrivent  le  comportement  par
       defaut  si  matherr()  renvoie  zero. Si la colonne << Msg? >> contient
       << o >>, alors le systeme affiche un message  d'erreur  sur  la  sortie
       d'erreur.

       La table utilise les notations et abreviations suivantes :

              x        premier parametre de la fonction
              y        deuxieme parametre de la fonction
              fin      valeur finie du parametre
              neg      valeur negative du parametre
              ent      valeur entiere du parametre
              o/f      depassement (<< overflow >>) pour le resultat
              u/f      soupassement (<< underflow >>) pour le resultat
              |x|      valeur absolue de x
              X_TLOSS  constante definie dans <math.h>

       Fonction             Type        R'esultat       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**neg               DOMAIN      0.0             o     EDOM
       neg**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 a log(3). Le programme prend jusqu'a 3 parametres en  ligne  de
       commande.  Le  premier  parametre  est le nombre en virgule flottante a
       fournir a log(3). Si le  deuxieme  parametre,  optionnel,  est  fourni,
       _LIB_VERSION  est  configure  a  la  valeur  _SVID_  de telle sorte que
       matherr() soit appelee et l'entier fourni sur la ligne de commande  est
       utilise comme valeur de retour de matherr(). Si le troisieme parametre,
       optionnel, est fourni, il specifie  une  autre  valeur  de  retour  que
       matherr()  doit  positionner  comme  valeur  de  retour  de la fonction
       mathematique.

       L'execution suivante de  l'exemple  (dans  laquelle  log(3)  recoit  la
       valeur 0,0) n'utilise pas matherr() :

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

       Dans l'execution suivante, matherr() est appelee 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 ete affiche par la bibliotheque C.

       Dans  l'execution suivante, matherr() est appelee 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 bibliotheque C n'a pas affiche de message et errno  n'a
       pas ete positionnee.

       Dans  l'execution suivante, matherr() est appelee, modifie la valeur de
       retour de la fonction mathematique 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.27  du  projet  man-pages
       Linux.  Une description du projet et des instructions pour signaler des
       anomalies      peuvent      etre       trouvees       a       l'adresse
       <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION

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

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

       Veuillez  signaler  toute  erreur   de   traduction   en   ecrivant   a
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous pouvez toujours avoir acces a la version anglaise de  ce  document
       en utilisant la commande << man -L C <section> <page_de_man> >>.