Pretty printing.
[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 2004-04-17 on a Linux/x86 system running
17 a Fedora Core 2 test 2 + updates with the following results [*]:
18
19         FIPS            No reported problems
20
21         POSIX90         No reported problems
22
23         XPG3            Prototypes are now in the correct header file
24
25 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
26 *** Starting unistd.h
27 Missing: extern char *  cuserid();
28 Missing: extern int     rename();
29 *** Completed unistd.h
30 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
31
32         XPG4            Prototype is now in the correct header file
33                         and the _POSIX2_C_VERSION symbol has been removed
34
35 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36 *** Starting unistd.h
37 Missing: extern char *  cuserid();
38 Missing: #define        _POSIX2_C_VERSION       (-1L)
39 *** Completed unistd.h
40 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
41
42         POSIX96         Prototype moved
43                         (using "base realtime threads" subsets)
44
45 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46 *** Starting unistd.h
47 Missing: extern int     pthread_atfork();
48 *** Completed unistd.h
49 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
50
51         UNIX98          Prototypes moved and _POSIX2_C_VERSION removed
52                         (using "base realtime threads mse lfs" subset)
53
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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
61
62
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.
68
69
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).
74
75
76 Technical C standards conformance issues in glibc
77 =================================================
78
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__):
84
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
90
91 * glibc does not support this standard version.
92
93 (Note that -std=c99 is not available in GCC 2.95.2, and that no
94 version of GCC presently existing implements the full C99 standard.)
95
96 You may then define additional feature test macros to enable the
97 features from other standards, and use the headers defined in those
98 standards (for example, defining _POSIX_C_SOURCE to be 199506L to
99 enable features from ISO/IEC 9945-1:1996).
100
101 There are some technical ways in which glibc is known not to conform
102 to the supported versions of the C standard, as detailed below.  Some
103 of these relate to defects in the standard that are expected to be
104 fixed, or to compiler limitations.
105
106
107 Defects in the C99 standard
108 ===========================
109
110 Some defects in C99 were corrected in Technical Corrigendum 1 to that
111 standard.  glibc follows the corrected specification.
112
113
114 Implementation of library functions
115 ===================================
116
117 The implementation of some library functions does not fully follow the
118 standard specification:
119
120 C99 added additional forms of floating point constants (hexadecimal
121 constants, NaNs and infinities) to be recognised by strtod() and
122 scanf().  The effect is to change the behavior of some strictly
123 conforming C90 programs; glibc implements the C99 versions only
124 irrespective of the standard version selected.
125
126 C99 added %a as another scanf format specifier for floating point
127 values.  This conflicts with the glibc extension where %as, %a[ and
128 %aS mean to allocate the string for the data read.  A strictly
129 conforming C99 program using %as, %a[ or %aS in a scanf format string
130 will misbehave under glibc.
131
132
133 Compiler limitations
134 ====================
135
136 The macros __STDC_IEC_559__, __STDC_IEC_559_COMPLEX__ and
137 __STDC_ISO_10646__ are properly supposed to be defined by the
138 compiler, and to be constant throughout the translation unit (before
139 and after any library headers are included).  However, they mainly
140 relate to library features, and the necessary magic has yet to be
141 implemented for GCC to predefine them to the correct values for the
142 library in use, so glibc defines them in <features.h>.  Programs that
143 test them before including any standard headers may misbehave.
144
145 GCC doesn't support the optional imaginary types.  Nor does it
146 understand the keyword _Complex before GCC 3.0.  This has the
147 corresponding impact on the relevant headers.
148
149 glibc's use of extern inline conflicts with C99: in C99, extern inline
150 means that an external definition is generated as well as possibly an
151 inline definition, but in GCC it means that no external definition is
152 generated.  When GCC's C99 mode implements C99 inline semantics, this
153 will break the uses of extern inline in glibc's headers.  (Actually,
154 glibc uses `extern __inline', which is beyond the scope of the
155 standard, but it would clearly be very confusing for `__inline' and
156 plain `inline' to have different meanings in C99 mode.)
157
158 glibc's <tgmath.h> implementation is arcane but thought to work
159 correctly; a clean and comprehensible version requires compiler
160 builtins.
161
162 For most of the headers required of freestanding implementations,
163 glibc relies on GCC to provide correct versions.  (At present, glibc
164 provides <stdint.h>, and GCC doesn't.)
165
166 Implementing MATH_ERRNO, MATH_ERREXCEPT and math_errhandling in
167 <math.h> needs compiler support: see
168
169 http://sources.redhat.com/ml/libc-hacker/2000-06/msg00008.html
170 http://sources.redhat.com/ml/libc-hacker/2000-06/msg00014.html
171 http://sources.redhat.com/ml/libc-hacker/2000-06/msg00015.html
172
173
174 Issues with headers
175 ===================
176
177 There are various technical issues with the definitions contained in
178 glibc's headers, listed below.  The list below assumes GCC 3.3.2, and
179 relates to i686-linux; older GCC may lead to more problems in the
180 headers.
181
182 Note that the _t suffix is reserved by POSIX, but not by pure ISO C.
183 Also, the Single Unix Specification generally requires more types to
184 be included in headers (if _XOPEN_SOURCE is defined appropriately)
185 than ISO C permits.
186
187 <ctype.h> should not declare size_t.
188
189 <signal.h> should not declare size_t.
190
191 <stdio.h> should not declare or use wchar_t or wint_t.
192
193 <wchar.h> does not support AMD1; to support it, the functions
194 fwprintf, fwscanf, wprintf, wscanf, swprintf, swscanf, vfwprintf,
195 vwprintf, vswprintf and fwide would need to be declared when
196 __STDC_VERSION__ >= 199409L and not just for C99.
197
198 <wctype.h> should not declare size_t.