* 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: tydeman@tybor.com 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: to , 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: , 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, code sample 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 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 Subclause: 7.x.4.1.3. The LIA_WRAP pragma Synopsis #include #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 and 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 Subclause: 7.6.y Floating-point trapping **** Add 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 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 Subclause: 7.6.y.2.1 The fedisabletrap function Synopsis #include 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 Subclause: 7.6.y.2.2 The feenabletrap function Synopsis #include 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 Subclause: 7.6.y.2.3 The fetesttrap function Synopsis #include 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 Subclause: 7.x.4.3 Integer Trapping: **** Add 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 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 Subclause: 7.x.4.3.2.1 The iedisabletrap function Synopsis #include 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 Subclause: 7.x.4.3.2.2 The ieenabletrap function Synopsis #include 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 Subclause: 7.x.4.3.2.3 The ietesttrap function Synopsis #include 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 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 Subclause: 7.6.z.1 The fegetprec function Synopsis #include 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 Subclause: 7.6.z.2 The fesetprec function Synopsis #include 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