Refine documentation of libm exceptions goals.
[glibc.git] / CONFORMANCE
blobb23318ee9d4eda7f329925e0c343311b1534fa09
1 Conformance of the GNU libc with various standards
2 ==================================================
4 The GNU libc is designed to be conformant with existing standard as
5 far as possible.  To ensure this I've run various tests.  The results
6 are presented here.
9 Open Group's hdrchk
10 ===================
12 The hdrchk test suite is available from the Open Group at
14         ftp://ftp.rdg.opengroup.org/pub/unsupported/stdtools/hdrchk/
16 I've last run the suite on 2004-04-17 on a Linux/x86 system running
17 a Fedora Core 2 test 2 + updates with the following results [*]:
19         FIPS            No reported problems
21         POSIX90         No reported problems
23         XPG3            Prototypes are now in the correct header file
25 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
26 *** Starting unistd.h
27 Missing: extern char *  cuserid();
28 Missing: extern int     rename();
29 *** Completed unistd.h
30 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
32         XPG4            Prototype is now in the correct header file
33                         and the _POSIX2_C_VERSION symbol has been removed
35 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36 *** Starting unistd.h
37 Missing: extern char *  cuserid();
38 Missing: #define        _POSIX2_C_VERSION       (-1L)
39 *** Completed unistd.h
40 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
42         POSIX96         Prototype moved
43                         (using "base realtime threads" subsets)
45 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46 *** Starting unistd.h
47 Missing: extern int     pthread_atfork();
48 *** Completed unistd.h
49 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
51         UNIX98          Prototypes moved and _POSIX2_C_VERSION removed
52                         (using "base realtime threads mse lfs" subset)
54 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
55 *** Starting unistd.h
56 Missing: extern char *  cuserid();
57 Missing: #define        _POSIX2_C_VERSION       (-1L)
58 Missing: extern int     pthread_atfork();
59 *** Completed unistd.h
60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63 That means all the reported issues are due to the headers having been
64 cleaned up for recent POSIX/Unix specification versions.  Duplicated
65 prototypes have been removed and obsolete symbols have been removed.
66 Which means that as far as the tests performed by the script go, the
67 headers files comply to the current POSIX/Unix specification.
70 [*] Since the scripts are not clever enough for the way gcc handles
71 include files (namely, putting some of them in gcc-local directory) I
72 copied over the iso646.h, float.h, and stddef.h headers and ignored the
73 problems resulting from the split limits.h file).
76 Technical C standards conformance issues in glibc
77 =================================================
79 If you compile programs against glibc with __STRICT_ANSI__ defined
80 (as, for example, by gcc -ansi, gcc -std=c89, gcc -std=iso1990:199409
81 or gcc -std=c99), and use only the headers specified by the version of
82 the C standard chosen, glibc will attempt to conform to that version
83 of the C standard (as indicated by __STDC_VERSION__):
85 GCC options             Standard version
86 -ansi                   ISO/IEC 9899:1990
87 -std=c89                ISO/IEC 9899:1990
88 -std=iso9899:199409     ISO/IEC 9899:1990 as amended by Amd.1:1995
89 -std=c99                ISO/IEC 9899:1999
91 (Note that -std=c99 is not available in GCC 2.95.2, and that no
92 version of GCC presently existing implements the full C99 standard.)
94 You may then define additional feature test macros to enable the
95 features from other standards, and use the headers defined in those
96 standards (for example, defining _POSIX_C_SOURCE to be 199506L to
97 enable features from ISO/IEC 9945-1:1996).
99 There are some technical ways in which glibc is known not to conform
100 to the supported versions of the C standard, as detailed below.  Some
101 of these relate to defects in the standard that are expected to be
102 fixed, or to compiler limitations.
105 Defects in the C99 standard
106 ===========================
108 Some defects in C99 were corrected in Technical Corrigendum 1 to that
109 standard.  glibc follows the corrected specification.
112 Implementation of library functions
113 ===================================
115 The implementation of some library functions does not fully follow the
116 standard specification:
118 C99 added additional forms of floating point constants (hexadecimal
119 constants, NaNs and infinities) to be recognised by strtod() and
120 scanf().  The effect is to change the behavior of some strictly
121 conforming C90 programs; glibc implements the C99 versions only
122 irrespective of the standard version selected.
124 C99 added %a as another scanf format specifier for floating point
125 values.  This conflicts with the glibc extension where %as, %a[ and
126 %aS mean to allocate the string for the data read.  A strictly
127 conforming C99 program using %as, %a[ or %aS in a scanf format string
128 will misbehave under glibc if it does not include <stdio.h> and
129 instead declares scanf itself; if it gets the declaration of scanf
130 from <stdio.h>, it will use a C99-conforming version.
133 Compiler limitations
134 ====================
136 The macros __STDC_IEC_559__, __STDC_IEC_559_COMPLEX__ and
137 __STDC_ISO_10646__ are properly supposed to be constant throughout the
138 translation unit (before and after any library headers are included).
139 However, they mainly relate to library features, and GCC only knows to
140 preinclude <stdc-predef.h> to get their definitions in version 4.8 and
141 later.  Programs that test them before including any standard headers
142 may misbehave with older compilers.
144 GCC doesn't support the optional imaginary types.  Nor does it
145 understand the keyword _Complex before GCC 3.0.  This has the
146 corresponding impact on the relevant headers.
148 glibc's <tgmath.h> implementation is arcane but thought to work
149 correctly; a clean and comprehensible version requires compiler
150 builtins.
152 For most of the headers required of freestanding implementations,
153 glibc relies on GCC to provide correct versions.  (At present, glibc
154 provides <stdint.h>, and GCC doesn't before version 4.5.)
156 The definition of math_errhandling conforms so long as no translation
157 unit using math_errhandling is compiled with -fno-math-errno,
158 -fno-trapping-math or options such as -ffast-math that imply these
159 options.  math_errhandling is only conditionally defined depending on
160 __FAST_MATH__; the compiler does not provide the information needed
161 for more exact definitions based on settings of -fno-math-errno and
162 -fno-trapping-math, possibly for only some source files in a program.
165 Issues with headers
166 ===================
168 None known.