|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH fenv.h "0P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH PROLOG
|
|
Packit |
7cfc04 |
This manual page is part of the POSIX Programmer's Manual.
|
|
Packit |
7cfc04 |
The Linux implementation of this interface may differ (consult
|
|
Packit |
7cfc04 |
the corresponding Linux manual page for details of Linux behavior),
|
|
Packit |
7cfc04 |
or the interface may not be implemented on Linux.
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
fenv.h
|
|
Packit |
7cfc04 |
\(em floating-point environment
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
#include <fenv.h>
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The functionality described on this reference page is aligned with the
|
|
Packit |
7cfc04 |
ISO\ C standard. Any conflict between the requirements described here and the
|
|
Packit |
7cfc04 |
ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR <fenv.h>
|
|
Packit |
7cfc04 |
header shall define the following data types through
|
|
Packit |
7cfc04 |
.BR typedef :
|
|
Packit |
7cfc04 |
.IP "\fBfenv_t\fR" 10
|
|
Packit |
7cfc04 |
Represents the entire floating-point environment. The floating-point
|
|
Packit |
7cfc04 |
environment refers collectively to any floating-point status flags and
|
|
Packit |
7cfc04 |
control modes supported by the implementation.
|
|
Packit |
7cfc04 |
.IP "\fBfexcept_t\fR" 10
|
|
Packit |
7cfc04 |
Represents the floating-point status flags collectively, including any
|
|
Packit |
7cfc04 |
status the implementation associates with the flags. A floating-point
|
|
Packit |
7cfc04 |
status flag is a system variable whose value is set (but never cleared)
|
|
Packit |
7cfc04 |
when a floating-point exception is raised, which occurs as a side-effect
|
|
Packit |
7cfc04 |
of exceptional floating-point arithmetic to provide auxiliary
|
|
Packit |
7cfc04 |
information. A floating-point control mode is a system variable whose
|
|
Packit |
7cfc04 |
value may be set by the user to affect the subsequent behavior of
|
|
Packit |
7cfc04 |
floating-point arithmetic.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR <fenv.h>
|
|
Packit |
7cfc04 |
header shall define each of the following macros if and only if the
|
|
Packit |
7cfc04 |
implementation supports the floating-point exception by means of the
|
|
Packit |
7cfc04 |
floating-point functions
|
|
Packit |
7cfc04 |
\fIfeclearexcept\fR(),
|
|
Packit |
7cfc04 |
\fIfegetexceptflag\fR(),
|
|
Packit |
7cfc04 |
\fIferaiseexcept\fR(),
|
|
Packit |
7cfc04 |
\fIfesetexceptflag\fR(),
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
\fIfetestexcept\fR().
|
|
Packit |
7cfc04 |
The defined macros shall expand to integer constant expressions with
|
|
Packit |
7cfc04 |
values that are bitwise-distinct.
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS
|
|
Packit |
7cfc04 |
FE_DIVBYZERO
|
|
Packit |
7cfc04 |
FE_INEXACT
|
|
Packit |
7cfc04 |
FE_INVALID
|
|
Packit |
7cfc04 |
FE_OVERFLOW
|
|
Packit |
7cfc04 |
FE_UNDERFLOW
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the implementation supports the IEC 60559 Floating-Point option, all
|
|
Packit |
7cfc04 |
five macros shall be defined.
|
|
Packit |
7cfc04 |
Additional implementation-defined floating-point exceptions with
|
|
Packit |
7cfc04 |
macros beginning with FE_ and an uppercase letter may also be
|
|
Packit |
7cfc04 |
specified by the implementation.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR <fenv.h>
|
|
Packit |
7cfc04 |
header shall define the macro FE_ALL_EXCEPT as the bitwise-inclusive
|
|
Packit |
7cfc04 |
OR of all floating-point exception macros defined by the
|
|
Packit |
7cfc04 |
implementation, if any. If no such macros are defined, then the
|
|
Packit |
7cfc04 |
macro FE_ALL_EXCEPT shall be defined as zero.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR <fenv.h>
|
|
Packit |
7cfc04 |
header shall define each of the following macros if and only if the
|
|
Packit |
7cfc04 |
implementation supports getting and setting the represented rounding
|
|
Packit |
7cfc04 |
direction by means of the
|
|
Packit |
7cfc04 |
\fIfegetround\fR()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
\fIfesetround\fR()
|
|
Packit |
7cfc04 |
functions. The defined macros shall expand to integer constant
|
|
Packit |
7cfc04 |
expressions whose values are distinct non-negative values.
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS
|
|
Packit |
7cfc04 |
FE_DOWNWARD
|
|
Packit |
7cfc04 |
FE_TONEAREST
|
|
Packit |
7cfc04 |
FE_TOWARDZERO
|
|
Packit |
7cfc04 |
FE_UPWARD
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the implementation supports the IEC 60559 Floating-Point option, all
|
|
Packit |
7cfc04 |
four macros shall be defined.
|
|
Packit |
7cfc04 |
Additional implementation-defined rounding directions with macros
|
|
Packit |
7cfc04 |
beginning with FE_ and an uppercase letter may also be specified by the
|
|
Packit |
7cfc04 |
implementation.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR <fenv.h>
|
|
Packit |
7cfc04 |
header shall define the following macro, which represents the
|
|
Packit |
7cfc04 |
default floating-point environment (that is, the one installed at
|
|
Packit |
7cfc04 |
program startup) and has type pointer to const-qualified
|
|
Packit |
7cfc04 |
.BR fenv_t .
|
|
Packit |
7cfc04 |
It can be used as an argument to the functions within the
|
|
Packit |
7cfc04 |
.IR <fenv.h>
|
|
Packit |
7cfc04 |
header that manage the floating-point environment.
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS
|
|
Packit |
7cfc04 |
FE_DFL_ENV
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The following shall be declared as functions and may also be defined as
|
|
Packit |
7cfc04 |
macros. Function prototypes shall be provided.
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
int feclearexcept(int);
|
|
Packit |
7cfc04 |
int fegetenv(fenv_t *);
|
|
Packit |
7cfc04 |
int fegetexceptflag(fexcept_t *, int);
|
|
Packit |
7cfc04 |
int fegetround(void);
|
|
Packit |
7cfc04 |
int feholdexcept(fenv_t *);
|
|
Packit |
7cfc04 |
int feraiseexcept(int);
|
|
Packit |
7cfc04 |
int fesetenv(const fenv_t *);
|
|
Packit |
7cfc04 |
int fesetexceptflag(const fexcept_t *, int);
|
|
Packit |
7cfc04 |
int fesetround(int);
|
|
Packit |
7cfc04 |
int fetestexcept(int);
|
|
Packit |
7cfc04 |
int feupdateenv(const fenv_t *);
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The FENV_ACCESS pragma provides a means to inform the implementation
|
|
Packit |
7cfc04 |
when an application might access the floating-point environment to test
|
|
Packit |
7cfc04 |
floating-point status flags or run under non-default floating-point
|
|
Packit |
7cfc04 |
control modes. The pragma shall occur either outside external
|
|
Packit |
7cfc04 |
declarations or preceding all explicit declarations and statements
|
|
Packit |
7cfc04 |
inside a compound statement. When outside external declarations, the
|
|
Packit |
7cfc04 |
pragma takes effect from its occurrence until another FENV_ACCESS
|
|
Packit |
7cfc04 |
pragma is encountered, or until the end of the translation unit. When
|
|
Packit |
7cfc04 |
inside a compound statement, the pragma takes effect from its
|
|
Packit |
7cfc04 |
occurrence until another FENV_ACCESS pragma is encountered (including
|
|
Packit |
7cfc04 |
within a nested compound statement), or until the end of the compound
|
|
Packit |
7cfc04 |
statement; at the end of a compound statement the state for the pragma
|
|
Packit |
7cfc04 |
is restored to its condition just before the compound statement. If
|
|
Packit |
7cfc04 |
this pragma is used in any other context, the behavior is undefined. If
|
|
Packit |
7cfc04 |
part of an application tests floating-point status flags, sets
|
|
Packit |
7cfc04 |
floating-point control modes, or runs under non-default mode settings,
|
|
Packit |
7cfc04 |
but was translated with the state for the FENV_ACCESS pragma off, the
|
|
Packit |
7cfc04 |
behavior is undefined. The default state (on or off) for the pragma is
|
|
Packit |
7cfc04 |
implementation-defined. (When execution passes from a part of the
|
|
Packit |
7cfc04 |
application translated with FENV_ACCESS off to a part translated with
|
|
Packit |
7cfc04 |
FENV_ACCESS on, the state of the floating-point status flags is
|
|
Packit |
7cfc04 |
unspecified and the floating-point control modes have their default
|
|
Packit |
7cfc04 |
settings.)
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
This header is designed to support the floating-point exception status
|
|
Packit |
7cfc04 |
flags and directed-rounding control modes required by the IEC\ 60559:\|1989 standard, and
|
|
Packit |
7cfc04 |
other similar floating-point state information. Also it is designed to
|
|
Packit |
7cfc04 |
facilitate code portability among all systems.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Certain application programming conventions support the intended model
|
|
Packit |
7cfc04 |
of use for the floating-point environment:
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
A function call does not alter its caller's floating-point control
|
|
Packit |
7cfc04 |
modes, clear its caller's floating-point status flags, nor depend on
|
|
Packit |
7cfc04 |
the state of its caller's floating-point status flags unless the
|
|
Packit |
7cfc04 |
function is so documented.
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
A function call is assumed to require default floating-point control
|
|
Packit |
7cfc04 |
modes, unless its documentation promises otherwise.
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
A function call is assumed to have the potential for raising
|
|
Packit |
7cfc04 |
floating-point exceptions, unless its documentation promises otherwise.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
With these conventions, an application can safely assume default
|
|
Packit |
7cfc04 |
floating-point control modes (or be unaware of them). The
|
|
Packit |
7cfc04 |
responsibilities associated with accessing the floating-point
|
|
Packit |
7cfc04 |
environment fall on the application that does so explicitly.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Even though the rounding direction macros may expand to constants
|
|
Packit |
7cfc04 |
corresponding to the values of FLT_ROUNDS, they are not required to do
|
|
Packit |
7cfc04 |
so.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
For example:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
#include <fenv.h>
|
|
Packit |
7cfc04 |
void f(double x)
|
|
Packit |
7cfc04 |
{
|
|
Packit |
7cfc04 |
#pragma STDC FENV_ACCESS ON
|
|
Packit |
7cfc04 |
void g(double);
|
|
Packit |
7cfc04 |
void h(double);
|
|
Packit |
7cfc04 |
/* ... */
|
|
Packit |
7cfc04 |
g(x + 1);
|
|
Packit |
7cfc04 |
h(x + 1);
|
|
Packit |
7cfc04 |
/* ... */
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the function
|
|
Packit |
7cfc04 |
\fIg\fR()
|
|
Packit |
7cfc04 |
might depend on status flags set as a side-effect of the first
|
|
Packit |
7cfc04 |
.IR x +1,
|
|
Packit |
7cfc04 |
or if the second
|
|
Packit |
7cfc04 |
.IR x +1
|
|
Packit |
7cfc04 |
might depend on control modes set as a side-effect of the call to
|
|
Packit |
7cfc04 |
function
|
|
Packit |
7cfc04 |
\fIg\fR(),
|
|
Packit |
7cfc04 |
then the application shall contain an appropriately placed invocation
|
|
Packit |
7cfc04 |
as follows:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
#pragma STDC FENV_ACCESS ON
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.SH RATIONALE
|
|
Packit |
7cfc04 |
.SS "The fexcept_t Type"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.BR fexcept_t
|
|
Packit |
7cfc04 |
does not have to be an integer type. Its values must be obtained by a
|
|
Packit |
7cfc04 |
call to
|
|
Packit |
7cfc04 |
\fIfegetexceptflag\fR(),
|
|
Packit |
7cfc04 |
and cannot be created by logical operations from the exception macros.
|
|
Packit |
7cfc04 |
An implementation might simply implement
|
|
Packit |
7cfc04 |
.BR fexcept_t
|
|
Packit |
7cfc04 |
as an
|
|
Packit |
7cfc04 |
.BR int
|
|
Packit |
7cfc04 |
and use the representations reflected by the exception macros, but is
|
|
Packit |
7cfc04 |
not required to; other representations might contain extra information
|
|
Packit |
7cfc04 |
about the exceptions.
|
|
Packit |
7cfc04 |
.BR fexcept_t
|
|
Packit |
7cfc04 |
might be a
|
|
Packit |
7cfc04 |
.BR struct
|
|
Packit |
7cfc04 |
with a member for each exception (that might hold the address of the
|
|
Packit |
7cfc04 |
first or last floating-point instruction that caused that exception).
|
|
Packit |
7cfc04 |
The ISO/IEC\ 9899:\|1999 standard makes no claims about the internals of an
|
|
Packit |
7cfc04 |
.BR fexcept_t ,
|
|
Packit |
7cfc04 |
and so the user cannot inspect it.
|
|
Packit |
7cfc04 |
.SS "Exception and Rounding Macros"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Macros corresponding to unsupported modes and rounding directions are
|
|
Packit |
7cfc04 |
not defined by the implementation and must not be defined by the
|
|
Packit |
7cfc04 |
application. An application might use
|
|
Packit |
7cfc04 |
.BR #ifdef
|
|
Packit |
7cfc04 |
to test for this.
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
The System Interfaces volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "\fIfeclearexcept\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIfegetenv\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIfegetexceptflag\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIfegetround\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIfeholdexcept\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIferaiseexcept\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIfetestexcept\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIfeupdateenv\fR\^(\|)"
|
|
Packit |
7cfc04 |
.SH COPYRIGHT
|
|
Packit |
7cfc04 |
Portions of this text are reprinted and reproduced in electronic form
|
|
Packit |
7cfc04 |
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
|
|
Packit |
7cfc04 |
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Packit |
7cfc04 |
Specifications Issue 7, Copyright (C) 2013 by the Institute of
|
|
Packit |
7cfc04 |
Electrical and Electronics Engineers, Inc and The Open Group.
|
|
Packit |
7cfc04 |
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
|
|
Packit |
7cfc04 |
event of any discrepancy between this version and the original IEEE and
|
|
Packit |
7cfc04 |
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
Packit |
7cfc04 |
is the referee document. The original Standard can be obtained online at
|
|
Packit |
7cfc04 |
http://www.unix.org/online.html .
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
Any typographical or formatting errors that appear
|
|
Packit |
7cfc04 |
in this page are most likely
|
|
Packit |
7cfc04 |
to have been introduced during the conversion of the source files to
|
|
Packit |
7cfc04 |
man page format. To report such errors, see
|
|
Packit |
7cfc04 |
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|