JTC1/SC22/WG14
N752
* Document Number: WG14 N752/J11 97-115
C9X Revision Proposal
=====================
* Title: LIA-1 Binding: Optional parts annex
Author: Fred J. Tydeman
Author Affiliation: Tydeman Consulting
Postal Address: 3711 Del Robles Dr., Austin, Texas, USA, 78727
E-mail Address: [email protected]
Telephone Number: +1 (512) 255-8696
Fax Number: +1 (512) 255-8696
Sponsor: WG14
Date: 1997-09-16
Proposal Category:
__ Editorial change/non-normative contribution
__ Correction
Y_ New feature
__ Addition to obsolescent feature list
__ Addition to Future Directions
__ Other (please specify) ______________________________
Area of Standard Affected:
__ Environment
__ Language
__ Preprocessor
Y_ Library
Y_ Macro/typedef/tag name
Y_ Function
__ Header
__ Other (please specify) ______________________________
Prior Art: Very little. Cray Research has implemented
fe*trap() functions similar to these proposed ones. That is
part of one of the optional features.
Target Audience: Programmers writing programs that perform a
significant amount of numeric processing.___________________
Related Documents (if any):
WG14/N758 C9X and LIA-1 informative annex,
WG14/N756 LIA-1 Binding: Arithmetic exception => SIGFPE,
WG14/N755 LIA-1 Binding: <fenv.h> to <stdmath.h>,
WG14/N753 LIA-1 Binding: Rationale,
WG14/N751 LIA-1 Binding: Combined LIA-1 + IEC-559 annex,
WG14/N750 LIA-1 Binding: LIA-1 annex,
WG14/N749 LIA-1 Binding: <stdlia.h>,
WG14/N748 LIA-1 Binding: Adding 'pole' from LIA-2,
WG14/N747 IEC 559 Binding: Signaling NaNs,
WG14/N528 C Binding for LIA-1,
WG14/N488 LIA-2 (math library),
WG14/N487 LIA-1 (arithmetic),
WG14/N486 LIA Overview,
WG14/N463 Impact of adding LIA-1,
WG14/N461 C Binding of LIA-1
Proposal Attached: _Y Yes __ No, but what's your interest?
Abstract: This part of the C9X+LIA binding discusses the
optional parts of LIA and how they would be supported via an
informative annex.
Proposal:
Note: The '*' characters in the lefthand column are not part
of the proposal (they are useful for emacs M-x outline mode)
In the following, bold text, italic text,
<TT>code sample</TT> are the conventions used to indicate
text different from normal.
* -- Add new annex, call it J, before existing annex H
Common warnings.
Annex J
(informative)
** I.1 Introduction
This annex supplements Annex H to specify optional parts of
LIA-1.
Defining syntax for optional facilities does not make those
facilities required. All it does is ensure that those
implementations that choose to provide an optional facility
will do so using a standardized syntax.
This annex provides standard syntax and semantics for
optional features that an implementation may wish to
support.
** I.2 The LIA_NOTIFY pragma is extended to include DYNAMIC.
*** Add to <stdlia.h> Subclause 7.x.4.1.1 The LIA_NOTIFY pragma:
#pragma STDC LIA_NOTIFY { ... | DYNAMIC }
DYNAMIC means that the program will enable/disable trapping
at runtime. When trapping is disabled, then notification
shall be via flags. When trapping is enabled, notification
shall be via traps.
** I.3 The LIA_WRAP pragma
*** Add <stdlia.h> Subclause: 7.x.4.1.3. The LIA_WRAP pragma
Synopsis
#include <stdlia.h>
#pragma STDC LIA_WRAP on_off_switch
Description
The LIA_WRAP pragma provides a means to inform the
implementation whether out-of-bounds signed integers of
types int, long, and long long should wrap (similar to
unsigned integers) or notify. The pragma can occur either
outside external declarations or preceding all explicit
declarations and statements inside a compound statement.
When outside external declarations, the pragma takes effect
from its occurrence until another LIA_WRAP pragma is
encountered, or until the end of the translation unit. When
inside a compound statement, the pragma takes effect from
its occurrence until another LIA_WRAP pragma is encountered
(within a nested compound statement), or until the end of
the compound statement; at the end of a compound statement
the state for the pragma is restored to its condition just
before the compound statement. The effect of this pragma in
any other context is undefined. The default state for the
pragma is implementation-defined.
The value of INT_OUT_OF_BOUNDS macro shall track the state
of this pragma.
** I.4 Notification via traps
The headers <fenv.h> and <stdlia.h> are extended to include
macros to denote traps and functions to enable, disable, and
test trapping. When a trap is disabled and a notification
happens, the corresponding flag is set. When a trap is
enabled and a notification happens, SIGFPE is raised.
SIGFPE shall be raised if an enable for a flag is
done and then that same flag is set.
It is implementation defined if SIGFPE is raised if a
flag is set and then an enable for that same flag is done.
*** Add new <fenv.h> Subclause: 7.6.y Floating-point trapping
**** Add <fenv.h> Subclause: 7.6.y.1 The floating-point trap macros
Each macro
FE_TRAP_INVALID
FE_TRAP_DIVBYZERO
FE_TRAP_OVERFLOW
FE_TRAP_UNDERFLOW
FE_TRAP_INEXACT
is defined if and only if the implementation supports the
trap by means of the functions in 7.6.y. The defined macros
expand to integral constant expressions whose values are
distinct powers of 2. FE_TRAP_INVALID, FE_TRAP_DIVBYZERO,
FE_TRAP_OVERFLOW, and FE_TRAP_UNDERFLOW shall be defined for
LIA-1 conformance. In addition to the LIA-1 trap macros,
FE_TRAP_INEXACT shall be defined for IEC 559 conformance.
The macro
FE_TRAP_ALL
is simply the bitwise OR of all floating-point trap macros
defined by the implementation.
**** Add <fenv.h> Subclause: 7.6.y.2 Trap enable/disable functions
The fedisabletrap and feenabletrap functions provide control
of floating-point trapping modes. The fetesttrap function
provides status of trapping.
***** Add <fenv.h> Subclause: 7.6.y.2.1 The fedisabletrap function
Synopsis
#include <fenv.h>
int fedisabletrap( int traps );
Description
The fedisabletrap function disables traps for the
supported exceptions represented by its argument.
Returns
The fedisabletrap function returns a value that
corresponds to the set (bitwise OR of the floating-point
trap macros) of traps it disabled[footnote].
[footnote]fedisabletrap(~0) shall return FE_TRAP_ALL.
***** Add <fenv.h> Subclause: 7.6.y.2.2 The feenabletrap function
Synopsis
#include <fenv.h>
int feenabletrap( int traps );
Description
The feenabletrap function enables traps for the
supported exceptions represented by its argument.
Returns
The feenabletrap function returns a value that
corresponds to the set (bitwise OR of the floating-point
trap macros) of traps it enabled.
***** Add <fenv.h> Subclause: 7.6.y.2.3 The fetesttrap function
Synopsis
#include <fenv.h>
int fetesttrap( int traps );
Description
The fetesttrap function determines which of a
specified subset of the floating-point traps are currently
enabled. The traps argument specifies the
floating-point traps to be queried.
Returns
The fetesttrap function returns the value of the set
(bitwise OR of the floating-point trap macros) corresponding
to the currently enabled traps included in traps.
*** Add new <stdlia.h> Subclause: 7.x.4.3 Integer Trapping:
**** Add <stdlia.h> Subclause: 7.x.4.3.1 The integer trap macros
Each macro
INT_TRAP_INVALID
INT_TRAP_DIVBYZERO
INT_TRAP_OVERFLOW
is defined if and only if the implementation supports the
trap by means of the functions in 7.x.4.3. The defined macros
expand to integral constant expressions whose values are
distinct powers of 2. INT_TRAP_INVALID, INT_TRAP_DIVBYZERO,
and INT_TRAP_OVERFLOW shall be defined for LIA-1
conformance.
The macro
INT_TRAP_ALL
is simply the bitwise OR of all integer trap macros defined
by the implementation.
The iedisabletrap and ieenabletrap functions provide control
of integer trapping modes.
**** Add <stdlia.h> Subclause: 7.x.4.3.2 Trap enable/disable functions
The iedisabletrap and ieenabletrap functions provide control
of integer trapping modes. The ietesttrap function provides
status of trapping.
***** Add <stdlia.h> Subclause: 7.x.4.3.2.1 The iedisabletrap function
Synopsis
#include <stdlia.h>
int iedisabletrap( int traps );
Description
The iedisabletrap function disables traps for the
supported exceptions represented by its argument.
Returns
The iedisabletrap function returns a value that
corresponds to the set (bitwise OR of the integer trap
macros) of traps it disabled[footnote].
[footnote]iedisabletrap(~0) shall return INT_TRAP_ALL.
***** Add <stdlia.h> Subclause: 7.x.4.3.2.2 The ieenabletrap function
Synopsis
#include <stdlia.h>
int ieenabletrap( int traps );
Description
The ieenabletrap function enables traps for the
supported exceptions represented by its argument.
Returns
The ieenabletrap function returns a value that
corresponds to the set (bitwise OR of the integer trap
macros) of traps it enabled.
***** Add <stdlia.h> Subclause: 7.x.4.3.2.3 The ietesttrap function
Synopsis
#include <stdlia.h>
int ietesttrap( int traps );
Description
The ietesttrap function determines which of a
specified subset of the integer traps are currently enabled.
The traps argument specifies the integer traps to be
queried.
Returns
The ietesttrap function returns the value of the set
(bitwise OR of the integer trap macros) corresponding to the
currently enabled traps included in traps.
** I.5 Precision control
*** Add new <fenv.h> Subclause: 7.6.z Rounding precision control
The fegetprec and fesetprec functions provide control of
dynamic precision modes.
Each macro
FE_FLTPREC
FE_DBLPREC
FE_LDBLPREC
is defined if and only if the implementation supports the
dynamic precision by means of the functions in 7.6.z. The
defined macros expand to integral constant expressions whose
values are distinct.
**** Add <fenv.h> Subclause: 7.6.z.1 The fegetprec function
Synopsis
#include <fenv.h>
int fegetprec(void);
Description
The fegetprec function gets the current precision.
Returns
The fegetprec function returns the value of the
precision macro representing the current precision.
**** Add <fenv.h> Subclause: 7.6.z.2 The fesetprec function
Synopsis
#include <fenv.h>
int fesetprec(int prec);
Description
The fesetprec function establishes the precision
represented by its argument prec. If the argument
does not match a precision macro, the precision is not
changed.
Returns
The fesetprec function returns a nonzero value if and
only if the argument matches a precision macro (that is, if
and only if the requested precision can be established).
** I.6 7.x.1.2 Floating-point limits is extended to
include characteristics of partial LIA-1 conformity
(see Annex B of LIA-1).
The following are added after HAS_DENORM_LOSS:
-- boolean value (0 or 1) to indicate if LIA-1 strict 1-ulp
accuracy and a common rounding rule for +, -, *, and / is
used,
LIA_STRICT
-- boolean value (0 or 1) to indicate if underflows are
silent (do not produce a notification),
SILENT_UNDERFLOW
-- boolean value (0 or 1) to indicate if comparisons may
overflow or underflow like subtraction,
COMPARISON_VIA_SUBTRACT
-- boolean value (0 or 1) to indicate if negate may fail
because floating-point values are not sign symmetric,
NEGATE_MAY_FAIL
For LIA-1 conformance,
The LIA_STRICT macro must be 1.
The SILENT_UNDERFLOW macro must be 0.
The COMPARISON_VIA_SUBTRACT macro must be 0.
The NEGATE_MAY_FAIL macro must be 0.
The following is added to D.x.1.2 Floating-point
limits
LIA_STRICT
SILENT_UNDERFLOW
COMPARISON_VIA_SUBTRACT
NEGATE_MAY_FAIL