2003-12-31 Joseph S. Myers <jsm@polyomino.org.uk>
[kopensolaris-gnu/glibc.git] / CONFORMANCE
1 Conformance of the GNU libc with various standards
2 ==================================================
3
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.
7
8
9 Open Group's hdrchk
10 ===================
11
12 The hdrchk test suite is available from the Open Group at
13
14         ftp://ftp.rdg.opengroup.org/pub/unsupported/stdtools/hdrchk/
15
16 I've last run the suite on 2000-08-13 on a Linux/ix86 system with the
17 following results [*]:
18
19         FIPS            No reported problems
20
21         POSIX90         No reported problems
22
23         XPG3            No reported problems
24
25         XPG4            No reported problems
26
27         POSIX96         Same as for UNIX98 (see below).
28         UNIX98          The message queue implementation is missing:
29
30 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
31 /****** <mqueue.h> - Missing include file ******/
32 /****** Start of Definitions for file mqueue.h ******/
33 extern int mq_close();
34 extern int mq_getattr();
35 extern int mq_notify();
36 extern mqd_t mq_open();
37 extern ssize_t mq_receive();
38 extern int mq_send();
39 extern int mq_setattr();
40 extern int mq_unlink();
41 typedef <type> mqd_t;
42 struct mq_attr { <members> };
43 struct sigevent { <members> };
44 /****** End of Definitions for file mqueue.h ******/
45 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46
47 [*] Since the scripts are not clever enough for the way gcc handles
48 include files (namely, putting some of them in gcc-local directory) I
49 copied over the iso646.h, float.h, and stddef.h headers and ignored the
50 problems resulting from the splitted limits.h file).
51
52
53 Technical C standards conformance issues in glibc
54 =================================================
55
56 If you compile programs against glibc with __STRICT_ANSI__ defined
57 (as, for example, by gcc -ansi, gcc -std=c89, gcc -std=iso1990:199409
58 or gcc -std=c99), and use only the headers specified by the version of
59 the C standard chosen, glibc will attempt to conform to that version
60 of the C standard (as indicated by __STDC_VERSION__):
61
62 GCC options             Standard version
63 -ansi                   ISO/IEC 9899:1990
64 -std=c89                ISO/IEC 9899:1990
65 -std=iso9899:199409     ISO/IEC 9899:1990 as amended by Amd.1:1995 *
66 -std=c99                ISO/IEC 9899:1999
67
68 * glibc does not support this standard version.
69
70 (Note that -std=c99 is not available in GCC 2.95.2, and that no
71 version of GCC presently existing implements the full C99 standard.)
72
73 You may then define additional feature test macros to enable the
74 features from other standards, and use the headers defined in those
75 standards (for example, defining _POSIX_C_SOURCE to be 199506L to
76 enable features from ISO/IEC 9945-1:1996).
77
78 There are some technical ways in which glibc is known not to conform
79 to the supported versions of the C standard, as detailed below.  Some
80 of these relate to defects in the standard that are expected to be
81 fixed, or to compiler limitations.
82
83
84 Defects in the C99 standard
85 ===========================
86
87 Some defects in C99 were corrected in Technical Corrigendum 1 to that
88 standard.  glibc follows the corrected specification.
89
90
91 Implementation of library functions
92 ===================================
93
94 The implementation of some library functions does not fully follow the
95 standard specification:
96
97 C99 added additional forms of floating point constants (hexadecimal
98 constants, NaNs and infinities) to be recognised by strtod() and
99 scanf().  The effect is to change the behavior of some strictly
100 conforming C90 programs; glibc implements the C99 versions only
101 irrespective of the standard version selected.
102
103 C99 added %a as another scanf format specifier for floating point
104 values.  This conflicts with the glibc extension where %as, %a[ and
105 %aS mean to allocate the string for the data read.  A strictly
106 conforming C99 program using %as, %a[ or %aS in a scanf format string
107 will misbehave under glibc.
108
109
110 Compiler limitations
111 ====================
112
113 The macros __STDC_IEC_559__, __STDC_IEC_559_COMPLEX__ and
114 __STDC_ISO_10646__ are properly supposed to be defined by the
115 compiler, and to be constant throughout the translation unit (before
116 and after any library headers are included).  However, they mainly
117 relate to library features, and the necessary magic has yet to be
118 implemented for GCC to predefine them to the correct values for the
119 library in use, so glibc defines them in <features.h>.  Programs that
120 test them before including any standard headers may misbehave.
121
122 GCC doesn't support the optional imaginary types.  Nor does it
123 understand the keyword _Complex before GCC 3.0.  This has the
124 corresponding impact on the relevant headers.
125
126 glibc's use of extern inline conflicts with C99: in C99, extern inline
127 means that an external definition is generated as well as possibly an
128 inline definition, but in GCC it means that no external definition is
129 generated.  When GCC's C99 mode implements C99 inline semantics, this
130 will break the uses of extern inline in glibc's headers.  (Actually,
131 glibc uses `extern __inline', which is beyond the scope of the
132 standard, but it would clearly be very confusing for `__inline' and
133 plain `inline' to have different meanings in C99 mode.)
134
135 glibc's <tgmath.h> implementation is arcane but thought to work
136 correctly; a clean and comprehensible version requires compiler
137 builtins.
138
139 For most of the headers required of freestanding implementations,
140 glibc relies on GCC to provide correct versions.  (At present, glibc
141 provides <stdint.h>, and GCC doesn't.)
142
143 Implementing MATH_ERRNO, MATH_ERREXCEPT and math_errhandling in
144 <math.h> needs compiler support: see
145
146 http://sources.redhat.com/ml/libc-hacker/2000-06/msg00008.html
147 http://sources.redhat.com/ml/libc-hacker/2000-06/msg00014.html
148 http://sources.redhat.com/ml/libc-hacker/2000-06/msg00015.html
149
150
151 Issues with headers
152 ===================
153
154 There are various technical issues with the definitions contained in
155 glibc's headers, listed below.  The list below assumes GCC 3.3.2, and
156 relates to i686-linux; older GCC may lead to more problems in the
157 headers.
158
159 Note that the _t suffix is reserved by POSIX, but not by pure ISO C.
160 Also, the Single Unix Specification generally requires more types to
161 be included in headers (if _XOPEN_SOURCE is defined appropriately)
162 than ISO C permits.
163
164 <ctype.h> should not declare size_t.
165
166 <signal.h> should not declare size_t.
167
168 <stdio.h> should not declare or use wchar_t or wint_t.
169
170 <wchar.h> does not support AMD1; to support it, the functions
171 fwprintf, fwscanf, wprintf, wscanf, swprintf, swscanf, vfwprintf,
172 vwprintf, vswprintf and fwide would need to be declared when
173 __STDC_VERSION__ >= 199409L and not just for C99.
174
175 <wctype.h> should not declare size_t.