Compiler features required by the GNU C Library
In general, we intend the GNU C Library to be usable to compile programs with any ISO-conformant C compiler. However, for technical reasons, glibc requires compilers to implement a small number of extensions to the C standard, and to implement certain behaviors that are implementation-defined or unspecified in the C standard in a specific way. This page documents these additional requirements. It is not yet complete; if you know of requirements that are not mentioned here, please add them.
Note that using glibc to compile programs is not the same as compiling glibc itself. glibc itself can only be compiled using GCC.
Some compilers other than GCC declare themselves as closely compatible with GCC, by defining the preprocessor macros __GNUC__ and __GNUC_MINOR__. We advise against doing this, in the strongest possible terms. To the best of our knowledge, no compiler has ever duplicated all of GCC's numerous extensions to C, and glibc's headers may use any of those extensions if they observe these macros to be defined, as may application programs. We have had to make a few too many special exceptions in our headers for the existing allegedly closely compatible compilers. Instead, please talk to us about making appropriate additions to our features.h and sys/cdefs.h so that your compiler's analogous extensions are also used.
Versions of the C standard
Compilers to be used with the GNU C library must be complete freestanding implementations of the base ISO C standard, ISO/IEC 9899:1990. Support for the additional language features in the 1999 and 2011 revisions of the C standard is strongly recommended. "Traditional" (pre-standardization, K&R) C compilers cannot be used with glibc; its headers use C1990 features (e.g. prototypes, const, and void) even if __STDC__ is not defined.
Compilers that advertise compliance with newer versions of the C standard (1999, 2011, 2018), by defining __STDC_VERSION__ appropriately, must implement all of the mandatory language features for that version. There are a few exceptions:
Library headers added to the C standard in newer versions (C1990 Amendment 1: wchar.h, wctype.h; C1999: complex.h, fenv.h, inttypes.h, stdint.h, tgmath.h; C2011: threads.h, uchar.h) may make unconditional use of features from the standard where they were added.
Glibc does not implement the aspects of Annex G relating to pure imaginary numbers. A compiler that defines __STDC_IEC_559_COMPLEX__ is nonetheless not expected to implement pure imaginary types.
- Glibc is most commonly used with compilers that, by default, do not convert trigraphs. Its headers might accidentally contain character sequences that would be misinterpreted by compilers that do convert trigraphs. We do consider all such cases to be bugs.
(As a practical matter, no one has tested glibc together with a C1990-only compiler in many years; some features of the 1999 and 2011 standards may be used unconditionally. We do consider any such cases to be bugs in our headers, but we may not treat them as high priority.)
Version Signaling
A compiler that supports multiple historical versions of the C standard, controllable at run time with command-line switches or equivalent, should set __STDC_VERSION__ appropriately in each mode.
A compiler that intends to provide strict conformance to the ISO C standard should define the macro __STRICT_ANSI__, with value 1. This causes the ISO C standard headers to behave as if they contain only the macros and declarations specified by the C standard as of __STDC_VERSION__. If the header did not appear in that version of the C standard, it will behave as if it contains the macros and declarations specified by the earliest version of the C standard in which it does appear. Headers specified by POSIX and not ISO C will behave as if they contain the macros and declarations specified by the first version of POSIX in which they appear. (Application programs can request additional declarations by defining "feature test macros" before including any headers.)
If the strictness of a compiler's conformance to ISO C is controllable at runtime, it should define __STRICT_ANSI__ only in its strictest mode.
C++
All of glibc's headers are intended to be usable from C++ programs, but this has not been as thoroughly tested as usability from C, especially for headers that are not part of the ISO C and/or POSIX standards. Please report all cases of headers not usable from C++ as bugs.
C++ compilers used with glibc must be complete freestanding implementations of the base ISO C standard, ISO/IEC 14882:1998. The __cplusplus macro must be defined to the appropriate value for the revision of the C++ standard that is implemented.
glibc does not provide any of the facilities of the C++ Standard Library that are not part of the ISO C or POSIX standards, and its headers do not make any use of the standard C++ headers.
Some of glibc's headers support declaring C library functions with the slightly different prototypes specified by the C++ standard. For instance, string.h can declare memchr with two overloads,
instead of the single prototype specified by the C standard,
1 extern void *memchr(const void *, int, size_t);
This behavior is currently limited to GCC's C++ compiler because the C++ standard library needs to be aware of it, and we only know for certain that GCC's C++ standard library is aware. We will cheerfully extend the behavior to other C++ compilers on request.
Required Implementation-Defined and Unspecified Behavior
The compiler must comply with the additional requirements placed on a freestanding implementation by POSIX; in particular, CHAR_BIT must be 8, the exact-width integral types and (u)intptr_t are required, and signed integer types must use twos-complement representation. 64-bit integer types must be available. All pointers (including both function and object pointers) must have the same size and representation. The null pointer must have the same representation as (uintptr_t)0 (that is, all bits zero).
sizeof(void *) and sizeof(size_t) must be no larger than sizeof(long). This was implicitly required by C1990; the requirement was relaxed in C1999 but we still require it.
Glibc has not been tested in many years, perhaps not ever, with an implementation where the basic execution character set is not ASCII-compatible, or where the standard integer types have padding bits. We would at least consider patches to make it compatible with such implementations, but we have no plans to develop those patches ourselves. Please consult with us before developing any such patches; we don't want you to spend a lot of time on work that we might not ultimately accept.
Glibc currently does not support any compiler or operating system that uses an object code format other than ELF. We are not interested in patches to support proprietary environments that use other object code formats. We would consider patches to support Free environments that use other object code formats, but, again, please consult with us before developing any such patches.
Required Headers
The compiler must provide the headers required of a freestanding implementation: float.h, limits.h, stdarg.h, and stddef.h. C1999 compliant compilers must also provide iso646.h and stdbool.h; C2011 compliant compilers must also provide stdalign.h and stdnoreturn.h.
Because the types defined by stdint.h are also required to be defined by several other headers specified by POSIX, glibc provides this header. The compiler should not provide this header in its hosted mode.
The POSIX standard requires several additional definitions in limits.h. Because of this, glibc's headers must cooperate with the compiler's limits.h to make all of the appropriate definitions. The existing mechanism for this cooperation is somewhat fragile and depends on GCC's #include_next extension. If you have a better idea please tell us about it.
The macro NULL and the types size_t, ptrdiff_t, and wchar_t are required to be defined by several other standard headers as well as by stddef.h. None of those headers are allowed to define offsetof or max_align_t, so they cannot simply include stddef.h. Because of this, glibc requires the compiler's stddef.h to implement the following protocol:
stddef.h must #undef NULL before defining it, in case it has already been defined.
If the macro _SIZE_T is defined, this means size_t has already been declared, and stddef.h must not declare it again. Similarly, if _PTRDIFF_T is defined, stddef.h must not declare ptrdiff_t, and if _WCHAR_T is defined, it must not declare wchar_t.
If any of the macros __need_size_t, __need_ptrdiff_t, __need_wchar_t, and/or __need_NULL are defined upon inclusion of stddef.h, stddef.h must provide only a subset of its usual definitions, corresponding to the set of macros that are defined. (However, anything that is already declared, according to _SIZE_T etc., must not be declared again.) This must happen even if C++2020 "modules" are in use. It must then undefine all of the __need_* macros.
Some older versions of glibc also expected stddef.h to declare wint_t when included with __need_wint_t defined. This is no longer required.
stddef.h must be prepared to be included multiple times with different sets of __need_* macros defined, making the appropriate set of definitions each time. Only if none of the above __need_* macros are defined should it declare offsetof and (in C2011 mode) max_align_t and activate a whole-file reinclusion guard.
Several standard headers are required to declare functions that take an argument of type va_list, but are also required not to declare va_list or define any of the macros defined by stdarg.h. Therefore, glibc requires the compiler's stdarg.h to implement a similar protocol to the one for stddef.h:
stdarg.h must define the typedef name __gnuc_va_list as the same underlying type that it uses to define va_list. It must also define the macro __GNUC_VA_LIST (the value of this macro does not matter) to indicate that it has done this. (These names are used for historical reasons.)
If the macro __need___va_list is defined upon inclusion of stdarg.h, stdarg.h must define only the typedef name __gnuc_va_list and the macro __GNUC_VA_LIST, not va_list, any of the va_* macros, or any other name in the user namespace. It must then undefine __need___va_list.
stdarg.h must be prepared to be included multiple times with and without __need___va_list defined.
If the macro _VA_LIST is defined, this means va_list has already been declared, and stddef.h must not declare it again.
Required Extensions to C
On CPU architectures that support multiple ABIs, the compiler must provide predefined preprocessor macros that indicate which ABI is currently in use. The names and semantics of the expected macros are architecture-specific. They are usually specified in the ELF psABI document for the architecture. Common cases include macros that indicate whether pointers and long are 32 or 64 bits wide, and macros that indicate whether values are stored in memory in big- or little-endian byte order.
The compiler must provide some mechanism for declaring a function whose symbol name in an object file is different from its declared name visible to C code. For example, using the GCC extension for this purpose,
declares an external function that C programs can call by the name fscanf. If they do, a call to __isoc99_fscanf will appear in the object file.
The definition of _Complex_I and the CMPLX macros in complex.h is currently GCC-specific. We will cheerfully accept patches to add support for other compilers.
Some math.h macros depend on built-in functions such as __builtin_nan, __builtin_nans, __builtin_huge_val, __builtin_inff for a correct implementation.
tgmath.h currently requires arcane GCC extensions. We would consider patches to implement it in terms of the C2011 _Generic feature.
gconv.h requires the GNU extension of zero-size arrays at the end of structs (some code in glibc uses __gconv_info in ways not permitted for C1999 flexible array members).
Some headers may require flexible array members even in C1990 and C++.
Some headers, such as netinet/tcp.h, may require anonymous structs and unions (a C11 feature).
...
Optional Extensions to C
The compiler should predefine macros __SIZE_TYPE__, __PTRDIFF_TYPE__, __WCHAR_TYPE__, and __WINT_TYPE__, which expand to the underlying types to be used for size_t, ptrdiff_t, wchar_t, and wint_t respectively, in a form usable in a typedef statement. For instance:
1 typedef __SIZE_TYPE__ size_t;
should be a correct definition of size_t, in all compilation modes. Headers provided by the compiler should not undefine these macros under any circumstances.
The compiler should provide a built-in typedef name __builtin_va_list which can be used to define va_list:
1 typedef __builtin_va_list va_list;
should be a correct definition of va_list. It should also make __builtin_va_list a predefined macro that expands to __builtin_va_list, so that glibc's headers can easily detect that this typedef name is available.