ISO/ IEC 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: 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: <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