[COMMITTED] Restore documentation for const/volatile functions [PR107942]
Checks
Commit Message
In r5-7698-g8648c55f3b703a I accidentally removed the documentation of
GCC's special interpretation of const/volatile qualifiers on functions
from the function attributes section, thinking this was just a
bit-rotten leftover from old versions of GCC. PR107942 points out
that this functionality is still present even though the docs are now gone.
I decided this material didn't really belong in the function
attributes discussion, but a new subsection in the general list of GCC
extensions to the C language. And I agree with the comment in the
issue that we shouldn't really recommend this usage any more.
gcc/ChangeLog
PR c/107942
* doc/extend.texi (C Extensions): Add new section to menu.
(Function Attributes): Move dangling index entries to....
(Const and Volatile Functions): New section.
---
gcc/doc/extend.texi | 37 +++++++++++++++++++++++++++++++++++--
1 file changed, 35 insertions(+), 2 deletions(-)
@@ -70,6 +70,7 @@ extensions, accepted by GCC in C90 mode and in C++.
* Character Escapes:: @samp{\e} stands for the character @key{ESC}.
* Alignment:: Determining the alignment of a function, type or variable.
* Inline:: Defining inline functions (as fast as macros).
+* Const and Volatile Functions :: GCC interprets these specially in C.
* Volatiles:: What constitutes an access to a volatile object.
* Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler.
* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
@@ -2522,8 +2523,6 @@ the enclosing block.
@section Declaring Attributes of Functions
@cindex function attributes
@cindex declaring attributes of functions
-@cindex @code{volatile} applied to function
-@cindex @code{const} applied to function
In GNU C and C++, you can use function attributes to specify certain
function properties that may help the compiler optimize calls or
@@ -10397,6 +10396,40 @@ The definition in the header file causes most calls to the function
to be inlined. If any uses of the function remain, they refer to
the single copy in the library.
+@node Const and Volatile Functions
+@section Const and Volatile Functions
+@cindex @code{const} applied to function
+@cindex @code{volatile} applied to function
+
+The C standard explicitly leaves the behavior of the @code{const} and
+@code{volatile} type qualifiers applied to functions undefined; these
+constructs can only arise through the use of @code{typedef}. As an extension,
+GCC defines this use of the @code{const} qualifier to have the same meaning
+as the GCC @code{const} function attribute, and the @code{volatile} qualifier
+to be equivalent to the @code{noreturn} attribute.
+@xref{Common Function Attributes}, for more information.
+
+As examples of this usage,
+
+@smallexample
+
+/* @r{Equivalent to:}
+ void fatal () __attribute__ ((noreturn)); */
+typedef void voidfn ();
+volatile voidfn fatal;
+
+/* @r{Equivalent to:}
+ extern int square (int) __attribute__ ((const)); */
+typedef int intfn (int);
+extern const intfn square;
+@end smallexample
+
+In general, using function attributes instead is preferred, since the
+attributes make both the intent of the code and its reliance on a GNU
+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 Volatiles
@section When is a Volatile Object Accessed?
@cindex accessing volatiles