The documentation of which standard C library facilities (headers) are
provided by GCC, as being those required of freestanding
implementations, is reasonably accurate for C99 and before (if you
ignore the provision of <tgmath.h> for non-GNU targets). It's less
accurate for C11, since we provide <stdatomic.h> although that's not
required for freestanding implementations. And it's very inaccurate
for C23, which specifies that freestanding implementations also
provide most of <string.h>, memalignment from <stdlib.h>, and, when
supporting Annex F, also <fenv.h>, <math.h> and the strto*
floating-point numeric conversion functions from <stdlib.h>.
I don't think expanding the scope of the C library facilities GCC
provides to include all those extra facilities specified by C23 for
freestanding implementations is a good idea. (Indeed, GCC once used
to install assert.h on some platforms, but stopped doing so a long
time ago.) Rather, it seems better to document that in both the
freestanding and the hosted cases, GCC is intended to provide the
compiler part of a conforming implementation, to be combined with a
corresponding library implementation, rather than providing all the
required library facilities in either case.
The rule about which headers GCC provides is then described in terms
of headers not declaring functions with external linkage, which is
much closer to existing practice, although still not perfect in all
cases (<stdatomic.h>, although mainly providing type-generic
operations, does declare a few non-type-generic functions that we
provide in libatomic).
A paragraph in trouble.texi that talks about freestanding
implementations with -ansi -pedantic is not changed (given that the
description in terms of freestanding implementations is sufficiently
accurate for C90); if the -ansi there were changed to an option for a
more recent standard, a corresponding change to that paragraph might
be needed as well.
Tested with "make info html pdf".
* doc/standards.texi (C Language): Document library facilities
provided in terms of headers not declaring functions with external
linkage, not in terms of headers required of freestanding
implementations.
* doc/sourcebuild.texi (Subdirectories, Headers): Likewise.
* doc/trouble.texi (Standard Libraries): Likewise.
diff --git a/gcc/doc/sourcebuild.texi b/gcc/doc/sourcebuild.texi
index 91fadc6ed01d..90430028eb86 100644
--- a/gcc/doc/sourcebuild.texi
+++ b/gcc/doc/sourcebuild.texi
@@ -215,10 +215,10 @@ man pages and support for converting the installation
manual to
HTML@. @xref{Documentation}.
@item ginclude
-System headers installed by GCC, mainly those required by the C
-standard of freestanding implementations. @xref{Headers, , Headers
-Installed by GCC}, for details of when these and other headers are
-installed.
+System headers installed by GCC, mainly those defined by the C
+standard that do not declare functions with external linkage.
+@xref{Headers, , Headers Installed by GCC}, for details of when these
+and other headers are installed.
@item po
Message catalogs with translations of messages produced by GCC into
@@ -326,7 +326,8 @@ Headers Installed by GCC}, for more information about the
In general, GCC expects the system C library to provide most of the
headers to be used with it. However, GCC will fix those headers if
necessary to make them work with GCC, and will install some headers
-required of freestanding implementations. These headers are installed
+of its own, mainly headers that do not declare functions with external
+linkage. These headers are installed
in @file{@var{libsubdir}/include}. Headers for non-C runtime
libraries are also installed by GCC; these are not documented here.
(FIXME: document them somewhere.)
@@ -351,8 +352,8 @@ representation of floating point numbers.
GCC also installs its own version of @code{<limits.h>}; this is generated
from @file{glimits.h}, together with @file{limitx.h} and
@file{limity.h} if the system also has its own version of
-@code{<limits.h>}. (GCC provides its own header because it is
-required of ISO C freestanding implementations, but needs to include
+@code{<limits.h>}. (GCC provides its own header because it does not
+declare functions with external linkage, but needs to include
the system header from its own header as well because other standards
such as POSIX specify additional values to be defined in
@code{<limits.h>}.) The system's @code{<limits.h>} header is used via
diff --git a/gcc/doc/standards.texi b/gcc/doc/standards.texi
index bbae3501a546..011f7e292079 100644
--- a/gcc/doc/standards.texi
+++ b/gcc/doc/standards.texi
@@ -152,7 +152,9 @@ library facilities: those in @code{<float.h>},
@code{<limits.h>},
@code{<iso646.h>}; since C99, also those in @code{<stdbool.h>} and
@code{<stdint.h>}; and since C11, also those in @code{<stdalign.h>}
and @code{<stdnoreturn.h>}. In addition, complex types, added in C99, are not
-required for freestanding implementations.
+required for freestanding implementations. Since C23, freestanding
+implementations are required to support a larger range of library
+facilities, including some functions from other headers.
The standard also defines two environments for programs, a
@dfn{freestanding environment}, required of all implementations and
@@ -167,13 +169,13 @@ a program using the facilities of an
operating system is an example of a program running in a hosted environment.
@opindex ffreestanding
-GCC aims towards being usable as a conforming freestanding
-implementation, or as the compiler for a conforming hosted
-implementation. By default, it acts as the compiler for a hosted
+GCC aims towards being usable as the compiler for a conforming
+freestanding or hosted implementation.
+By default, it acts as the compiler for a hosted
implementation, defining @code{__STDC_HOSTED__} as @code{1} and
presuming that when the names of ISO C functions are used, they have
-the semantics defined in the standard. To make it act as a conforming
-freestanding implementation for a freestanding environment, use the
+the semantics defined in the standard. To make it act as the compiler
+for a freestanding environment, use the
option @option{-ffreestanding}; it then defines
@code{__STDC_HOSTED__} to @code{0} and does not make assumptions about the
meanings of function names from the standard library, with exceptions
@@ -181,12 +183,24 @@ noted below. To build an OS kernel, you may well still
need to make
your own arrangements for linking and startup.
@xref{C Dialect Options,,Options Controlling C Dialect}.
-GCC does not provide the library facilities required only of hosted
-implementations, nor yet all the facilities required by C99 of
-freestanding implementations on all platforms.
-To use the facilities of a hosted
-environment, you need to find them elsewhere (for example, in the
-GNU C library). @xref{Standard Libraries,,Standard Libraries}.
+GCC generally provides library facilities in headers that do not
+declare functions with external linkage (which includes the headers
+required by C11 and before to be provided by freestanding
+implementations), but not those included in other headers.
+Additionally, GCC provides @code{<stdatomic.h>}, even though it
+declares some functions with external linkage (which are provided in
+@code{libatomic}). On a few platforms, some of the headers not
+declaring functions with external linkage are instead obtained from
+the OS's C library, which may mean that they lack support for features
+from more recent versions of the C standard that are supported in
+GCC's own versions of those headers. On some platforms, GCC provides
+@code{<tgmath.h>} (but this implementation does not support interfaces
+added in C23).
+
+To use the facilities of a hosted environment, and some of the
+facilities required in a freestanding environment by C23, you need to
+find them elsewhere (for example, in the GNU C library).
+@xref{Standard Libraries,,Standard Libraries}.
Most of the compiler support routines used by GCC are present in
@file{libgcc}, but there are a few exceptions. GCC requires the
diff --git a/gcc/doc/trouble.texi b/gcc/doc/trouble.texi
index 15ced5f2da55..a2e6de43edb4 100644
--- a/gcc/doc/trouble.texi
+++ b/gcc/doc/trouble.texi
@@ -494,10 +494,12 @@ as to use the proper set, but you'll have to do this by
hand.
@section Standard Libraries
@opindex Wall
-GCC by itself attempts to be a conforming freestanding implementation.
+GCC by itself attempts to provide the compiler part of a conforming
+implementation, but only a limited subset of the library part of such
+an implementation.
@xref{Standards,,Language Standards Supported by GCC}, for details of
-what this means. Beyond the library facilities required of such an
-implementation, the rest of the C library is supplied by the vendor of
+what this means. Beyond the limited library facilities described
+there, the rest of the C library is supplied by the vendor of
the operating system. If that C library doesn't conform to the C
standards, then your programs might get warnings (especially when using
@option{-Wall}) that you don't expect.
--
Joseph S. Myers
josmy...@redhat.com
