This is part of an incremental effort to make the documentation for
GCC extensions better organized by grouping/rearranging sections by
topic.
I was originally intending to consolidate all the sections documenting
builtins as subsections of a new container section within the C
extensions chapter, but I ran into a technical limitation of Texinfo:
it only supports sectioning depth up to @subsubsection, and we already
had quite a few of those in the target-specific builtins sections. So
instead I have pulled all the existing sections out into a new
chapter. This actually makes sense since some of the builtins are
specific to C++ anyway and are not C language extensions at all.
Subsequent patches in this series will move things around within the
new chapter; this one just adds the new container node and adjusts
the menus.
gcc/ChangeLog
PR other/42270
* doc/extend.texi (C Extensions): Move menu items for
builtin-related sections to...
(Built-in Functions): New chapter.
* doc/gcc.texi (Introduction): Add menu entry for new chapter.
---
gcc/doc/extend.texi | 51 ++++++++++++++++++++++++++++++++-------------
gcc/doc/gcc.texi | 1 +
2 files changed, 37 insertions(+), 15 deletions(-)
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 371e82a6852..386b6b0f5b1 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -36,21 +36,6 @@ extensions, accepted by GCC in C90 mode and in C++.
* Using Assembly Language with C:: Instructions and extensions for interfacing
C with assembler.
* Syntax Extensions:: Other extensions to C syntax.
* Semantic Extensions:: GNU C defines behavior for some non-standard
constructs.
-* Nonlocal Gotos:: Built-ins for nonlocal gotos.
-* Constructing Calls:: Built-ins for dispatching a call to another function.
-* Return Address:: Getting the return or frame address of a function.
-* Stack Scrubbing:: Stack scrubbing internal interfaces.
-* Vector Extensions:: Using vector instructions through built-in functions.
-* __sync Builtins:: Legacy built-in functions for atomic memory access.
-* __atomic Builtins:: Atomic built-in functions with memory model.
-* Integer Overflow Builtins:: Built-in functions to perform arithmetics and
- arithmetic overflow checking.
-* x86 specific memory model extensions for transactional memory:: x86 memory
models.
-* Object Size Checking:: Built-in functions for limited buffer overflow
- checking.
-* New/Delete Builtins:: Built-in functions for C++ allocations and
deallocations.
-* Other Builtins:: Other built-in functions.
-* Target Builtins:: Built-in functions specific to particular targets.
@end menu
@node Additional Numeric Types
@@ -14217,6 +14202,42 @@ extension explicit. Additionally, using @code{const}
and
@code{volatile} in this way is specific to GNU C and does not work in
GNU C++.
+@node Built-in Functions
+@chapter Built-in Functions Provided by GCC
+@cindex Built-in Functions
+
+GCC provides a very large number of implicitly-declared built-in
+functions that are typically inlined by the compiler. Some of these
+builtins directly correspond to standard library routines, while
+others provide the underlying functionality needed to implement
+features provided by library functions or similar ``glue'' between GCC
+and other programming languages or libraries. Others are
+target-specific, providing direct access to instructions that have no
+direct C equivalents without the need to write assembly language. There
+are also builtins to support various kinds of runtime error checking.
+
+Most builtins have names prefixed with @samp{__builtin_}. Except as
+otherwise documented, all built-in functions are available from any
+of the C family languages supported by GCC.
+
+@menu
+* Nonlocal Gotos:: Built-ins for nonlocal gotos.
+* Constructing Calls:: Built-ins for dispatching a call to another function.
+* Return Address:: Getting the return or frame address of a function.
+* Stack Scrubbing:: Stack scrubbing internal interfaces.
+* Vector Extensions:: Using vector instructions through built-in functions.
+* __sync Builtins:: Legacy built-in functions for atomic memory access.
+* __atomic Builtins:: Atomic built-in functions with memory model.
+* Integer Overflow Builtins:: Built-in functions to perform arithmetics and
+ arithmetic overflow checking.
+* x86 specific memory model extensions for transactional memory:: x86 memory
models.
+* Object Size Checking:: Built-in functions for limited buffer overflow
+ checking.
+* New/Delete Builtins:: Built-in functions for C++ allocations and
deallocations.
+* Other Builtins:: Other built-in functions.
+* Target Builtins:: Built-in functions specific to particular targets.
+@end menu
+
@node Nonlocal Gotos
@section Nonlocal Gotos
@cindex nonlocal gotos
diff --git a/gcc/doc/gcc.texi b/gcc/doc/gcc.texi
index ba26bf8a429..3b7b289c325 100644
--- a/gcc/doc/gcc.texi
+++ b/gcc/doc/gcc.texi
@@ -144,6 +144,7 @@ Introduction, gccint, GNU Compiler Collection (GCC)
Internals}.
* C Implementation:: How GCC implements the ISO C specification.
* C++ Implementation:: How GCC implements the ISO C++ specification.
* C Extensions:: GNU extensions to the C language family.
+* Built-in Functions:: Library functions built in to GCC.
* C++ Extensions:: GNU extensions to the C++ language.
* Objective-C:: GNU Objective-C runtime features.
* Compatibility:: Binary Compatibility
--
2.34.1
