1.\"	$OpenBSD: feclearexcept.3,v 1.4 2013/06/05 03:40:26 tedu Exp $
2.\"
3.\" Copyright (c) 2011 Martynas Venckus <martynas@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: June 5 2013 $
18.Dt FECLEAREXCEPT 3
19.Os
20.Sh NAME
21.Nm feclearexcept ,
22.Nm fegetexceptflag ,
23.Nm feraiseexcept ,
24.Nm fesetexceptflag ,
25.Nm fetestexcept
26.Nd access floating-point status flags
27.Sh SYNOPSIS
28.In fenv.h
29.Ft int
30.Fn feclearexcept "int excepts"
31.Ft int
32.Fn fegetexceptflag "fexcept_t *flagp" "int excepts"
33.Ft int
34.Fn feraiseexcept "int excepts"
35.Ft int
36.Fn fesetexceptflag "const fexcept_t *flagp" "int excepts"
37.Ft int
38.Fn fetestexcept "int excepts"
39.Sh DESCRIPTION
40These functions provide access to the floating-point status flags.
41The
42.Fa excepts
43input argument is a bitmask specifying an exception type and
44containing any of the values listed below.
45.Bl -tag -width ".Dv FE_DIVBYZERO"
46.It Dv FE_DIVBYZERO
47A divide-by-zero exception occurs when the program attempts to
48divide a finite non-zero number by zero.
49.It Dv FE_INEXACT
50An inexact exception is raised whenever there is a loss of precision
51due to rounding.
52.It Dv FE_INVALID
53Invalid operation exceptions occur when a program attempts to
54perform calculations for which there is no reasonable representable
55answer.
56.Pp
57For instance, subtraction of infinities, division of zero by zero,
58ordered comparison involving \*(Nas, and taking the square root of a
59negative number are all invalid operations.
60.It Dv FE_OVERFLOW
61An overflow exception occurs when the magnitude of the result of a
62computation is too large to fit in the destination type.
63.It Dv FE_UNDERFLOW
64Underflow occurs when the result of a computation is too close to zero
65to be represented as a non-zero value in the destination type.
66.It Dv FE_DENORMAL
67Denormalization exception occurs when the result of a floating-point
68expression is a denormalized number.
69.Pp
70This is available only on the floating-point implementations of
71amd64 and i386 processors.
72.El
73.Pp
74Additionally, the macro
75.Dv FE_ALL_EXCEPT
76is simply the bitwise OR of all floating-point exception macros
77listed above.
78.Pp
79The
80.Fn feclearexcept
81function clears the floating-point exceptions represented by
82.Fa excepts .
83.Pp
84The
85.Fn fegetexceptflag
86function stores a representation of the states of the floating-point
87flags indicated by
88.Pa excepts
89in the object pointed to by
90.Pa flagp .
91.Pp
92The
93.Fn feraiseexcept
94function raises floating-point exceptions represented by
95.Pa excepts .
96.Pp
97The
98.Fn fesetexceptflag
99function sets the floating-point status flags indicated by
100.Pa excepts
101to the states stored in the object pointed to by
102.Pa flagp .
103The value of
104.Pa flagp
105shall have been set by a previous call to
106.Fn fegetexceptflag
107whose second argument represented at least those floating-point
108exceptions represented by
109.Pa excepts .
110This function does not raise floating-point exceptions, but only
111sets the state of the flags.
112.Pp
113The
114.Fn fetesteexcept
115function determines which of a specified subset of the floating-point
116exception flags are currently set.
117The
118.Pa excepts
119specifies the floating-point status flags to be queried.
120.Sh RETURN VALUES
121The
122.Fn feclearexcept ,
123.Fn fegetexceptflag ,
124.Fn feraiseexcept ,
125and
126.Fn fesetexceptflag
127functions return zero on success, and non-zero if an error occurred.
128The
129.Fn fetestexcept
130function returns a bitmask of a specified subset of the floating-point
131exception flags which are currently set.
132.Sh SEE ALSO
133.Xr feenableexcept 3 ,
134.Xr fegetenv 3 ,
135.Xr fegetround 3
136.Sh STANDARDS
137The
138.Fn feclearexcept ,
139.Fn fegetexceptflag ,
140.Fn feraiseexcept ,
141.Fn fesetexceptflag ,
142and
143.Fn fetestexcept
144functions conform to
145.St -isoC-99 .
146.Pp
147The return types for
148.Fn feclearexcept ,
149.Fn fegetexceptflag ,
150.Fn feraiseexcept ,
151and
152.Fn fesetexceptflag
153are
154.Vt int
155for alignment with
156.St -isoC-99
157Defect Report #202.
158.Sh HISTORY
159These functions first appeared in
160.Ox 5.0 .
161.Sh CAVEATS
162On some architectures,
163.Fn feraiseexcept
164additionally raises the
165.Dq inexact
166floating-point exception whenever it raises the
167.Dq overflow
168or
169.Dq underflow
170floating-point exception.
171