Doc: Move builtin documentation to a new chapter [PR42270]

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.

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 371e82a6852f27fc8316454ebe9273d1a5311d4e..386b6b0f5b1df08448fc65df030ed30ed8f99a41 100644 (file)
--- 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 ba26bf8a42952f68745dd7f2e071b5d53518c477..3b7b289c325ac69568779af98b4c9ed856d562ba 100644 (file)
--- 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