.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl)
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" USA.
.\"
.\" Traduction 31/08/2000 par Christophe Blaess (ccb@club-internet.fr)
.\" LDP 1.31
.\" Mise  jour 04/06/2001 - LDP-man-pages-1.36
.TH FENV 3  "4 Juin 2001" "Linux" "Manuel du programmeur Linux"
.SH NOM
feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, fetestexcept, fegetenv, fegetround, feholdexcept, fesetround, fesetenv, feupdateenv - Gestion des exceptions C99 pour les arrondis et les erreurs en virgule flottante.
.SH SYNOPSIS
.nf
.B #include <fenv.h>
.sp
.BI "void feclearexcept(int " excepts );
.br
.BI "void fegetexceptflag(fexcept_t *" flagp ", int " excepts );
.br
.BI "void feraiseexcept(int " excepts );
.br
.BI "void fesetexceptflag(const fexcept_t *" flagp ", int " excepts );
.br
.BI "int fetestexcept(int " excepts );
.sp
.B "int fegetround(void);"
.br
.BI "int fesetround(int " rounding_mode );
.sp
.BI "void fegetenv(fenv_t *" envp );
.br
.BI "int feholdexcept(fenv_t *" envp );
.br
.BI "void fesetenv(const fenv_t *" envp );
.br
.BI "void feupdateenv(const fenv_t *" envp );
.fi
.SH DESCRIPTION
Ces onze fonctions ont t dfinies dans le C99, et permettent de paramtrer
les arrondis et les gestions d'erreurs (dbordement, division par zro, etc.) en virgule flottante.
.SS Exceptions
L'exception DivideByZero se produit quand une opration sur des nombres finis
donne un infini comme rponse exacte.
.LP
L'exception Overflow se produit quand un rsultat doit tre reprsent par un
nombre en virgule flottante, mais que sa valeur absolue est trop grande
pour tre reprsente par un nombre fini.
.LP
L'exception Underflow se produit quand un rsultat doit tre reprsent par un
nombre en virgule flottante, mais que sa valeur absolue est trop petite pour
tre reprsente.
.LP
L'exception Inexact se produit quand le rsultat arrondi d'une opration
n'est pas gal au rsultat en prcision infinie. Elle peut se dclencher
quand les exceptions Overflown ou Underflow se produisent.
.LP
L'exception Invalid se produit quand il n'y a pas de rsultat bien dfini
pour une opration, comme 0/0 ou infini-infi ou sqrt(-1).
.SS "Gestion des exceptions"
Les exceptions sont reprsentes de deux manires : en tant qu'un unique bit
(exception prsente ou absente) correspondant de manire dpendant de
l'implmentation avec une position au sein d'un entier, et aussi en tant que
structure opaque pouvant vhiculer plus d'information
concernant l'exception (ventuellement l'adresse du code dclenchant l'erreur).
.LP
Chacune des macros
.BR FE_DIVBYZERO ,
.BR FE_INEXACT ,
.BR FE_INVALID ,
.BR FE_OVERFLOW ,
.BR FE_UNDERFLOW
est dfinie lorsque l'implmentation supporte la gestion
de l'exception correspondante. Les bits sont alors dfinis,
ainsi on peut appeler par exemple les fonctions de gestion
des exceptions avec un argument entier
.BR FE_OVERFLOW | FE_UNDERFLOW .
D'autres exceptions peuvent tre supportes. La macro
.B FE_ALL_EXCEPT
est un masque regroupant par OU binaire tous les bits des exceptions supportes.
.PP
La fonction
.B feclearexcept
efface les exceptions supportes reprsentes par les bits prsents
dans son argument.
.LP
La fonction
.B fegetexceptflag
stocke une reprsentation de l'tat des exceptions contenues dans 
son argument
.I excepts
dans l'objet opaque
.RI * flagp .
.LP
La fonction
.B feraiseexcept
dclenche les exceptions supportes reprsentes par les bits de l'argument
.IR excepts .
.LP
La fonction
.B fesetexceptflag
fixe l'tat des exceptions reprsentes par l'argument
.I excepts
en employant la valeur
.RI * flagp .
Cette dernire doit tre le rsultat d'un appel pralable 
.B fegetexceptflag
avec un dernier argument contenant au moins tous les bits prsents dans
.IR excepts .
.LP
La fonction
.B fetestexcept
renvoie un mot dont les bits galement prsents dans
l'argument
.I excepts
seront positionns si l'exception correspondante est prsente.
.SS Arrondis
Chacune des macros
.BR FE_DOWNWARD ,
.BR FE_TONEAREST ,
.BR FE_TOWARDZERO ,
.BR FE_UPWARD
est dfinie lorsque l'implmentation supporte l'usage 
de la direction d'arrondi correspondante.
.LP
La fonction
.B fegetround
renvoie la macro correspondant au mode d'arrondi
en cours.
.LP
La fonction
.B fesetround
fixe le mode d'arrondi tel qu'il est spcifi par son argument
et renvoie zro lorsqu'elle russit.
.SS "Environnement en virgule flottante."
L'environnement de travail en virgule flottante, y compris
les modes de contrle et les tats peuvent tre manipuls
sous forme d'un objet opaque de type
.IR fenv_t .
L'environnement par dfaut, est reprsent par
.B FE_DFL_ENV
(de type
.IR "const fenv_t *" ).
Il s'agit de la configuration de l'environnement au dmarrage du programme
et elle est dfinie par ISO C comme ayant un arrondi au plus proche, toutes
les exceptions effaces et un mode non-stop (continuer sur exception).
.LP
La fonction
.B fegetenv
sauve l'environnement de travail en virgule flottante en cours dans
l'objet 
.RI * envp .
.LP
La fonction
.B feholdexcept
effectue la mme chose, puis efface tous les drapeaux d'exceptions,
et bascule si possible sur un mode non-stop (continuer en prsence d'exceptions).
Elle renvoie zro si elle russit.
.LP
La fonction
.B fesetenv
recharge l'environnement de travail en virgule flottante 
partir de l'objet 
.RI * envp .
Cette objet doit tre valide, c'est  dire tre le rsultat de
.BR fegetenv ,
de
.B feholdexcept
ou gal 
.BR FE_DFL_ENV .
Cet appel ne dclenche pas les exceptions.
.LP
La fonction
.B feupdateenv
installe l'environnement en virgule flottante reprsent par l'objet
.RI * envp ,
sauf que les exceptions dj dclenches ne sont pas effaces.
Aprs l'appel de cette fonction, les exception dclenches seront un OU
binaire entre l'ensemble prcdent, et celui contenu dans
.RI * envp .
Comme prcdemment, l'objet point par
.I envp
doit tre valide.
 
.SH "DTAILS GNU"
Si possible, la bibliothque Gnu LibC dfinit une macro
.B FE_NOMASK_ENV
qui reprsente l'environnement quand toutes les exceptions dclenchent un
appel. On peut tester la prsence de cette macro en utilisant
.BR #ifdef .
Elle n'est dfinie que si la constante symbolique
.B _GNU_SOURCE
est dfinie.
Le standard C99 ne dfinit pas de manire de fixer des bits individuels dans
le masque, par exemple pour intercepter des exceptions particulires.
La GLibC 2.2 supportera
.I feenableexcept
et
.I fedisableexcept
pour fixer individuellement des interceptions, et
.I fegetexcept
pour demander l'tat.
.sp
.nf
.BI "int feenableexcept (int " excepts );
.br
.BI "int fedisableexcept (int " excepts );
.br
.BI "int fegetexcept (void);"
.br
.fi
.LP
Les fonctions
.B feenableexcept
et
.B fedisableexcept
activent (dsactivent) l'interception pour chaque exception reprsente par
.I excepts
et renvoient l'ensemble prcdent des exceptions actives lorsqu'elle
russissent, et \-1 sinon.
La fonction
.B fegetexcept
renvoie l'ensemble des exceptions actuellement actives.
.SH CONFORMIT
IEC 60559 (IEC 559:1989), ANSI/IEEE 854, ISO C99 (ISO/IEC 9899:1999).
.SH TRADUCTION
Christophe Blaess, 2000.